# Index Template Files

Index template files specify the format of the body of an HTML index file. They always begin with a `<BODY>` tag and end with a `</BODY>` tag. They contain the following information:

| Text & HTML | All characters that aren't part of a token, directive, or line continuation are sent directly to the generated index file. This includes text and HTML tags.
| Tokens | Tokens of the form "`${`name...`}`" are replaced with variable data, as described below. Tokens may appear anywhere in the text, at any position on a line, and may even span multiple lines.
| Directives | Directives are lines that begin with a '#' character. They contain instructions for processing the template file, as described below. Directives are always a single full line.
| Line continuation | If a '&' character appears as the last character on a line, the line will be joined to the next line in the generated index file (the '&' character and the end-of-line characters will be removed).

Index template files are specified by using the template option in the configuration file.

### Tokens

Tokens are placeholders for variable data which is inserted into the generated index file. The syntax of tokens is very similar to the syntax of HTML tags, except that the opening "<" is replaced by "${" and the closing ">" is replaced by "}". The token syntax is as follows:

> `${name}` or,
> `${name [attribute=value [attribute=value [...]]}`

Where,

> `name` |  | is the name of the token (case-insensitive).
> `attribute` |  | is the name of an attribute (case-insensitive).
> `value` |  | is the value of an attribute. If the attribute contains non-alphanumeric characters or spaces, then it should be enclosed in single or double quotes. You may use`\"` or`\'` to represent a quote within quotes, or use`\\` to represent a single backslash. You can also use`\n` to represent a line break (newline).

The following tokens are supported. Optional attributes are shown indented below their respective tokens.

`${nav}` | Inserts the appropriate navigational link buttons. These may consist of previous, back, and next links (in that order), as appropriate. See the ${prev}, ${back}, and ${next} tokens for more information. This token should normally appear on a line by itself.
`${back}` | Inserts a backlink to the parent directory (HTML). This normally displays the "home.gif" icon which is located in the icons directory, but it may display text instead, depending on the backlink type specified in the configuration file. It may also contain a block of JavaScript code.
`src=`iconRef | The image file that will be displayed as the button. If this attribute is not specified, it defaults to "`HOME.GIF`".
`attrib=`attributes | HTML attributes that will be included in the <IMG> tag. The SRC, WIDTH, and HEIGHT attributes are inserted automatically, and should not be included here. If this attribute is not specified, it defaults to "`BORDER=0 ALIGN=TOP`".
`${prev}` | Inserts a link button to the previous page of the index. This normally displays the "prev.gif" or "noprev.gif" button images which are located in the icons directory, but custom button images may be specified instead.
`src1=`iconRef | The image file that will be displayed when the button is enabled. If this attribute is not specified, it defaults to "`PREV.GIF`".
`src0=`iconRef | The image file that will be displayed when the button is disabled. If this attribute is not specified, it defaults to "`NOPREV.GIF`" if src1 is also not specified, or blank (empty) if src1 is specified.
`attrib=`attributes | HTML attributes that will be included in the <IMG> tag. The SRC, WIDTH, and HEIGHT attributes are inserted automatically, and should not be included here. If this attribute is not specified, it defaults to "`BORDER=0 ALIGN=TOP`".
`${next}` | Inserts a link button to the next page of the index. This normally displays the "next.gif" or "nonext.gif" button images which are located in the icons directory, but custom button images may be specified instead.
`src1=`iconRef | The image file that will be displayed when the button is enabled. If this attribute is not specified, it defaults to "`NEXT.GIF`".
`src0=`iconRef | The image file that will be displayed when the button is disabled. If this attribute is not specified, it defaults to "`NONEXT.GIF`" if src1 is also not specified, or blank (empty) if src1 is specified.
`attrib=`attributes | HTML attributes that will be included in the <IMG> tag. The SRC, WIDTH, and HEIGHT attributes are inserted automatically, and should not be included here. If this attribute is not specified, it defaults to "`BORDER=0 ALIGN=TOP`".
`${iconDir}` | Inserts the path to the icons directory (URL). This is normally used in the form "`${iconDir}/filename`".
`${icon}` | Inserts an HTML <IMG> tag at the current position, with the proper HEIGHT and WIDTH attributes. The tag will appear as follows: `<IMG SRC="`url`" WIDTH=`width `HEIGHT=`height`` attributes`>`. The url and attributes are specified (see below), and the width and height are obtained directly from the image file. The "src" attribute must be specified for this token.
`src=`iconRef | The name of an image file that currently exists in the icons directory. The full path will appear as the value of the SRC attribute in the <IMG> tag. The path will be the same as "`${iconDir}/`filename".
`attrib=`attributes | HTML attributes that will be included in the <IMG> tag. The SRC, WIDTH, and HEIGHT attributes are inserted automatically, and should not be included here.
`${img}` | Inserts an HTML <IMG> tag at the current position, with the proper HEIGHT and WIDTH attributes. The tag will appear as follows: `<IMG SRC="`url`" WIDTH=`width `HEIGHT=`height`` attributes`>`. The url and attributes are specified (see below), and the width and height are obtained directly from the image file. The "src" attribute must be specified for this token.
`src=`url | The URL that will appear as the value of the SRC attribute in the <IMG> tag. This should be a relative URL, and should reference an image file that currently exists in the file system.
`attrib=`attributes | HTML attributes that will be included in the <IMG> tag. The SRC, WIDTH, and HEIGHT attributes are inserted automatically, and should not be included here.
`${desc}` | Inserts the description of the current directory, or blank if there is no description. If the "links" attribute is not specified, it defaults to the value specified by the webLinks configuration option.
`links` [`=yes`] | Enables the webLinks feature for this description.
`links=no` | Disables the webLinks feature for this description.
`${thumb}` | Inserts the thumbnail for the current directory (HTML <IMG> tag), or blank if there is no thumbnail.
`attrib=`attributes | HTML attributes that will be included in the <IMG> tag. These attributes must not include HEIGHT and WIDTH, because they are inserted automatically.
`${nothumb}` | Inserts the thumbnail for the current directory (HTML <IMG> tag), or the default thumbnail if there is no thumbnail.
`attrib=`attributes | HTML attributes that will be included in the <IMG> tag. These attributes must not include HEIGHT and WIDTH, because they are inserted automatically.
`${index}` | Inserts the index list(s) using the format specified in the configuration file (HTML). This may consist of one or more lists or tables, and headings where appropriate. The HTML content generated by this token is designed to be stand-alone, and should not be nested within inline or block-level HTML elements (e.g. `<CENTER>${index}</CENTER>` is illegal).
`${list}` | Inserts a single list of links at the current position (HTML). The list may contain links to files, links to directories, or both. If a format is not specified with the "format" attribute, a pre-defined default format will be used. This token may be nested within block-level HTML elements (e.g. `<CENTER>${list}</CENTER>`).
`fileLinks` | Includes only links to individual files (including slides) in this list -- not links to directories.
`dirLinks` | Includes only links to directories in this list -- not links to individual files (or slides).
`heading=`text | Heading text that will appear if the list is not empty. The characters &, <, and > must be encoded as HTML character entities.
`layout=`layout | Determines the type of the list. layout can be one of the following: "simple" = one entry per line, "bullet" = unordered list (`<UL>`) [default], "thumbnail" = list of thumbnails only, each separated by a single space.
`format=`format | Determines the format of each entry in the index. format is a format string enclosed in quotes, which defines the way in which list entries will appear. It defaults a pre-defined format. This attribute is ignored if layout=thumbnail.
`nowrap` | Prevents lines from wrapping by converting all spaces to non-breaking spaces (&nbsp;). This attribute is ignored if layout=thumbnail.
`${table}` | Inserts a single table of links at the current position (HTML). The table may contain links to files, links to directories, or both. If a format is not specified with the "format" attribute, the default format will be used, which is specified by the configuration file. This token may be nested within block-level HTML elements (e.g. `<CENTER>${table}</CENTER>`).
`fileLinks` | Includes only links to individual files (including slides) in this table -- not links to directories.
`dirLinks` | Includes only links to directories in this table -- not links to individual files (or slides).
`heading=`text | Heading text that will appear if the table is not empty. The characters &, <, and > must be encoded as HTML character entities.
`format=`format | Determines the format of each entry in the index. format is a format string enclosed in quotes, which defines the way in which table entries will appear. It defaults to the value specified in the configuration file.
`columns=`columns | Specifies the number of columns in the table. This option is only available when the "format=format" attribute is used. It defaults to the value specified in the configuration file. If columns is a negative number, the absolute value is used as a default value, which can be overridden by specifying a different value in any of the configuration files.
`hPadding=`pixels | Specifies the padding, in pixels, between the columns in a multi-column index. This option is only available when the "format=format" attribute is used. It defaults to the value specified in the configuration file.
`vPadding=`pixels | Specifies the padding, in pixels, between the rows in the index. This option is only available when the "format=format" attribute is used. It defaults to the value specified in the configuration file.
`iPadding=`pixels | Specifies the padding, in pixels, between fields in an index entry. This option is only available when the "format=format" attribute is used. It defaults to the value specified in the configuration file.
`attrib=`attributes | HTML attributes that will be included in the <TABLE> tag. This option is only available when the "format=format" attribute is used. It defaults to "BORDER=0 CELLPADDING=0 CELLSPACING=0".
`tr=`attributes | HTML attributes that will be included in the <TR> tags. This option is only available when the "format=format" attribute is used. It defaults to empty (no attributes).
`td=`attributes | HTML attributes that will be included in the <TD> tags. This option is only available when the "format=format" attribute is used. It defaults to empty (no attributes).
`${rowtables}` | Very similar to the ${table} token except that it inserts a separate table for each row. This token accepts all of the same attributes as the ${table} token except "vPadding". It has one additional option:
`vSpacer=`text | String of HTML text that will be inserted between each row table. This may include text and/or HTML tags. It defaults to "`<P>\n`".
`${page}` | Inserts the current page number in a multi-page index (text). If the index is only a single page, this will be blank.
`${pages}` | Inserts the total number of pages in a multi-page index (text). If the index is only a single page, this will be blank.
`${pageLinks}` | Inserts a list of page links in a multi-page index (HTML). If the index is only a single page, this will be blank.
`${slideLink}` | Usage: `${slideLink}` content `${/slideLink}` Inserts a link to the first slide file in the index. The "`${/slideLink}`" end token is required. The generated output will be "`<A HREF=` ... `>` content `</A>`". If there are no slide files in the index, no anchor tags will be inserted but the content will remain. The content can be anything that HTML allows between the start and end anchor tags.
`${section}` | Inserts a section of the original index file (if there is one) into the generated index file. This effectively preserves a customized section of the index, such as introductory text, across builds. The section to be preserved must begin with a start string and end with a stop string. Line boundries have no significance. The entire section, including the start string and the stop string is inserted into the new index at this position, regardless of where it appears in the original index file. If the start string does not exist in the original index file, this will be blank. If more than one start string exists in the original index file, only the first one will be used. This token should normally appear on a line by itself.
`begin=`start string | String of characters that indicate the beginning of the section to be preserved (case sensitive). This is usually an HTML comment string. It defaults to`"<!-- BEGIN HEADING -->"`.
`end=`stop string | String of characters that indicate the end of the section to be preserved (case sensitive). This is usually an HTML comment string. It defaults to`"<!-- END HEADING -->"`.
`suffix=`suffix string | String of characters that is inserted immediately after the stop string. It defaults to`"\n"` (newline).

In addition, all of the tokens that are allowed in Format Strings are also supported.

### Directives

Lines beginning with a '#' sign are called directives. Directive lines are not sent to the generated index file. The following directives are supported:

`#if` expression | If the index attributes match the specified query expression, then everything up to the next #elseif, #else or #endif directive will be included in the generated index file. If/else constructs may be nested.
`#elif` expression | Specifies the optional "else if" section of an if/else construct.
`#else` [comment] | Marks the optional "else" section of an if/else construct. An optional comment may follow the #else directive.
`#endif` [comment] | Marks the end of an if/else construct. An optional comment may follow the #endif directive.
`#include` filename | Inserts the contents of the specified template filename into the template at the current position. If filename does not include a path, then ImajSite will seach for the file in the current working directory and then in the icons directory.
`#log` message | Sends a one-line message to the log file (or stderr if no log file has been configured). This can be used for template debugging or identifying invalid configurations.

### Comments

Template comments may be included in index template files to document the template itself. Template comments are really just special directives that don't do anything. Their syntax is as follows:

> `#` comment

Like all directives, the '#' must appear as the first character on the line. One or more spaces must follow the initial '#' character. The comment ends at the end of the line.

Inline token comments of the form "${-- comment text --}" are also allowed, but are not as useful. This syntax is similar to the HTML comment syntax, and they may span multiple lines.

### Icon References

Several tokens take attributes which specify the location of an icon file (iconRef). In order to specify icons which are located in the icons directory as well as files in the current directory, special translations are made as shown in the table below:

Attribute Value | Resulting HTML Code | Description
--- | --- | ---
`filename` | `icons/filename` | filename located in the icons directory
`./filename` | `filename` | filename located in the current directory
`path/filename` | `path/filename` | filename located in a relative path

For example, to specify an icon named "button.gif" located in the current directory, the attribute value would be "./button.gif". In order to specify the same file located in the icons directory, the attribute value would simply be "button.gif".

### Example

    # This is an index template file
    <BODY>
    <CENTER>
    ${nav}
    <P>
    #if thumbnail
    ${thumb attrib="BORDER=2"}<BR>
    <STRONG>${title}</STRONG><BR>
    ${description}
    #else
    <FONT SIZE=5><STRONG>${title}</STRONG></FONT><BR>
    ${description}
    #endif
    </CENTER>
    <P>
    <CENTER>
    Keywords: ${keywords}<BR>
    Template: ${iconDir}/template.htm<BR>
    </CENTER>
    <P>
    #if thumbFileLinks
    <CENTER>
    <TABLE BORDER=0 CELLSPACING=0 CELLPADDING=10 BGCOLOR=WHITE>
    <TR><TD>${table
      tr="ALIGN=CENTER"
      hPadding=12 vPadding=20
      format="<?A>${thumb}<?BR>${title}</A>"
      columns=4}</TD></TR>
    </TABLE>
    </CENTER>
    #else
    #if dirLinks
    <CENTER>
    <TABLE BORDER=0 CELLSPACING=0 CELLPADDING=10 BGCOLOR=WHITE>
    <TR><TD>${table dirLinks}</TD></TR>
    </TABLE>
    </CENTER>
    #endif
    #if dirLinks & fileLinks
    <P>
    #endif
    #if fileLinks
    <CENTER>
    <TABLE BORDER=0 CELLSPACING=0 CELLPADDING=10 BGCOLOR=WHITE>
    <TR><TD>${table fileLinks}</TD></TR>
    </TABLE>
    </CENTER>
    #endif
    #endif
    </BODY>

Table of Contents