The record formatting section is consulted whenever a record is to be displayed. The supported record formats are listed in the Section called syntax in Chapter 5 and you can have many record formatting sections for different record formats in the same .zap file.
In the following subsection we will go through the formatting different main record formats but we will star off with GRS-1 record formatting and use them to explain a number of general concepts about formatting records in ZAP. Therefore, even if you are not interested in GRS-1 records, be sure to read this section carefully.
The record formatting section (%%format grs1) consists of a number of lines. In the beginning of each line is a GRS-1 tagpath, ie. a list of (x,y) vectors separated by "/". Each vector corresponds to a tag type and a tag value (string or numeric). The character "*" may be used as a wildcard matching all tag values for a given type. The tagpath is followed by whitespace, and then by a string (surrounded by double quotes), which is to be sent to the user for each occurrence of the GRS-1 element corresponding to that tag-path. The order of the display of elements depends on the order of the lines in the GRS-1 section - on the order of the elements in the GRS-1 file.
A GRS-1 tag can also be just a string tag. In this case the tagpath will consist of the stringtags separated by "/" or a combination of stringtags and normal (x,y) GRS-1 tags.
The code after the tagpath may include references to the $data variable, which expands to the CONTENTS of the data element, if it is unstructured. The code can't include any newlines.
The basic string value mentioned above is sent only for primitive data values (ie. unstructured GRS-1 elements). If you wish to send output for a structured element, you should prepend the string with a "b:" or "e:". The former is emitted before the contents of the structured element are consulted - the latter after.
In some circumstances it is desirable to send output only the first time an element is met, e.g. you want to write "Keywords" only the first time a keyword field is found. This can be done by appending a ":1" to the end of the tagpath.
Example 9-1. Record Formatting with tag paths
The simplest case is an unstructured element, title, with the tag (2,1):
(2,1) "The title is: $data" |
A more complex element might be, say, a structured author element (2,2) with sub-elements name (2,7) and e-mail-address (2,13):
(2,2) b:"Author: " (2,2)/(2,7) "$data" (2,2)/(2,13) " (email: $data)" |
Given the values "Sebastian Hammer" and "quinn@indexdata.dk" for the name and e-mail-address sub-element, respectively, the following display would result:
Author: Sebastian Hammer (email: quinn@indexdata.dk) |
If the field (2,2)/(2,13) exists more than one time in the record, ie. a person has more than one e-mail address, the last line in the example above could be changed to the following, in order to only write "(email:" once:
(2,2)/(2,13):1 " (email: " (2,2)/(2,13) " $data " (2,2)/(2,13):1 ")" |
Finally, let us assume a Title element (2,1) which is sometimes unstructured, and sometimes structured into the well-known tag (1,19), and a locally string-tagged sub-elements (e.g. (3,"Subtitle")).
(2,1) "Title: $data" b:"Title: " (2,1)/(1,19) "$data"<BR> (2,1)/(3,*) " ($tagvalue: $data)" |
This example might lead to an output like this:
Title: Macbeth (Subtitle: An Electronic Version) |
There is a more general method than $data available to access individual elements of the record. The format
"${" ["/"] <tag> {"/" <tag>} "}" |
Will map to the contents of the element matched by the tag-path supplied. The format of "tag" is the usual (x,y) vector. If there is an initial "/" in the tagpath, the search is "rooted", ie. the entire tag-path must match from the root of the record. If there is no "/" in the beginning of the path, the search is limited to the "current" sub-tree of the record.
This:
${/(2,1)} |
${(2,1)} |
This:
${/(4,70)/(2,1)} |
It is possible to embed conditional statements in the display, such that a given bit of content is displayed only if a condition (usually the existence of a variable or field) is true. The syntax is
"${" <expression> "?" <text1> ":" <text2> "}" |
The expression may be a variable (as described above) or an element reference. If the variable/element exists, then text1 is displayed, otherwise text2 is displayed. Either text may be empty, and both may contain other, embedded element/variable references or conditional expressions. No language would be complete without a mechanism for generating recursive and completely incomprehensible statements - to baffle the novice and boost the ego of the journeyman.