Templates

A template is a BSCW document of MIME type ‘Document Template’ (text/x-bscw-template). Templates should be created using a normal ASCII text editor (e.g., Windows Notepad), not a text processing system such as Microsoft Word. When uploading a template document into a document set, the MIME type ‘Document Template’ has to be specified. Other­wise the evaluation process does not recognize the document as a template.

We recommend that you use an extension such as .dtm for template documents, so they may easily be identified within folder listings. A template is represented by the icon .

There are two classes of templates: templates of the first class create a document directly during the evaluation process. A template belongs to this class if the evaluation parameter document is specified for the template.

Templates of the second class indirectly contribute to the creation of a document because they are referred to from other templates. A template belongs to this class if the evaluation pa­rameter document is missing.

Besides the evaluation parameter document, there is another evaluation parameter template which indicates a template into which the entity definitions of the present template will be inserted during the evaluation. Both evaluation parameters specify document names within the document set.

The evaluation parameters may be regarded as a sort of entities belonging to templates. They may be set (and reset) using   Eval Parameters  in the action menu of a template document.

The following rules apply during the evaluation process:

(a) Evaluation parameter document is specified for template X

The evaluation process will evaluate template X and create a document with the name speci­fied by the parameter document. In this case, the template consists, in general, of text and of entity references which are resolved by the evaluation process before the document is inserted into the document set.

(b) Evaluation parameters document and template are specified for template X

The evaluation process will evaluate the template specified by the parameter template and create a document with the name specified by the parameter document. During the evaluation process, the entity definitions of template X are used. In this case, the tem­plate consists, in general, of entity definitions, which are inserted into the template specified by the parameter template by the evaluation process before the document is inserted into the document set.

(c) No evaluation parameter is specified for template X

The evaluation process will evaluate template X only if it is referred to by another template via the template parameter (see case (b) above) or if it is embedded in an­other template (see below). In this case, template X essentially consists of text con­taining references to entities that will be evaluated by the evaluation process.

(d) Evaluation parameter template is specified for template X

The evaluation process will evaluate template X only if it is referred to by another template via the template parameter (see case (b) above) or if it is embedded in an­other template (see below). In this case, template X consists of entity definitions that are inserted into the tem­plate specified by the parameter template by the evaluation process.

Embedded templates

Templates may be embedded in other templates, i.e. a template may be used by several other templates. A template is embedded using the following notation:

#(name-of-template)#

During the evaluation process, the embedded template is evaluated and the resulting text re­places the reference. The reference to an embedded template may also contain path informa­tion to locate the template in the folder hierarchy of the document set. Path names are consid­ered to be relative to the location of the referencing template. Templates with entity defini­tions may also be embedded in another template. In this case, the result of the evaluation process will be inserted, too.

Using the notation

#(name-of-template, name-of-combined-template)#

one may combine an embedded template with another template that contains entity defini­tions. At the point of evaluation of the embedded template, the entity definitions of the com­bined template will be evaluated first and inserted into the embedded template; only then the embedded template will be evaluated and inserted. In this way, one can combine templates defining entities with different templates in various contexts.

Names of embedded templates may contain the wildcard characters ‘*’ (arbitrary string) and ‘?’ (arbitrary character). In this case, all templates that match the pattern will be embedded one after another. The expression

#(&(content_dir);/faq/question*.dtm, &(template_dir);/faq.dtm)#

will cause all templates in the directory &(content_dir);/faq whose name matches the pattern question*.dtm to be combined with the template &(template_dir);/faq.dtm and then to be evaluated and inserted.