Index: openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 17 Oct 2001 20:39:25 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,104 +1,219 @@ -
-Table of Contents
By michael@arsdigita.com and -aure@arsdigita.com
+ + +
+ +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:
-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:
-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: -
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: -
-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 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 +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. -
Using ad_page_contract
+
+For non-library Tcl files (those not in the private Tcl directory), -use ad_page_contract +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 { @@ -116,35 +231,47 @@ {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 +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. -
Using ad_library
-For shared Tcl library files, use ad_library after +
+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 { @@ -153,51 +280,63 @@ @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 + +
+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> <ul> -" +" db_foreach get_row_info { select row_information from bar } { - append page_content "<li>row_information\n" + append page_content "<li>row_information\n" } -append page_content "</ul> +append page_content "</ul> -[ad_footer]" +[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 @@ -210,20 +349,56 @@ 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. -