Template Exports

Using the Export Function

The export function in the File pulldown can be used to generate reports from the data stored in the current database in various formats. The format is controlled by a template. A template is a file containing the static text framework that should appear in the exported file, with embedded expressions that are evaluated as part of the export process. These expressions are either standard grok expressions (see Expression Grammar), or special export expressions that are available only in export templates.

If the Export function in the file pulldown is chosen, a dialog containing a list of available templates is shown. The list begins with builtin templates that are not actually residing in template files on disk, but are built in to the grok program itself. User-defined templates reside in files in a directory that has the same path and the same name as the form file for the database, except that the extension ``.gf'' is replaced with the extension ``.tm''. The directory path can be displayed with the Database choice in the Help pulldown. For example, if the form file path is ``/usr/people/thomas/.grok/phone.gf'', all template files for the phone database are in the directory ``/usr/people/thomas/.grok/phone.tm''. The name of every file in that directory appears in the list of templates in the export dialog.

New templates can be created from scratch with the Create button under the template list. This will ask for the name of the new template and start an editor with the empty template file. To write a template that is a variation of an existing template, select the existing template, press the Dup (duplicate) button, and choose a file name. This creates a copy of the template that can then be edited b y selecting it in the template list and pressing the Edit button. This method also works for builtin templates.

The template only contains the instructions for creating the output file that is the result of the export operation. After selecting a template, the full path of the output file must be entered into the text field under the template list, or selected using the Browse button. When both the template and the output file are defined, the Export button performs the export operation and removes the dialog. Note that it is possible to write templates that ignore the output file name in the dialog and write to one or more files defined in the template. None of the builtin templates do that.

Template exports can also be started from the command line. The command

     grok -x phone html /415 > phone.html

The export output file is basically a copy of the template. Normal text in the template is copied to the output file unchanged, including all white space, tabs, newlines, and other control characters. Expressions that are enclosed in \{ (backslash directly followed by an opening brace) and } (closing brace) are not copied verbatim but are evaluated. The result of the evaluation is copied into the export output file. For example, the following text fragment in a template:

     Six multiplied by eight is n \{(6*8)}, approximately.

produces the following text in the output file:

     Six multiplied by eight is 48, approximately.

Note that the \{...} notation puts the expression parser in string mode, so inner parentheses had to be used to evaluate a numerical expression. There is no n \(...) syntax that would permit numerical expressions directly. If the export file should contain a backslash followed by an opening brace verbatim, the backslash must be doubled to prevent the sequence from being interpreted as the beginning of an expression. The switch statement may not be used with a new database specifier (First argument) in a template.

Most templates use more complicated expressions that reference fields in the database. For example, suppose an export file is to be generated from the phone database that is part of the grok distribution. The form for this database contains the fields ``name'' and ``phone'' whose values can be referenced in expressions by prefixing an underscore (again, refer to Expression Grammar for details). A template can be written that contains the following text:

     The phone number of \{_name} is \{_phone=="" ? "unknown" : _phone}.

This expression substitutes the name of the current card and the phone number if it exists (i.e. is not the empty string) or the text ``unknown'' otherwise. However, this expression is not useful by itself because it always references the first card in the database. Template expressions are provided that allow looping over all or selected cards of the database, excluding parts of the template, or define text substitutions for expression results that contain characters not allowed in the output file. The phone template above can be made to loop over all cards in the current query by rewriting it:

     Phone directory:
     
     \{FOREACH}

     The phone number of \{_name} is \{_phone=="" ? "unknown" : _phone}.

     \{END}

Here is a list of all supported template expressions:

• \{FOREACH expr} text \{END}
  The text between the FOREACH and END commands is executed once for every card for which the query expression expr is true. Every card is considered in the order of the most recent sort, and the query expression is executed. If it returns false (numerical value 0 or empty string or string beginning with "f") the parser skips to the matching END without evaluating text and considers the next card until the last card has been executed. The text can contain expressions and template expressions. FOREACH loops can be nested 10 levels deep.

  The query expression expr is optional; if it is missing the most recent query from the enclosing FOREACH loop is used, or if there is none, the last query from the command line or from the Query pulldown or from a text search in the main menu is used. It is recommended to not use query expressions because they make the -x command-line option less useful.

• \{IF expr} text \{ENDIF}
  Conditional expressions evaluate text only if the expression expr is true. Otherwise text is ignored. The text may contain expressions and template expressions, including FOREACH loops and other conditionals. IF statements can be nested arbitrarily.

• \{SUBST c=string c=string ... }
  Some characters are unwanted in output files. For example, angle brackets ``< >'' have a special meaning in HTML files, so the result of an expression that is placed in the output file must be adjusted to avoid these characters. This is done by providing substitutions for these special characters. The SUBST statement assigns an arbitrary string string to a character c that is substituted for every occurrence of c in the result of an expression. Both c and string may contain a backslash followed by an octal number, or ``t'' for a tab, or ``n'' for a newline. Blanks in string must be given as ``\040''. For example, a template creating an HTML file may contain the substitutions ``<=&lt;'' and ``\n=<BR>''. Later substitutions of the same c override earlier ones.

• \{SUBST HTML}
  This is a shorthand for substitutions required in HTML documents. It substitutes angle brackets, ampersands, and newlines. If newlines should not be preserved, follow this expression with a substitution like ``\n=\n''.

• \{FILE expr}
  The expression expr can either be a simple string or a string expression enclosed in braces. The result becomes the new output file name, and the previous file name specified in the export dialog (or stdout if the -x command-line option is used) is closed. The export function creates a file only when the first character is written to it, not when the filename is specified.

  The FILE command can be used in a template that creates form letters. Such a template would begin with a FOREACH statement followed by a FILE statement that creates a file whose name is derived from a database field or from a counter implemented with a variable.

• \{QUIT}
  This command aborts template evaluation. It is executed automatically when the end of the template file is reached. Normally QUIT would be given in a conditional statement.