ACS File Naming and Formatting Standards

By Michael Yoon and Aurelius Prochazka

+ +ACS File Naming and Formatting Standards

Prev	Chapter 11. Engineering Standards	Next

ACS File Naming and Formatting Standards

By Michael Yoon and Aurelius Prochazka

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

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 +
- 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 +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 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 - +/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: +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 +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 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 +/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
  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 +/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 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 +
  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, +module-procs.tcl +
- For files that contain procedures that are part of the core ACS, use the convention:
  -ad-description-procs.tcl -

URLs

+ad-description-procs.tcl +

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. +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 +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 +(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.

@@ -95,7 +95,7 @@
 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
@@ -119,32 +119,32 @@
     {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 +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 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 -optional. They do what you'd expect; values will not be +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 +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 -and sql_identifier will make sure that the values -supplied are integers/sql_identifiers. The integer flag +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 +notnull, both will accept the empty string. +
- 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 +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
@@ -165,56 +165,56 @@
 -- author
 -- created
 --
--- $Id$
+-- $Id$
 
```
-Of course, replace "--" with the comment delimiter +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 +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>
 
 <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 +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 +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 +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 @@ -225,7 +225,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. -

Tcl Library Files

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

($Id$)

Prev	Home	Next
Constraint naming standard	Up	PL/SQL Standards

docs@openacs.org

View comments on this page at openacs.org