<% # # /www/doc/standards.adp # # ACS standards # # michael@arsdigita.com, March 2000 # # standards.adp,v 3.3.2.5 2000/03/17 08:29:54 michael Exp # proc proc_doc_link { proc_name } { return "$proc_name" } %> Standards

Standards

for the ArsDigita Community System
To ensure consistency (and its collateral benefit, maintainability), we define and adhere to standards in the following areas:

File Naming

Under the page root (and the template root if using the Style package): In the Tcl library directory:

URLs

File names also appear within pages, as linked URLs and form targets. When they do, always use abstract URLs (e.g., 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:
  1. specifying the input it expects (in essence, its parameter list) with a call to <%= [proc_doc_link ad_page_variables] %> (which supersedes <%= [proc_doc_link set_the_usual_form_variables] %>)
  2. validating its input with a call to <%= [proc_doc_link page_validation] %> (which supersedes <%= [proc_doc_link ad_return_complaint] %>)

Page Construction

Construct the page as one Tcl variable (name it 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 <%= [proc_doc_link 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 <%= [proc_doc_link util_report_library_entry] %>.

The last line of each Tcl library file should be a call to <%= [proc_doc_link util_report_successful_library_load] %>.

Under discussion; will include: proc naming conventions

Data Modeling

Under discussion; will include: standard columns, naming conventions for constraints.

Documentation

Under discussion.
michael@arsdigita.com
aure@arsdigita.com