Data Specification Files

Introduction

Data specifications for dynamic templates are stored in plain text files in the document tree of the web server. Specifications files carry the data extension. They are formatted as XML documents. An XML element named template serves as the root of each data specification.

The core specification for a dynamic template consists of three tiers of information:

• Global properties. This includes basic information that applies to the template as a whole. Each global property is a child element of the root template element.

• Data sources. Each template may have zero or more sources of dynamic content. Data sources may obtain data directly from a database query, or from the results of a Tcl procedure. The properties for each data source are contained within a datasource element under the document root.

• Variables. Each data source makes one or more dynamic variables available for placing in a template. Each variable should be documented for the template writer. The properties for each variable are contained within the particular datasource element that determines its value.

The overall structure of the basic specification document looks like this (each property is described in the document below):

<template>

  <name>template namespace<name>
  <title>template title<title>
  <master>master template URL<master>
  <comment>template description</comment>

  <process>

  For each data source in the template:

  <datasource>

    <name>name<name>
    <type>query, param or eval</type>
    <structure>onevalue, onerow or multirow</structure>
    <condition>condition</condition>
    <comment>data source description</comment>

    For each variable in the data source: 
    <variable>
      <name>variable name<name>
      <comment>variable description</comment>
    </variable>

  </datasource>

  <process>

</template>

As is generally true for XML documents, white space is ignored in parsing the specification. Longer properties such as comments and queries can thus be broken into multiple lines to improve the legibility of the specification. Comments may NOT contain other markup tags, as this will invalidate the structure of the specification as an XML document.

Template properties

Basic template properties include the following:

• The name property should be a short token without white space, such as home or myworkspace. The template name defines an optional variable namespace for all data sources in the template. This is done to avoid collisions between variable names in subtemplates. See below for more information on variable names.

• The title property is optional and may be referenced as the title of the page. This property does not apply to subtemplates that specify page components that would never appear in a page of their own.

• The master property is optional and specifies the URL of the master template in which the current template should be embedded as content. If no master template is defined, then the default master template at /templates/master.adp is used.

  This property only applies when the requested URL matches that of the specification URL, after substituting adp for data. Other referenced templates are assumed to be subtemplates.

• The comment property may be used to provide a general description of the template for documentation purposes.

Data source properties

Data source properties include the following:

• The name property should be a short token without white space, such as userinfo. This property is used by the template writer to refer to variable(s) provided by the data source, in a manner dependent on the structure of the data (see the next property).

• The structure property specifies how the content provided by this data source is structured. There are three options:

  1. onevalue indicates that the data source makes available a single string. The template writer refers to this value in one of two ways:

     <var name="template_namespace.datasource_name">
     <var name="datasource_name">

  2. onerow indicates that the data source makes available a single set of values, represented internally as a single ns_set. The template writer refers to each variable in the set like so:

     <var name="template_namespace.datasource_name.variable_name">
     <var name="datasource_name.variable_name">

  3. multirow indicates that the data source makes available a list of sets of values, represented internally as a list of ns_sets. The template writer refers to variables from a multirow data source within the context of a multiple tag:

     <var name="template_namespace.datasource_name.variable_name">
     <var name="datasource_name.variable_name">

• The type property specifies the general origin of the data, and informs the template processor how to use the condition property. Options include:

  1. eval, in which case the value of the condition property is evaluated as a Tcl procedure with a return value matching the specified data structure for this data source.

  2. param, in which case the value of the condition property is the name of a CGI query parameter.

  3. query, in which case the value of the condition property is a database query that returns an appropriately structured result.

• The comment property may be used to provide a general description of the data source for documentation purposes.

Variable properties

There are two key variable properties:

• The name property refers to the naming of the variable by the data source. For onerow and multirow data sources, it corresponds internally to a key in the ns_set(s) that hold the dynamic content.

• The comment property is critical so that the template writer knows how to apply the variable.