<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"> <!-- file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp --> </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"> <p> Last Modified: file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp </p> </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>"] <h2><span class="emphasis"><em>Page Title</em></span></h2> <hr> <ul> " db_foreach get_row_info { select row_information from bar } { append page_content "<li><span class="emphasis"><em>row_information</em></span>\n" } append page_content "</ul> [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 <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. </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>