object_type-verb.extension
For example, the page to erase a user's portrait from the database is
/admin/users/portrait-erase.tcl
.
object_type.extension
For example, the page to view the properties of an
/ecommerce/product.tcl
.
/bookmarks/
directory, it would be redundant to name the page for editing a
bookmark bookmark-edit.tcl
(which would result in the URL
bookmarks/bookmark-edit.tcl
. Instead, we omit the object
type, and use the convention:
verb.extension
Thus, the page to edit a bookmark is /bookmarks/edit.tcl
.
one.extension
For example, the page to view one bookmark is
/bookmarks/one.tcl
.
foobar.extension
(Step 1)
foobar-2.extension
(Step 2)
foobar-N.extension
(Step N)
where foobar
is determined by the above
rules.
Typically, we build three-step page flows:
/www/doc/sql
, and name them
using the convention:
module.sql
module-procs.tcl
ad-description-procs.tcl
user-delete
instead of
user-delete.tcl
), because they enhance maintainability.
Similarly, when linking to the index page of a directory, do not
explicitly name the index file (index.tcl
,
index.adp
, index.html
, etc.). Instead, use
just the directory name, for both relative links
(subdir/
) and absolute links
(/top-level-dir/
). If linking to the directory in which
the page is located, use the empty string (""
), which
browsers will resolve correctly.
File Headers
Include the standard header in all source files:
# path from server home/filename # # Brief description of the file's purpose # # author's email address, file creation date # # $Id$
Of course, replace "#
" with the comment delimiter
appropriate for the language in which you are programming, e.g.,
"--
" for SQL and PL/SQL.
Previously, the standard for headers in files under the page root was
to specify a path relative to the page root, e.g.
/index.tcl
, unlike all other files in the ACS, where the
path was relative to the server home directory, e.g.
/tcl/bboard-defs.tcl
. The current standard eliminates
this inconsistency, so that the path in every file header (under the
page root or not) is relative to the server home directory:
/www/index.tcl
instead of /index.tcl
.
Page Input
In addition to the standard file header, each page should start by:
ad_page_variables
(which supersedes set_the_usual_form_variables
)
page_validation
(which supersedes ad_return_complaint
)
page_content
), and then send it back to the browser with
one call to ns_return
. Make sure to release any database
handles (and any other acquired resources, e.g., filehandles) before
the call.
For example:
set db [ns_db gethandle] set page_content "[ad_header "Page Title"] <h2>Page Title</h2> <hr> <ul> " set selection [ns_db select $db sql] while { [ns_db getrow $db $selection] } { set_variables_after_query append page_content "<li>row information\n" } append page_content "</ul> [ad_footer]" ns_db releasehandle $db ns_return 200 text/html $page_content
Previously, the convention was to call ReturnHeaders
and
then ns_write
for each distinct chunk of the page. This
approach has the disadvantage of tying up a scarce and valuable
resource (namely, a database handle) for an unpredictable amount of
time while sending packets back to the browser, and so, it is to be
avoided in most cases. (On the other hand, for a page that requires an
expensive database query, it's better to call
ad_return_top_of_page
first, so that the user is not left to stare at an empty page while
the query is running.)
Local procedures (i.e., procedures defined and used only within one
page) should be prefixed with "module_
" and
should be used rarely, only when they are exceedingly useful.
All files that prepare HTML to display should end with [ad_footer] or
[module_footer]. If your module requires its own footer,
this footer should call ad_footer within it. Why? Because when we
adopt the ACS to a new site, it is often the case that the client will
want a much fancier display than ACS standard. We like to be able to
edit ad_header (which quite possibly can start a <table>) and
ad_footer (which may need to end the table started in ad_footer) to
customize the look and feel of the entire site.
Tcl Library Files
After the file header, the first line of each Tcl library file should
be a call to util_report_library_entry
.
The last line of each Tcl library file should be a call to
util_report_successful_library_load
.
Under discussion; will include: proc naming conventions
Data Modeling
Under discussion; will include: standard columns, naming conventions
for constraints.
on_which_table
column of the
general_permissions
table), normalize them into upper
case (following the convention established in the Oracle data
dictionary).