Documenting Data Sources
Templating System : Developer Guide : User GuideEffective 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 namecomments
- 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:
-
Possible form entry types include text (or textentry), date, checkbox, radio, select, multiselect and textbox# @data_input name form comments # @input name <type of form entry> comments
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.