Template rules

Basically, a template is just a textual file. The Header template and Content template lines in the example in the previous chapter are replaced by the content of the template files. External references in the template files are substituted with the values of the referred definitions. The following types of external references are possible:

• References to DATA_RETRIEVAL and KEY_RETRIEVAL calls (the name of the function). These take the form @(ENTRY:RETRIEVAL), and are replaced by the DATA_RETRIEVAL or KEY_RETRIEVAL value as defined in the DID, depending on whether a data-retrieval of key-retrieval is performed.
• References to entry-specific definitions in the DEFINE section of the DID. These take the form @(ENTRY:<name>), and are replaced by the corresponding value in the DEFINE section in the DID. Note that the name 'RETRIEVAL' is predefined (see the previous item). Also note that these defines are shared for key-retrieval and data-retrieval.
  Typically, the DID DEFINE section contains a definition that specifies the format of the parameters (if applicable) for the particular entry (for example in a PARAMS key). In this definition one has to define the structure in which the parameters are passed to the data retrieval and key retrieval call. In this definition one can refer to the parameters defined in the DEFINE_PARAMETERS section of the entry via @(PAR:<name_parameter>).
• References to entry parameters. These take the form @(PAR:<name>) or @(PAR:<number>). They are replaced by the textual representation of the corresponding entry parameter. This textual representation is 'escaped' according to XML rules: '<', '>', ''', '"', and '&' are replaced by their XML escape sequences.
  It is not likely that one needs to refer directly to parameters from a template, as the number and type of parameters probably differs for each entry. It is more likely that the parameters are referred to by ways of a definition in the DEFINE section of the entry. In this way it is possible to refer to different parameters from different entries by just using one reference in the template. See the previous item.
• References to textual DataManager settings. These take the form @(DM:<name>), and are replaced by the value of the setting. The setting name should be specified with its name as it is known in the ITP Administration Program. These references are typically used in the header template. They are sometimes also used in the content if it contains a section with connection information.
• There are two special @(…) values. When found in the template, they are substituted with the actual current time or date, and the setting in the connection configuration specifies the format of these values:
• @(DATE:<format>) instructs to insert the current system date. The format string indicates how to format it. It is a text string, in which the following character substitutions are made:
  • y – two-digit year representation
  • Y – four-digit year representation
  • m – one- or two-digit month representation
  • M – two-digit month representation
  • d – one- or two-digit day representation
  • D – two-digit day representation
  • other characters are preserved

  As an example:

  Y-M-D may expand to 2007-05-02, whereas m/d/y would result in 5/2/07.

• @(TIME:<format>) instructs to insert the current system time. The format string indicates how to format it. It is a text string, in which the following character substitutions are made:
  • h – one- or two-digit hour representation
  • H – two-digit hour representation
  • m or M – two-digit minutes representation
  • s or S – two-digit seconds representation
  • u – subsecond digit. The first u represents 1/10 of a second, the second u represents 1/100 of a second, and so forth
  • A – represents AM or PM. Inclusion automatically converts time representation to a 12-hour format, other characters are preserved

  Some examples:

  H:M may expand to 08:25, H:M A would expand to 08:25 AM, h:m:s,uuu could yield 8:25:33,013.

ENTRY:RETRIEVAL and ENTRY:<name> references have the same status. Expansion of references is strictly hierarchical, in the order Template - DM – ENTRY – PAR. This means:

• Templates may refer to all types of references.
• DM settings may refer to entry definitions and parameters, but not to other DM settings.
• Entry definitions may refer to parameters, but not to DM settings or other entry definitions.
• Parameters cannot contain references to any other definition.

The main reason for having a strict hierarchy is to avoid cyclic definitions.