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.
