iVia

Appendix C: Template files and the iVia Macro Language

Warning: This page has not been updated to iVia version 5.

Many iVia web pages, including search results, are generated dynamically as the user interacts with them. These pages are created with iVia’s macro system, which works by reading template files, inserting data into the templates at the appropriate places, and sending the resulting HTML to the user’s web browser. This system makes it easy to control the appearance of the web pages by changing the template files.

In most programs we can specify a set of template files to use. We call each set of files a "theme". For example, a canned_search query for "tree" might be displayed in the defaults theme, simple theme, titles theme or ucr_library theme. In each case, the data is the same, but the outward appearance is different because a different set of template files is used.

Introduction to iVia macros

To control the appearance of a web page, we create template files that look like the pages we ultimately want displayed, but which contain macros instead of data values. For example, suppose we want a search results page that, when performing a search for the term "tree" that returns 49 results, will display:

To get the desired output, we take advantage of two of the macros set by the canned_search program: $QUERY and $TOTAL_NUMBER_OF_RESULTS. The template file contains macros in place of the data values:

When the sentence is output, the macro names will be replaced with the data values. This process is called "macro substitution".

Template files and themes

Template files are stored in the $IVIA_HOME/html_templates directory, with each theme in a separate subdirectory. The defaults theme, for example, is stored in $IVIA_HOME/html_templates/defaults. Within each theme directory, file are usually (but not always) stored in subdirectories that are named after the CGI program. For example, the template files that control the display of the canned search program with the dbase_manage theme are in $IVIA_HOME/html_templates/dbase_manage/canned_search, and the template files for the same program using the defaults theme are in $IVIA_HOME/html_templates/defaults/canned_search.

The defaults theme is a special theme: it is the theme that is used when the CGI program does not explicitly set the theme. Further, if a CGI program specifies a theme, but cannot find the template files it needs using that theme, then it falls back the defaults theme and uses it’s files instead (if they are available).

The two most commonly-used themes are defaults and dbase_manage. Dbase_manage is the main theme used by programs on the adders web site. There are many less common themes that are intended only to be used with a single program, such as the pop-up_window which is used to display pages without banners from the standard canned_search result page, and the p_title_desc theme which is used to format canned_search results for inclusion by PHP scripts.

The macro ands template system is not restricted to HTML and Web page output. For example, iVia uses it to format the email messages sent to subscribers to the Email Alert Service. The templates use din this case are found in the $IVIA_HOME/email_templates directory.

Advanced features of the macro language

The macro language supports a range of other features beyond simple macro substitution. A range of conditionals are supported ($IF, $IFDEF, $IFNDEF, $ELSIF and $ENDIF), a $CALL(function_name) construct supports special functions (PRINT_MACROS, SEARCH_BOX), and $SET and $UNSET can be used to alter macro definitions.

Macro names

Macro names must follow the pattern [A-Z][A-Z0-9_]*. Except for occurrences within $IFDEF or $IFNDEF, macro invocations must always correspond to defined macro names.

Conditionals

Suppose we want only want to output the number of results if it is less than 100, otherwise we want to output a simple message. Then we can write:

In fact, there are several types of conditional expression. The simplest is $IFDEF, which takes a simple macro name enclosed in parenthesis and output the following text only if the macro is defined. For example, $IFDEF(FRED) Frederick $ENDIF will output the text Frederick only if the macro $FRED is defined. (Note: the leading $-sign on the macro name must be omitted.) A similar function, $IFNDEF, outputs true only if the given macro is not defined, and both $IFDEF and $IFNDEF can be used with $ELSE clauses.

The $IF and $ELSIF conditionals are used to output text only when the specified condition is true. They both take expressions enclosed in parenthesis, which can be built up from the comparison operators "==", "!=", "<", ">", "<=" and ">=". For example, $IF($NUM >= 10 and $NUM <= 20) some-useful-text $ENDIF only output text for certain values of $NUM.

Multiple comparisons may be combined with the keywords "and" and "or" (which must be lowercase). "and" and "or" have the lowest precedence, but parenthesis may be used for grouping and to override the default precedence rules.

Both string and numeric comparisons are allowed. If one of the operands of a binary comparison is a number (which may be any signed or unsigned integer) and the other operand a macro, the macro must evaluate to a string that contains a valid integer, e.g. "-5". If neither operand of a binary comparison is a number then string comparisons are applied.

SET and UNSET

Macros can be set and unset via the $SET and $UNSET directives. For example, $SET(FRED, "Fred Flinstone") creates a new macro, called FRED, with the value Fred Flintstone. The syntax for $SET is $SET(macro_name, value) where value can be another macro name, a signed or unsigned integer constant or a double-quoted string constant. String constants can include optional double quotes or backslashes by preceding them with a single backslash each. (i.e. the value "A quoted string!" would have to be represented like this: "\"A quoted string!\""). The macro_name in $SET or $UNSET must not have a leading $-sign.

Callback functions

The language supports a function call mechanism for built-in Callback functions. The syntax is $CALL(function name). For example, $CALL(PRINT_MACROS) is a debugging function that outputs an HTML definition list displaying the currently defined macro variables and callback functions. In many programs, $CALL(SearchBox) will output HTML describing an iVia search box, and $CALL(Substring, $ANYMACRO, 50) can be used to truncate $ANYMACRO to 50 letters.