3.6 Lookup Tables
Description: Lookup Tables
Keywords: albatross

#
3.6 Lookup Tables

The example macro used in the previous section introduced a new Albatross tag called `<al-lookup>`. In this section we will look at the tag in more detail.

The `<al-lookup>` tag provides a mechanism for translating internal program values into HTML for display. This is another way which Albatross allows you to avoid placing presentation logic in your application.

In a hypothetical bug tracking system we have developed we need to display information about bugs recorded in the system. The severity of a bug is defined by a collection of symbols defined in the `btsvalues` module.

    TRIVIAL = 0
    MINOR = 1
    NORMAL = 2
    MAJOR = 3
    CRITICAL = 4

While the integer severity levels are OK for use as internal program values they are not very useful as displayed values. The obvious way to display a bug severity would be via the `<al-value>` tag.

    Severity: <al-value expr="bug.severity">

Unfortunately, this would yield results like this:

    Severity: 1

By using the `lookup` attribute of the `<al-value>` tag we are able to use the internal value as an index into a lookup table. The corresponding entry from the lookup table is displayed instead of the index.

The following is a table which translates the internal program value into HTML for display.

    <al-lookup name="bug-severity">
     <al-item expr="btsvalues.TRIVIAL"><font color="green">Trivial</font></al-item>
     <al-item expr="btsvalues.MINOR">Minor</al-item>
     <al-item expr="btsvalues.NORMAL">Normal</al-item>
     <al-item expr="btsvalues.MAJOR"><font color="red">Major</font></al-item>
     <al-item expr="btsvalues.CRITICAL"><font color="red"><b>Critical</b></font></al-item>
    </al-lookup>

The `btsvalues` module must be visible when the `<al-lookup>` tag is executed. You can place the `btsvalues` module in the the global namespace of the execution context by importing the `btsvalues` module in the same module which creates the `SimpleContext` execution context. When using other Albatross execution contexts you would need to import `btsvalues` in the module which called `run_template()` or `run_template_once()` to execute the `<al-lookup>` tag.

We invoke the lookup table by using the `lookup` attribute of the `<al-value>` tag.

    Severity: <al-value expr="bug.severity" lookup="bug-severity">

Note that the `btsvalues` module does not need to be in the namespace at this point. The `expr` attributes in the `<a-item>` tags are evaluated once when the `<al-lookup>` tag is executed.

The `<al-lookup>` tag has the same runtime properties as the `<al-macro>` tag. You have execute the tag to register the lookup table with the execution context. Once the lookup table has been registered it is available to all template files executed in the same execution context.

When using Albatross application objects the lookup table is registered in the application object so can be defined once and then used with all execution contexts.

Each entry in the lookup table is enclosed in a `<al-item>` tag. The `expr` attribute of the `<al-item>` tag defines the expression which will be evaluated to determine the item's table index. As explained above, the expression is evaluated when the lookup table is executed, not when the table is loaded, or looked up (with the rare exception of a lookup being used earlier in the same template file that it is defined).

It is important to note that the content enclosed by the `<al-item>` tag is executed when the item is retrieved via an `<al-value>` tag. This allows you to place Albatross tags inside the lookup table that are designed to be evaluated when the table is accessed.

Finally, any content not enclosed by an `<al-item>` tag will be returned as the result of a failed table lookup.