Documenting Data Sources

Effective coordination between the developer and designer is one of the major challenges of any publishing team. The templating system provides a set of simple documentation directives so that developer comments on data sources can be extracted from Tcl scripts and summarized for non-technical members of the publishing team automatically.

To take advantage of this capability, the developer must structure comments on a datasource in the following way:

# @datasource cars multirow
# The cars owned by a user.
# @column make The make of the car, i.e. Toyota
# @column model The model of the car, i.e. Camry
# @column year The year of manufacture

# @datasource name onevalue
# the name of the user

# @data_input add_entry form
# a form for adding entries to user's address book 
# @input first_names text 
# entry subject's first and middle names
# @input last_name text
# @input title text form of address for entry subject
# @input birthday date birthdate w/ "MONTH DD YYYY" format
# @input gender radio
# either "m" for male or "f" for female

A few formatting guidelines:

• all datasources (onevalues, onelists, multilists, multirows) are documented with the datasource directive, their name, the type of datasource, and then necessary comments:

  # @datasource name <type of datasource> comments

• multirow datasources are followed with a series of column directives, column names, and associated explanations:

  # @column name comments

• forms are documented with the data_input directive, and are also followed with a series of input directives with the name and type of input widgets, and necessary comments:

  	# @data_input name form comments
  	# @input name <type of form entry> comments
  	

  Possible form entry types include text (or textentry), date, checkbox, radio, select, multiselect and textbox

  Once the templates have been enabled, the designer can simply visit the URL from which the page will be served, substituting acs with the dat extension.

  ---

  templating@arsdigita.com