{/doc/acs-templating {ACS Templating}} {Template Designer Guide} Template Designer Guide <master>

## Designer Guide

Templating System : Designer Guide

### Overview

Templates are the primary means for separating the work of developers and designers. A template is written by a designer and consists largely of static HTML (or other markup). The template author uses a small set of special markup tags to reference dynamic data prepared by the developer.The tags allow authors to accomplish four basic tasks that are not possible with standard HTML:

- Embed a dynamic variable in a template (`var`).
- Repeat a template section for each object in a dynamic list of objects (`multiple`, `grid`).
- Output different template sections depending on the value of one or more dynamic variables (`if`).
- Provide a mechanism for building complete pages from multiple component templates (`include`).

A reasonably skilled template author should be able to implement a template without any assistance from the developer, other than assuring that the proper dynamic data is accessible.

### Concepts

This section introduces the basic concepts underlying the use of template tags in ACS 4.0.

#### Variable Substitution

Much like the mail merge feature of a word processor, template authors must use special tags to position each piece of dynamic data within the layout. Each template is associated with a data dictionary that lists all available data sources.

See Variable Substitution.

#### Use of Components

To speed development and ensure consistency of design, template authors are encouraged to assemble pages from distinct component templates that may be recycled in different contexts. One typical practice is to build a "master" template for an entire section of a site, with a common header, footer and sidebar layout. For each page request, the "content" template is incorporated dynamically into a specified area of the master template, usually a table cell.

(graphic)

Another common practice is to build small reusable templates that may be included in other templates as logical components. This may be useful for common "widgets" such as search boxes or lists of related links, as well as for building configurable portal pages where users may assemble different types of content to their liking.

(graphic)

See `include` and `master`. See also Building reusable layout components and Using master templates.

#### Property Declarations

Template authors need a simple mechanism for declaring properties within the templates. The most common use of such properties is for configuring elements of an enclosing master template, such as the title, navigation links, and whether to include a search box. The data dictionary specifies available properties as well as the set of valid values when appropriate.

(graphic)

See `property`.

#### Conditional Insertion

Designers often need to tailor the layout depending on the specific data being presented. For example, when presenting a list of library books that a user has checked out, the designer might want to highlight the overdue ones in red.

See `if..else`.

#### Iteration

Dynamic pages often present lists of values or records, each of which typically represents the results of a database query. Template authors must have a way to iterate over each value or record in such a list and format it appropriately. In the simplest scenario, the exact HTML is repeated with each iteration. However, template authors often need to vary the design depending on the context. For example:

1. First and last items may be formatted differently from items in between.

2. Special breaks may be required when a particular value changes. For example, a query may return the name and office of all employees in a company, and the designer may wish to insert a subheading for each office.

3. Colors or patterns may alternate between items. For example, the designer may want to have alternate between white and gray bands in a table.

To accommodate these type of scenarios, the template parser sets some additional variables that the designer can reference to vary the layout from item to item.

See `multiple`, `group`, `grid`.

### Notes

- Template tags are processed by the server each time a page is requested. The end result of this processing is a standard HTML page that is delivered to the user. Users do not see template tags in the HTML source code of the delivered page.

- With normal usage, the use of dynamic tags tends to increase the amount of whitespace in the final HTML as compared to the template. This usually does not affect how browsers display the page. However, if a page layout depends on the presence or absence of whitespace between HTML tags for proper display, then special care must be taken with dynamic tags to avoid adding whitespace.

  When placed on a line by themselves, tags that are containers for template sections (`grid`, `if`, and `multiple`) will cause newlines to be added to the page at the beginning and end of the section. This can be avoided by crowding the start and end tags like so:

      <td><if %x% eq 5><img src="five.gif"></if>
      <else><img src="notfive.gif"></else></td>

  Note that this should not be done unless necessary, since it reduces the legibility of the template to others who need to edit the template later.

- Caution: Do not write to the connection. Specifically, if you must use the `<% %>` tag, do not call `ns_puts`, because it will not work the same way as in AOLserver's ADP pages.

Last modified: Mon Oct 2 14:12:08 EDT 2000