| -Prev | -Chapter 6. Engineering Standards | -Next - | -
|---|
-
+
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.
+
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:
---object-verb.extension -
+
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 - +
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 -
+
+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:
---one.extension -
+
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:
---object.extension -
+
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)
-where foobar is determined by the above +
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 +
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 -
+
+module.sql +
In the Tcl library directory: -
-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 -
-File names also appear within pages, as linked URLs and +
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 +
+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 @@ -164,56 +68,40 @@ (/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. -
-+<!-- file-standards.html,v 1.2 2000/09/19 07:22:45 ron 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> Last Modified: file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp </p> --+
This can be at the top or bottom of the file. -
-+
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 { @@ -231,47 +119,35 @@ {return_url {[ad_pvt_home]}} {persistent_cookie_p f} } --+
Salient features of ad_page_contract: -
-A mandatory documentation string is the first argument. This has -the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the recieved variables and any necessary explanations.
The second argument specifies the page +
A mandatory documentation string is the first argument. This has +the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the recieved variables and any necessary explanations.
The second argument specifies the page inputs. The syntax for switches/flags (e.g. multiple-list, array, etc.) uses a colon (:) followed by any number of flags separated by commas (,), e.g. foo:integer,multiple,trim. In particular, multiple and array are the flags that correspond to the old -ad_page_variables flags.
There are new flags: trim, notnull and +ad_page_variables flags.
There are new flags: trim, notnull and optional. They do what you'd expect; values will not be trimmed, unless you mark them for it; empty strings are valid input, unless you specify notnull; and a specified variable will be considered required, -unless you declare it optional.
-ad_page_contract can do validation for you: the flags integer +unless you declare it optional.
ad_page_contract can do validation for you: the flags integer and sql_identifier will make sure that the values supplied are integers/sql_identifiers. The integer flag will also trim leading zeros. Note that unless you specify notnull, both will accept the empty string. -
Note that ad_page_contract does not generate +
Note that ad_page_contract does not generate 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 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 { @@ -280,43 +156,32 @@ @author John Doe (jdoe@arsdigita.com) @cvs-id file-standards.html,v 1.2 2000/09/19 07:22:45 ron 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 ++-- path relative to the ACS root directory -- --- brief description of the file's purpose +-- brief description of the file's purpose -- --- author --- created +-- author +-- created -- -- $Id$ --+
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 db_release_unused_handles prior to executing ns_return, effectively combining the two operations. -
-+
For example: -
--set page_content "[ad_header "Page Title"] ++set page_content "[ad_header "Page Title"] -<h2>Page Title</h2> +<h2>Page Title</h2> <hr> @@ -327,16 +192,15 @@ select row_information from bar } { - append page_content "<li>row_information\n" + 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 @@ -349,56 +213,22 @@ 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 +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, +[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. -
-