| Prev | Chapter 8. Engineering Standards | Next |
|---|
By michael@arsdigita.com and +
To ensure consistency (and its collateral benefit, maintainability), we define and adhere to standards in the following areas: -
+
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.
Under the page root (and the template root if using the Style package): -
For naming files that enable a specific action on an object, use this format:
+
For naming files that enable a specific action on an object, use this format:
object-verb.extension -
+
For example, the page to erase a user's portrait from the database is /admin/users/portrait-erase.tcl.
However, modules typically deal with only one primary type of object - e.g., the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on. Example: the user pages for the Bookmarks module live in the /bookmarks/ directory, and so there is no need to name the bookmark editing page with a redundant url: /bookmarks/bookmark-edit.tcl. Instead, we omit the object type, and use this convention: -
+
verb.extension -
+
Thus, the page to edit a bookmark is /bookmarks/edit.tcl. -
For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:
+
For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:
one.extension -
+
For example, the page to view one bookmark is /bookmarks/one.tcl. Note that no verb is necessary for display-type files. -
Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:
+
Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:
object.extension -
+
For example, the page to view the properties of an ecommerce product is /ecommerce/product.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)
+
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 use a three-step page flow when taking user information:
Present a form to the user
Present a confirmation page to the user
Perform the database transaction, then redirect
Put data model files in /www/doc/sql, and name them for the modules towards which they are used: -
+
module.sql -
+
In the Tcl library directory:
For files that contain module-specific procedures, use the -convention:
+convention:
module-procs.tcl -
For files that contain procedures that are part of the core ACS, -use the convention:
+
For files that contain procedures that are part of the core ACS, +use the convention:
ad-description-procs.tcl -
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 @@ -68,17 +68,17 @@ (/top-level-dir/). If linking to the directory in which the page is located, use the empty string (""), which browsers will resolve correctly. -
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.
@@ -94,7 +94,7 @@ </p>This can be at the top or bottom of the file. -
Using ad_page_contract+
Using ad_page_contractFor 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 @@ -141,7 +141,7 @@ QQvariables, which were automatically created by ad_page_variables and set_the_usual_form_variables. The use of bind variables makes such previous variable syntax obsolete. -
+
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 @@ -156,7 +156,7 @@ @author John Doe (jdoe@arsdigita.com) @cvs-id file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp } -
+
For SQL and other non-Tcl source files, the following file header structure is recommended:
-- path relative to the ACS root directory
@@ -170,7 +170,7 @@
Of course, replace "--" with the comment delimiter appropriate for the language in which you are programming. -
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 @@ -226,7 +226,7 @@ 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. -