File Standards

ACS Documentation : ACS Engineering Standards : File Standards
To ensure consistency (and its collateral benefit, maintainability), we define and adhere to standards in the following areas:

File Nomenclature

 Usually we organize our files so that they mainly serve one of the following three purposes:
  • displaying objects and their properties
  • manipulating or acting on objects in some way (by creating, editing, linking, etc)
  • housing procedures, packages, data models and other prerequisite code Essentially, we want our files named in a fashion that reflects their purpose.

    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 and Page Input

    Include the appropriate standard header in all scripts. The first line should be a comment specifying the file path relative to the ACS root directory. e.g. 
    # /www/index.tcl
    or 
    # /tcl/module-defs.tcl

    For static content files (html or adp), include a CVS identification tag as a comment at the top of the file, e.g. 

    <!-- file-standards.html,v 1.2 2001/02/26 20:41:05 bquinn Exp -->

    In addition, all static HTML files, documentation and other pages should have a visible CVS ID stamp, at least during development. These can be removed at release times. This should take the form of a line like this: 

    <p&gr;
Last Modified: file-standards.html,v 1.2 2001/02/26 20:41:05 bquinn Exp
</p&gr;

    This can be at the top or bottom of the file.

    Using ad_page_contract

    For non-library Tcl files (those not in the private Tcl directory), use ad_page_contract after the file path comment (this supersedes set_the_usual_form_variables and ad_return_complaint). Here is an example of using ad_page_contract, which serves both documentation and page input validation purposes: 
    
# www/register/user-login-2.tcl

ad_page_contract {
    Verify the user's password and issue the cookie.
    
    @param user_id The user's id in users table.
    @param password_from_from The password the user entered.
    @param return_url What url to return to after successful login.
    @param persistent_cookie_p Specifies whether a cookie should be set to keep the user logged in forever.
    @author John Doe (jdoe@arsdigita.com)
    @cvs-id file-standards.html,v 1.2 2001/02/26 20:41:05 bquinn Exp
} {
    user_id:integer,notnull
    password_from_form:notnull
    {return_url {[ad_pvt_home]}}
    {persistent_cookie_p f}
}

    Salient features of ad_page_contract:

     

    Using ad_library

    For shared Tcl library files, use ad_library after the file path comment. Its only argument is a doc_string in the standard (javadoc-style) format, like ad_page_contract. Don't forget to put the @cvs-id in there. Here is an example of using ad_library: 
    
# tcl/wp-defs.tcl

ad_library {
    Provides helper routines for the Wimpy Point module.

    @author John Doe (jdoe@arsdigita.com)
    @cvs-id file-standards.html,v 1.2 2001/02/26 20:41:05 bquinn Exp
}

     

    Non-Tcl Files

    For SQL and other non-Tcl source files, the following file header structure is recommended: 
    
-- path relative to the ACS root directory
--
-- brief description of the file's purpose
--
-- author
-- created
--
-- $Id$
    Of course, replace "--" with the comment delimiter appropriate for the language in which you are programming.

     

    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 doc_return, which will call db_release_unused_handles prior to executing ns_return, effectively combining the two operations.

    For example: 

    
set page_content "[ad_header "Page Title"]

<h2>Page Title</h2>

<hr>

<ul>
"

db_foreach get_row_info {
    select row_information 
    from bar
} {
    append page_content "<li>row_information\n"
}

append page_content "</ul>

[ad_footer]"

doc_return 200 text/html $page_content

    The old 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 should 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 adapt the ACS to a new site, it is often the case that the client will want a much fancier display than the 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

    Further standards for Tcl library files are under discussion; we plan to include naming conventions for procs.

    michael@arsdigita.com
    aure@arsdigita.com
         		Last Modified: file-standards.html,v 1.2 2001/02/26 20:41:05 bquinn Exp