Things to remember when developing on OpenACS

The goals of this document are:

• Help new and old developers to know guidelines when developing on OpenACS in a short doc. Its primary audience are new developers, but old developers may pick up a thing or two.
• Help developers read the real docs since the list will link to the real docs if possible.
• Hopefully start a chapter or section on the real docs if one of the item listed is not available from the real docs.

This document is NOT meant to:

• Serve as the primary documentation of OpenACS. Go read the docs at http://openacs.org/doc
• A list of tasks to do with the current code base. Some of the older codes base does not follow these guidelines. This list is meant to be a guideline for future development. For example changing an existing API name just to follow the guideline is highly discouraged.
• A complete list of guidelines. Its meant to be short. Maybe someone may make a complete list.

Much of the guidelines are gathered through OpenACS forums. I have initially categorized the list accoriding to the main areas of development in OpenACS which are: adp, tcl, sql and others

• Things to remember when developing ADP
• Things to remember when developing Tcl
• Things to remember when developing SQL and plSQL
• Other things to remember

• Avoid putting in tcl code on ADP pages if possible

  Although aolserver ADP supports this try to make use of OpenACS Templating or http://your.openacs/doc/acs-templating/. Try not to use <%= [proc_foo] %>, instead put into foo.tcl "set foo [proc_foo]" and put in the adp page "@foo@". Don't use tcl (e.g. <% if {$foo == 5} { %>) use OpenACS templating <if @foo_p@ eq 5>

• Pass the context_bar and title to the site master template

  Jeff Davis has started to clean up the master template of each package and the site master template. Ex:

      <property name="title">@title@</property>
      <property name="context_bar">@context_bar@</property>
      

• Avoid putting in HTML in tcl

  Try to make use of OpenACS Templating or http://your.openacs/doc/acs-templating/. If you can't avoid it try to isolate the HTML into a proc so editing the layout will be easier.

• Using namespace is encouraged

  Define your procs with with a namespace like "mypackage::foo_proc". Here is a dicussion about this. hopefully we can make a doc that describes about this more

• Use named parameters whenever possible

  Define named parameters on your procs so parameters will not be mixed up if somebody makes a mistake on passing the order of parameters. Also this makes the proc easier to add additional parameters in the future if needed. Use "ad_proc proc_name { {-parent_id pid} {-child_id cid} }" and not "ad_proc proc_name {pid cid}". This way developers will need to call proc stating explicitly what parameter "[proc_name -parent_id 1 -child_id 2]". we need to link this to a doc about ad_proc or something

• Do not use "==" in comparing strings

  Using "if { $string == "foo" }" is limited to the interger variable of Tcl. Read this thread as a reference. Instead make use of "if { [string equal "foo" $string] }".

• Delete the queries from your tcl files

  Since we are now using the query dispatcher it is encourage to make use of .xql files. If you use .xql files kindly delete the sql from the .tcl to avoid confusion. And place a "SQL" place holder on it. (ex. db_1row stmtname "SQL") link to QD doc

• Use ad_proc to define your tcl procs

  Make use of ad_proc. And make use of the self documentation facility of ad_proc. "ad_proc procname {} {Use this area to document} {}" This way the API browser will pick up your documentation automatically. What conventions are we still going to use? @author, @return, @see?

• Avoid using upvar

  Try to avoid using upvar. If needed pass in a parameter that specifies the upvar name. This way the one using your proc has option to name his/her variable. Ex.

      ad_proc upvaring {-upvar_name:required} {
          upvar $upvar_name local_var
      }
      

• Read the Tcl Style guide

  This is the Tcl styleguide (PDF), try to apply relevant guidelines. In particular chapter 4,5 and 7.

• Avoid the PG view/sequence trick - Postgres Only

  See this thread for more info. Can someone help me make a good writeup on this?

• Put a commnet next to each parameter name when calling plSQL functions with more than 3 parameters - Postgres Only

  You can put comments when you call postgres functions. Since postgres functions are determined by order its encouraged put the intent of each parameter.

      Example:
          select file_storage__new_file (
              :title,             -- title
              :folder_id,         -- parent_id
              :user_id,           -- creation_user
              :creation_ip,       -- creation_ip
              true                -- indb_p
          );
      

  Can someone point me to a doc that discusses about this

• plSQL functions must use "p_" as the prefix for supplied parameters and "v_" for local vars.

  Use the "p_" or "v_" prefix so its easy to find out what the varible is. An example declaration is shown below:

  Postgres
          p_name alias for $1;
          v_email foo_table.bar_column%TYPE;
      

  Oracle
          p_name in foo_table.bar_column%TYPE;
          v_email foo_table.bar_column%TYPE;
      

• Avoid declaring the local variable type explicitly

  When declaring local plSQL vars, don't declare the type explicitly. Don't write "v_foo varchar" instead write it this way "v_foo table_name.column_name%TYPE". someone please help on getting a link to sample code or doc?

• Make upgrade scripts if you are changing the datamodel

  Make upgrade scripts so people who used your package will not hunt you down when you put up an upgraded package with no upgrade script. Also increment the version number so APM will pick the upgrade scripts automatically. See this thread for more info.

• Try to make use of the package key on tcl api and db api

  When you great your tcl proc try to make use of packagekey::procname. Not mynamespace::procname. This also applies to db api. So use packagekey.dbapi.

• When naming boolean variables postfix it with _p

  Variables in adp, tcl and plsql that are boolean or acts as booleans should be postfixed with _p. (ex. foo_p, admin_p, etc.)

• It is encouraged to use CVS

  Its encouraged to use CVS for development. Also it is encouraged to use CVS keywords like $ID links to cvshome and Openacs cvs?

• Use return_url as the variable name that contains URL to redirect back to

  If you will be creating pages that will redirect back to from where a page flow is changed. Make use of the return_url as the variable name that will contain the URL of where you want to go back to. A good example are the registration pages. Also ad_return_url is a good way of making the return_url "set return_url [ad_return_url -urlencode]" need to link this to registration page tcl or something

Please email Jun Yamog for any comments, corrections, help, etc.