Chapter 7. Template Sections

Table of Contents
Each section in detail
Embedded TCL

The ZAP template consists of a number of sections. Each section, with a couple of exceptions, should contain the HTML fragment, which is to be output when a given situation arises. However, the def and override sections contain input parameters which are not directly output, and the record section sometimes uses special syntax to govern the formatting of a given record structure (e.g. GRS-1). Each section is headed by a %% in the leftmost column, followed by the name of the section (e.g., "%%begin").

Each section in detail

The sections are executed in the order depicted in figure 1. First the %%def, %%override and %%begin sections are interpreted. If the query is valid the search is performed and this will result in either the %%server-error or the %%server-hits section is executed. This procedure is repeated for each target. If the search results in any hits the %%records begin is executed and then for each record the %%record xxx and %%format xxx (where xxx is the record format the records are returned from the server in) is executed. Finally the %%end section is executed.

%%def

In this section all the initial declarations can be made such as what target to search, how many records to display and so forth. Parameters being transferred from a form will override the same parameters in this section.

%%override

Same as the %%def section but parameters declared in this section will override the parameters being transferred from a form.

%%begin

This section is sent to the user before anything else takes place. It typically contains the HTML header information (title, etc.). If the section is omitted, nothing is sent.

%%end

This section contains the last HTML to be Figure 1 Flow diagram of the sections in ZAP sent to the user. If the section is omitted, nothing is sent.

%%query-empty

This section is sent if the user supplied an empty query.

%%query-ok

This section is sent if the query is syntactically correct, but before it is sent to the target(s). One thing it might be used for is to display the interpreted query to the user. The query is available in a string form in the variable $query.

%%record xxx

This section is invoked for each record with a given record format where xxx is the record format. This is done before the actual record formatting takes place in the %%format section. Please refer to the Section called syntax in Chapter 5 for a list of valid record formats.

%%format xxx

This section contains the formatting expressions for a given record format, where xxx is the record format. It governs the mapping of an individual record to HTML Please refer to the Section called syntax in Chapter 5 for a list of valid record formats. See Chapter 9 on how to format records.

%%records begin

This section is sent before the first record for a given target. It might be used, for instance, to begin an HTML table or bullet-list.

%%records end

This section is sent after the last record for a given target.

%%server-error connection

This section is sent if ZAP is unable to establish a physical (network) connection with the given target ($host), or if the network connection drops suddenly during the processing of the query (the latter condition typically indicates that the target has crashed).

%%server-error timeout

This section is sent if ZAP times out during the connection phase. The time out time is set with the timeout variable (see the Section called timeout in Chapter 5).

%%server-error init

This section is sent if the attempt to initialize the Z39.50 association with the target fails.

%%server-error protocol

This section is sent if the protocol decoder layer fails on an incoming protocol package. It indicates a breach of protocol by the target, or a bug in ZAP's protocol layer (knock on wood).

%%server-error N

N is a number corresponding to a Bib-1 diagnostic code. Use this to generate a user-friendly message when a recognized error is returned.

Please refer to http://lcweb.loc.gov/z3950/agency/defns/bib1diag.html for further information on Bib-1 diagnostic codes.

%%server-error

This is a catch-all - if no specific section is found to match the bib-1 diagnostic code, this section is sent to the user. Use $errorcode, $errorstring, $addinfo, to get the diagnostic code, a human-readable string (often in English), and the diagnostic additional-info field (if it is supplied), respectively.

%%CCL-error N

N is the number corresponding to the errorcode returned from YAZ' CCL parser. Use this section to generate a user-friendly message when a errorcode is returned.

Table 7-1. CCL Error Codes

CodeDescription
0OK (no error)
1Search word expected
2')' expected
3Set name expected
4Operator expected
5Unbalanced ')'
6Unknown qualifier
7Qualifiers applied twice
8'=' expected
9Bad relation
10Left truncation not supported
11Both left - and right trunctation not supported
12Right truncation not supported

%%CCL-error

This is a catch-all - if no specific section is found to match the YAZ CCL parser errorcode, this section is sent to the user. Use $errorcode, $errorstring, to get the diagnostic code and a human-readable string (the Section called %%CCL-error N), respectively.

%%server-hits N

N is the number of hits in a resultset and this section is invoked when a resultset contains the specified number (N) of hits.

Example 7-1. Checking for specific hit count


      %%server-hits 0
      Sorry, no hits.
      
      %%server-hits 1
      There was one hit.
     

%%server-hits

This is a catch-all - if no specific section is found to match the number of hits, this section is invoked.

Example 7-2. Displaying any hit count


      %%server-hits
      There was $hits hits in $target.
     

%%include

%%includes is actually not a section but a call to include a file on that particular place.

Example 7-3. include

Lets say that you have put all the HTML code for the beginning of the page in the file header.html then you can include it the e.g. the begin section as follows


       %%begin
       %%include header.html
      

%%sort-record

This section should return the sort key for a record. It is only invoked if sorting is enabled. See the Section called servertotal in Chapter 5 This section is similar to %%record but should not make output. Upon completion of this section, ZAP inspects the TCL variable sort and assumes it is the sorting key.

%%sort-format

This section should return the sort key for a record. It is only invoked if sorting is enabled. See the Section called servertotal in Chapter 5 This section similar to %%format but should not make output. Upon completion of this section, ZAP inspects the TCL variable sort and assumes it is the sorting key.