Standards

• File Naming
• File Headers
• Page Input
• Page Construction
• Tcl Library
• Data Modeling
• Documentation

• For naming files that enable a specific action on an object, use the convention:

  object_type-verb.extension

  For example, the page to erase a user's portrait from the database is /admin/users/portrait-erase.tcl.

• For naming files that display the properties of one object (rather than letting the user take a specific action), simply omit the verb, and use the convention:

  object_type.extension

  For example, the page to view the properties of an ecommerce product is /ecommerce/product.tcl.

• Typically, a module deals with one primary type of object, e.g., the Bookmarks module deals mainly with bookmarks. Since the user pages for the Bookmarks module live in the /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.

• Similarly, for naming files that display the properties of one primary-type object, use the convention:

  one.extension

  For example, the page to view one bookmark is /bookmarks/one.tcl.

• For naming files in a page flow, use the convention:
  • 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:

  1. Present a form to the user
  2. Present a confirmation page to the user
  3. Perform the database transaction, then redirect

• Put data model files in /www/doc/sql, and name them using the convention:

  module.sql

• For files that contain module-specific procedures, use the convention:

  module-procs.tcl

• For files that contain procedures that are part of the core ACS, use the convention:

  ad-description-procs.tcl

URLs

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

# 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

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] %>)

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

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