<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>ACS File Naming and Formatting Standards</title><meta name="generator" content="DocBook XSL Stylesheets V1.66.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter�12.�Engineering Standards"><link rel="previous" href="eng-standards-constraint-naming.html" title="Constraint naming standard"><link rel="next" href="eng-standards-plsql.html" title="PL/SQL Standards"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td><th width="60%" align="center">Chapter�12.�Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-filenaming"></a>ACS File Naming and Formatting Standards</h2></div></div></div><div class="authorblurb"><p>By Michael Yoon and Aurelius Prochazka</p>
          OpenACS docs are written by the named authors, and may be edited
          by OpenACS documentation staff.
        </div><p>
To ensure consistency (and its collateral benefit, maintainability),
we define and adhere to standards in the following areas:
</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-nomenclature"></a>File Nomenclature</h3></div></div></div><p>
Usually we organize our files so that they mainly serve one of the following three purposes:
</p><div class="itemizedlist"><ul type="disc"><li><p> displaying objects and their properties</p></li><li><p> manipulating or acting on objects in some way (by creating, editing, linking, etc)</p></li><li><p> housing procedures, packages, data models and other prerequisite code
Essentially, we want our files named in a fashion that reflects their purpose.</p></li></ul></div><p>

Under the page root (and the template root if using the <a href="style" target="_top">Style package</a>):
</p><div class="itemizedlist"><ul type="disc"><li><p>For naming files that enable a specific action on an object, use this format:</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em><tt class="computeroutput">object-verb.extension</tt></em></span>
</p></blockquote></div><p>
For example, the page to erase a user's portrait from the database is
<tt class="computeroutput">/admin/users/portrait-erase.tcl</tt>.
</p></li><li><p>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 <tt class="computeroutput">/bookmarks/</tt>
directory, and so there is no need to name the bookmark editing page with a redundant url: <tt class="computeroutput">/bookmarks/bookmark-edit.tcl</tt>. Instead, we omit the object type, and use this convention:
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em><tt class="computeroutput">verb.extension</tt></em></span>
</p></blockquote></div><p>
Thus, the page to edit a bookmark is <tt class="computeroutput">/bookmarks/edit.tcl</tt>.
</p></li><li><p>For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module -  use this convention:</p><div class="blockquote"><blockquote class="blockquote"><p>
<tt class="computeroutput">one.</tt><span class="emphasis"><em><tt class="computeroutput">extension</tt></em></span>
</p></blockquote></div><p>
For example, the page to view one bookmark is
<tt class="computeroutput">/bookmarks/one.tcl</tt>.  Note that no verb is necessary for display-type files.
</p></li><li><p>Otherwise, if the object to be displayed is not the primary feature of a module,  simply omit the verb and use the object name:</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em><tt class="computeroutput">object.extension</tt></em></span>
</p></blockquote></div><p>
For example, the page to view the properties of an
ecommerce product is
<tt class="computeroutput">/ecommerce/product.tcl</tt>.
</p></li><li><p>For naming files in a page flow, use the convention:</p><div class="itemizedlist"><ul type="circle"><li><p><span class="emphasis"><em><tt class="computeroutput">foobar.extension</tt></em></span> (Step 1)</p></li><li><p><span class="emphasis"><em><tt class="computeroutput">foobar-2.extension</tt></em></span> (Step 2)</p></li><li><p>...</p></li><li><p><span class="emphasis"><em><tt class="computeroutput">foobar-N.extension</tt></em></span> (Step N)</p></li></ul></div><p>
where <span class="emphasis"><em><tt class="computeroutput">foobar</tt></em></span> is determined by the above
rules.
</p><p>
Typically, we use a three-step page flow when taking user information:
</p><div class="orderedlist"><ol type="1"><li><p>Present a form to the user</p></li><li><p>Present a confirmation page to the user</p></li><li><p>Perform the database transaction, then redirect</p></li></ol></div></li><li><p>Put data model files in <tt class="computeroutput">/www/doc/sql</tt>, and name them
for the modules towards which they are used:
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em><tt class="computeroutput">module</tt></em></span><tt class="computeroutput">.sql</tt>
</p></blockquote></div></li></ul></div><p>
In the Tcl library directory:
</p><div class="itemizedlist"><ul type="disc"><li><p>For files that contain module-specific procedures, use the
convention:</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em><tt class="computeroutput">module</tt></em></span><tt class="computeroutput">-procs.tcl</tt>
</p></blockquote></div></li><li><p>For files that contain procedures that are part of the core ACS,
use the convention:</p><div class="blockquote"><blockquote class="blockquote"><p>
<tt class="computeroutput">ad-</tt><span class="emphasis"><em>description</em></span><tt class="computeroutput">-procs.tcl</tt>
</p></blockquote></div></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-urls"></a>URLs</h3></div></div></div><p>
File names also appear <span class="emphasis"><em>within</em></span> pages, as linked URLs and
form targets. When they do, always use <a href="abstract-url" target="_top">abstract
URLs</a> (e.g., <tt class="computeroutput">user-delete</tt> instead of
<tt class="computeroutput">user-delete.tcl</tt>), because they enhance maintainability.
</p><p>
Similarly, when linking to the index page of a directory, do not
explicitly name the index file (<tt class="computeroutput">index.tcl</tt>,
<tt class="computeroutput">index.adp</tt>, <tt class="computeroutput">index.html</tt>, etc.). Instead, use
just the directory name, for both relative links
(<tt class="computeroutput">subdir/</tt>) and absolute links
(<tt class="computeroutput">/top-level-dir/</tt>). If linking to the directory in which
the page is located, use the empty string (<tt class="computeroutput">""</tt>), which
browsers will resolve correctly.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-headers"></a>File Headers and Page Input</h3></div></div></div><p>
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.
</p><div class="blockquote"><blockquote class="blockquote"><p><tt class="computeroutput">
# /www/index.tcl
</tt></p></blockquote></div><p>
or
</p><div class="blockquote"><blockquote class="blockquote"><p><tt class="computeroutput">
# /tcl/module-defs.tcl
</tt></p></blockquote></div><p>
For static content files (html or adp), include a CVS identification tag as a
comment at the top of the file, e.g.  
</p><pre class="programlisting">
&lt;!-- file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp --&gt;
</pre><p>
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><pre class="programlisting">
&lt;p&gt;
Last Modified: file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp
&lt;/p&gt;
</pre><p>
This can be at the top or bottom of the file.
</p><div>Using ad_page_contract</div><p>
For non-library Tcl files (those not in the private Tcl directory),
use <a href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract"><tt class="computeroutput">ad_page_contract</tt></a>
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:
</p><pre class="programlisting">
# 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@example.com)
    @cvs-id file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp
} {
    user_id:integer,notnull
    password_from_form:notnull
    {return_url {[ad_pvt_home]}}
    {persistent_cookie_p f}
}
</pre><p>
Salient features of <tt class="computeroutput">ad_page_contract</tt>:
</p><div class="itemizedlist"><ul type="disc"><li><p>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. </p></li><li><p>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. <tt class="computeroutput">foo:integer,multiple,trim</tt>. In particular, <tt class="computeroutput">multiple</tt> and
<tt class="computeroutput">array</tt> are the flags that correspond to the old
<tt class="computeroutput">ad_page_variables</tt> flags.</p></li><li><p>There are new flags: <tt class="computeroutput">trim</tt>, <tt class="computeroutput">notnull</tt> and
<tt class="computeroutput">optional</tt>. 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.</p></li><li><p><tt class="computeroutput">ad_page_contract</tt> can do validation for you: the flags <tt class="computeroutput">integer</tt>
and <tt class="computeroutput">sql_identifier</tt> will make sure that the values
supplied are integers/sql_identifiers. The <tt class="computeroutput">integer</tt> flag
will also trim leading zeros. Note that unless you specify
<tt class="computeroutput">notnull</tt>, both will accept the empty string.
</p></li><li><p>Note that <tt class="computeroutput">ad_page_contract</tt> 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.
</p></li></ul></div><div>Using ad_library</div><p>
For shared Tcl library files, use <a href="tcl-doc.html#tcl-doc-ad-library" title="ad_library"><tt class="computeroutput">ad_library</tt></a> after
the file path comment. Its only argument is a doc_string in the
standard (javadoc-style) format, like
<tt class="computeroutput">ad_page_contract</tt>. Don't forget to put the @cvs-id in
there.  Here is an example of using ad_library:
</p><pre class="programlisting">
# tcl/wp-defs.tcl

ad_library {
    Provides helper routines for the Wimpy Point module.

    @author John Doe (jdoe@example.com)
    @cvs-id file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp
}
</pre><div>Non-Tcl Files</div><p>
For SQL and other non-Tcl source files, the following file header structure is recommended:
</p><pre class="programlisting">
-- <span class="emphasis"><em>path relative to the ACS root directory</em></span>
--
-- <span class="emphasis"><em>brief description of the file's purpose</em></span>
--
-- <span class="emphasis"><em>author</em></span>
-- <span class="emphasis"><em>created</em></span>
--
-- <a href="http://www.loria.fr/~molli/cvs/doc/cvs_12.html#SEC93" target="_top">$Id: eng-standards-filenaming.html,v 1.30.2.10 2005/03/01 00:15:52 joel Exp $</a>
</pre><p>
Of course, replace "<tt class="computeroutput">--</tt>" with the comment delimiter
appropriate for the language in which you are programming.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-pages"></a>Page Construction</h3></div></div></div><p>
Construct the page as one Tcl variable (name it
<tt class="computeroutput">page_content</tt>), and then send it back to the browser with
one call to <tt class="computeroutput">doc_return</tt>, which will call
db_release_unused_handles prior to executing ns_return, effectively
combining the two operations.
</p><p>
For example:
</p><pre class="programlisting">
set page_content "[ad_header "<span class="emphasis"><em>Page Title</em></span>"]

&lt;h2&gt;<span class="emphasis"><em>Page Title</em></span>&lt;/h2&gt;

&lt;hr&gt;

&lt;ul&gt;
"

db_foreach get_row_info {
    select row_information 
    from bar
} {
    append page_content "&lt;li&gt;<span class="emphasis"><em>row_information</em></span>\n"
}

append page_content "&lt;/ul&gt;

[ad_footer]"

doc_return 200 text/html $page_content
</pre><p>
The old convention was to call <tt class="computeroutput">ReturnHeaders</tt> and
then <tt class="computeroutput">ns_write</tt> 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

<tt class="computeroutput">ad_return_top_of_page</tt>

first, so that the user is not left to stare at an empty page while
the query is running.)
</p><p>
Local procedures (i.e., procedures defined and used only within one
page) should be prefixed with "<span class="emphasis"><em><tt class="computeroutput">module_</tt></em></span>" and
should be used rarely, only when they are exceedingly useful.
</p><p>
All files that prepare HTML to display should end with [ad_footer] or
[<span class="emphasis"><em>module</em></span>_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 &lt;table&gt;) and
ad_footer (which may need to end the table started in ad_footer) to
customize the look and feel of the entire site.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-tcllib"></a>Tcl Library Files</h3></div></div></div><p>
Further standards for Tcl library files are under discussion; we plan to 
include naming conventions for procs.
</p><div class="cvstag">($Id: eng-standards-filenaming.html,v 1.30.2.10 2005/03/01 00:15:52 joel Exp $)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a></td></tr><tr><td width="40%" align="left">Constraint naming standard </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> PL/SQL Standards</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/current/eng-standards-filenaming.html#comments">View comments on this page at openacs.org</a></center></body></html>