The LaSt engine inputs are all sent as well-formed XML terms [BPC98]. That is, the syntax is like in XML, but the environments and tags are not specified in a DTD, as can also be seen in the example below. Exactly what the tag and environment names mean will be explained in the continuing documentation.
<last>
<process file="documents/toplists/topten.rw"
package="rules/toplists.last" />
<viewer>
<browser value="Netscape" />
<favorite_artist value="Bruce Springsteen" />
</viewer>
<choices file="documents/toplists/topten.choices" />
<flags output="full" />
</last>
All the inputs are given in the special `<last>' environment, structured as pure XML markup. All whitespace and text in between tags will be ignored, and there is no ordering between the different tags and environments on the same depth. Differing from HTML, the letter case is important in tag and attribute names. The example above might equally have been written as this:
<last> <flags output='full' /> Any text here will be ignored... <choices file="documents/toplists/topten.choices" /> <viewer><browser value="Netscape 4.5" /> <favorite_artist value='Bruce Springsteen' /> </viewer> <process package="rules/toplists.last" file="documents/toplists/topten.rw"/></last>
It is encouraged to keep the inputs human readable as much as possible, as they may end up in the server log. Having readable inputs will highly improve the possibilities of debugging, and will probably reduce the number of errors in the inputs.
The LaSt engine processes a specific RadioWeb document with the rules from one or more LaSt packages. A RadioWeb document may contain several dynamic objects, all of which will be sent to the WSDL interface for interpretation. Typically each object represents some database lookup with it's own expire date.
The RadioWeb document to process is given in a special input tag or environment. Below there is an example on how to process an input file, present in the directory `documents/toplists/', with the rules from the LaSt package `toplists.last'. Note that both these file names refer to files on the machine where the LaSt engine is running, relative the the directory where it was started.
<process file="documents/toplists/topten.rw" package="rules/toplists.last" />
The attributes `file' and `package' are mandatory, and optionally several `package' attributes may be given. In the latter case, any rule from the packages given can be used to process the objects in the document. The RadioWeb documents can also be sent embedded in the input along with the parameters, as shown in the example below. Instead of using a single element, a full `process' environment is used.
<process package="rules/toplists.last"> ... RadioWeb template here ... </process>
Note that it is not possible to embed LaSt packages in the same way as the documents. This would make the precompilation of the rules much more complicated, and also for security reasons it is probably not desirable that any rule can be used, since rules may contain arbitrary program code.
The RadioWeb documents are crucial for the processing in the LaSt engine, and they may not be omitted. If a <process> element or environment is missing a fatal error message will be printed and the LaSt engine will exit immediately.
The reader preferences are specified in a `<viewer>' environment. Inside this environment there are no other nested environments, instead each one of the reader preferences is specified with a tag. Basically these preferences can be seen as an unordered list of key-value pairs.
The LaSt engine is unaware of the names of the preferences that will be input, but rather uses a standardized format to convert the preferences to an internal structure, visible to the LaSt rules. Here is a small example of a set of reader preferences:
<viewer> <browser value="Netscape" /> <favorite_artist value="Bruce Springsteen" /> </viewer>
In this example the reader preferences consist of two key-value pairs; the "browser" set to "Netscape", and the "favorite_artist" set to "Bruce Springsteen". During the evaluation of the LaSt rules, there will now exist a special reader context that contains exactly these two bindings, and in the rules the values of any one of them can be tested.
The reader context can also be sent in a file, present on the file system where the LaSt engine runs, as shown in the example below. This is equivalent of replacing the `<viewer>' tag with the contents of the file, which thus must contain a `<viewer>' environment. The viewer environment may also be omitted in the input, in which case a viewer context with no entries will be seen by the LaSt rules.
<viewer file="filename" />
In order to keep layout and styling parameters fixed each time the LaSt engine is run, a structure containing the previous choices can be sent to the LaSt engine. Basically this structure contain the choices made for some or all of the free variables in the LaSt rules. Below is an example of how this input structure could look like.
<choices>
<layout id="object1" value="3">
<option name="cellpadding" value="3" />
<option name="border" after="0" />
<option name="width" before="100%" />
... more options ...
</layout>
<layout id="object2" after="1">
</layout>
... more layouts (for other objects) ...
</choices>
In this example the object `object1' will be assigned the third layout of all the possible layouts for that object. It is also possible to not specify the layout number for an object, in which case the first possible (i.e. layout number 1) will be selected.
As can be seen in the example below the choices may also reflect certain changes, like `after' and `before'. These two values specify that the next or previous default value for a variable should be used. In the case of layouts, the next or previous layout will be selected. A new value can also be set directly by changing the `value' attribute. If a certain option is not specified (like for example `bgcolor' in the example above), it will be selected automatically by the LaSt engine, i.e. it's value is considered free. Note that only the free options will be selected to conform with the constraints given in the LaSt rules.
Once a page has been designed, it is likely that the designer wishes to store some or all of the choices made. These can then be inputted to the LaSt engine as a file, as shown in the example below. This is exactly equivalent to replacing the include directive with the the contents of the file, thus requiring a `<choices>' environment to be present in the file.
<choices file="documents/toplists/topten.choices">
The LaSt engine will be used in at least two modes -- one for simple retrieval of pages, and one for designing pages. In the retrieval of pages one is typically only interested in the HTML result, while the possibility of changing the choices is crucial for the designer. A special tag allows for choosing full outputs, or normal outputs. If no flag is given the value is assumed to be normal outputs, which results in outputting only the HTML result. In full output mode, the choices made and possible errors and warnings are also output. How to select full outputs is shown in the example below.
<flags output="full" />
Including this tag in the input structure, will cause the LaSt engine to include all it's outputs inside a <last> environment, as further described in the next section.
Go to the first, previous, next, last section, table of contents.