Display Templates

From CollectiveAccess Documentation
Revision as of 19:03, 22 April 2015 by Julia (talk | contribs) (If rules)
Jump to: navigation, search

For v1.3

Bundle display templates are used to format data from Bundles (collections of metadata stored in CollectiveAccess) for display on screen, output into reports and presentation in search results. When no display template is defined, CollectiveAccess defaults to simply displaying the bundle data as-is. For bundles comprised of a single value (Eg. a simple text metadata element) this is not an issue. However, for complex bundles consisting of several discrete values – a mailing address for example – a template is often required to properly format the value. Other common uses for bundle display templates are:

  1. To define styling, such as headings, around simple and complex bundles.
  2. To conditionally include delimiters between values in a complex bundle. For example, if you have a bundle storing width, length and height dimensions for an object, and you want to place an "X" between each dimension value (and also, perhaps, specify suffixes and an order for the dimensions) a template is the means to achieve this.
  3. To display metadata attached to related items in relationship bundles. For example, if you want to display both the name and life dates for related entities you can use a bundle display template to both extract and format the metadata. Any bundle attached to the related entity can be displayed.

Defining templates

Bundle display templates can be defined for metadata elements as part of the configuration for the element. Templates can be set for all kinds of bundles, including metadata elements and relationships, in the setting for the bundle's placement within a display or user interface. Navigate to "Manage --> My Displays" in the user interface to set your template in the display list, or you can set the template when configuring a metadata element in "Manage --> Administration --> Metadata Elements." When a template is defined for a metadata element within a display it will take precedence over templates defined in the element's configuration.

Display template.png

Basic template syntax

At their most basic, templates are simply text with placeholders replaced by bundle values. Placeholders always start with a caret ("^") character followed by the name of the bundle value. For example, if you have a metadata element with the element code description and wish to preface the value of the element with the label "Description:" then the template would be thus:

Description: ^description

If the value of the description metadata element happens to be empty, this template will cause the label "Description:" to be awkwardly displayed without a trailing value. To avoid blank spaces like this,a display template can be made conditional on the presence of a value within a field. A template for description that only displays something if there's a description available would look like this:

<ifdef code="description">Description: </ifdef>^description

Everything between the <ifdef> and </ifdef> is only output for the corresponding placeholder (specified without the ^ in the <ifdef> tag) when it actually has a value.

Conditional output can be used for more than just labels. For dimensions and other collections of quantities, conditional output can be used to deal with variations where not all values are available at all times. For example, let's say you have a metadata container with three sub-elements: width, height and depth, all of which are elements of type Length. Displaying them without a template would result in three values separate with spaces:

12" 6" 9"

(we assume here that we're displaying in English units)

To make it clearer we can format the container using this template:

^width W x ^height H x ^depth D

This will display:

12" W x 6" H x 9" D

However if the depth value happened to be blank – a not uncommon occurrence – then the output would be:

12" W x 6" H x D

To rectify this we can use conditional output:

^width <ifdef code="width">W x</ifdef> ^height<ifdef code="height"> H x</ifdef> ^depth<ifdef code="depth"> D</ifdef>

Note that we can also use conditionals to close up the space between ^width and the "W", ^height and "H" and ^depth and "D". Normally space is required between the placeholder and any non-placeholder text to allow CollectiveAccess to distinguish the placeholder. With a conditional you can keep the placeholder separate from other text without resorting to spaces, as in this example:

^width<ifdef code="width">W x</ifdef> ^height<ifdef code="height">H x</ifdef> ^depth<ifdef code="depth">D</ifdef>

If you need to make part of your template conditional upon more than one value being set simply list the placeholder names in the "code" value separated by commas:

<ifdef code="width,height,depth">Dimensions are: </ifdef> ^width<ifdef code="width">W x</ifde> ^height<ifdef code="height">H x</ifdef> ^depth<ifdef code="depth">D</ifdef>

"Dimensions are:" will only be output if width, height and depth all have values. Of course this is probably not what you want when outputting a field label. Perhaps you need the text to be output if any of the values in the code list are set. Separating the placeholder names with "|" (aka. "pipe") characters will accomplish this:

<ifdef code="width|height|depth">Dimensions are: </ifdef> ^width<ifdef code="width">W x</ifdef> ^height<ifdef code="height">H x</ifdef> ^depth<ifdef code="depth">D</ifdef>

There are some cases in which you may need to make part of a template conditional upon a value or values not being defined. The <ifnotdef> tag will do this in an analogous manner to <ifdef>. For example, if you want to output a "No dimensions" message if no dimensions are defined:

<ifnotdef code="width,height,depth">No dimensions are set</ifnotdef> ^width<ifdef code="width">W x</ifdef> ^height<ifdef code="height">H x</ifdef> ^depth<ifdef code="depth">D</ifdef>

Pulling metadata through a relationship

In the above examples, the <ifdef code> is set to the direct element code (or sub-element code in a container) of the target field for the display. There are some cases, however, where metadata needs to be pulled through a relationship so that contextual information can be displayed. A common example of this would be placing a "Related Entities" bundle in a user interface (using the "List" format) and displaying a person's lifespan next to their name. In that case, a fuller path must be used to designate which record type the field is coming from.

^ca_entities.preferred_labels <ifdef code="ca_entities.life_span">(Life dates: </ifdef>^ca_entities.life_span<ifdef code="ca_entities.life_span">)</ifdef>

As you can see, in addition to "life_span" the prefix "ca_entities" is used within the <ifdef> tag.

Formatting display templates with <unit>

There are several scenarios in which you will need to organize the metadata in your display into discrete units. For these cases, you must use the <unit> tag. These include:

1.) If a record has repeating containers. Say you have a repeating address container on an entity record to accommodate multiple address changes. If you format your display template without specifying that each instance of the container needs to be displayed as a unit, you'll get a jumble of all of the subelements together - a nonsensical way to express an address.

2.) If you want to display metadata relating to hierarchical records. Without the <unit> tag, there's no way to individually list child records and accompanying metadata in a display. With the <unit> tag you can display child (or parent) records and hierarchical paths as discrete, complex units.

3.) If you want to pull metadata through an indirect relationship. Without the <unit> tag only metadata from the record of a direct relationship can be displayed. We could call this the Six Degrees of Kevin Bacon for CollectiveAccess where A is related to B which is related to C. If you want A's metadata on C's summary you must pull through the connecting B relationship.

The <unit> tag presents many opportunities for complex display formatting, which are explained in further detail, along with examples, here.

Contextual tags: <more> and <between>

Templates using <ifdef> and <ifnotdef> can get long and unruly when they include many elements dependent on the state of multiple placeholders. To help make such templates more manageable two tags are available that control output based solely upon their position in a template., obviating the need for long lists of placeholder names.

The <more> tag will output content if any placeholders following it have a value. Thus this template:

^description <more><br/>The source for this was: </more>^description_source 

will output this (assuming both description and description_source are set to "A metal pan" and "1978 auction catalogue" respectively):

A metal pan
The source for this was: 1978 auction catalogue

If description_source was empty the output would be:

A metal pan

The <between> tag will output content if any placeholders before it in the template and the placeholder directly following it in the template have values. This makes delimiting lists of values more compact than options using <ifdef>:

^width <between>x</between> ^height <between>x</between> ^depth

The output of this would be the defined dimensions with a single "x" delimiter between each pair.

Formatting single-table hierarchical displays

To display the hierarchical path of single record table, such as Places, you would create a simple display using the preferred_labels element. However, to view the preferred labels along with its parent records, you would add the hierarchy as follows:

^ca_places.hierarchy.preferred_labels 

However, you need a delimiter to separate the multiple values. Append a percent sign and delimiter=<my delimiter> to the field specifier, like so:

^ca_places.hierarchy.preferred_labels%delimiter=_➔_

When setting the delimiter, underscores are used in place of spaces. Spaces are used to delimit individual field specifiers, so you can't have the delimiter floating out past a space and expect it to be associated with the field spec. They will display as spaces in the search results, however.

Making links to other records

A special <l> tag is used in Providence to create a link within the bundle display template. Here's an example of a entity record, with address metadata, that's linked:

<l>^ca_entities.preferred_labels</l> <ifdef code="ca_entities.address.address1">(</ifdef>^ca_entities.address.address1<ifdef code="ca_entities.address.address1">)</ifdef>

Clicking on the entity name in the example above would take a cataloguer to the entity record. In Pawtucket the link tag works similarly, it creates a link to the record's detail page.

Using HTML

Bundle display templates accept HTML for additional styling when rendered in "list" format in addition to the special CollectiveAccess-specific tags mentioned above.
Screen Shot 2013-05-15 at 2.19.56 PM.png
As you can see this makes the Title a link and the identifier italicized.
Screen Shot 2013-05-15 at 2.16.45 PM.png

The "list" format, especially when styled with HTML, can help to create complex displays of "cross-table" information. This is often very helpful when a cataloguer needs to see specific contextual metadata from a related record in order to fully catalog the current record. Here's an example of an object record that uses display formatting to pull information from a related Exhibition record:
Screen Shot 2013-05-15 at 2.46.20 PM.png

The display formatting used for the example above is:

<l>^ca_occurrences.preferred_labels</l> <ifdef code="ca_occurrences.exhibit_date"><b>(Dates: </ifdef>^ca_occurrences.exhibit_date<ifdef code="ca_occurrences.exhibit_date">)
</b></ifdef> ^ca_occurrences.description


If rules

It's possible to use expressions to control when you see displayed data. To do so, use the if rule. Here's an example. Let's say you want to only output the display if "current" is selected from the type drop-down in a repeating credit line container. Your display template would look like this (with your correct codes of course):

        <unit relativeTo="ca_objects.credit_line"><if rule="^credit_type =~ /current/">^ca_objects.credit_line.credit_text 
        (^ca_objects.credit_line.credit_type)</if></unit>

Types of templates

Templates can be defined for all four types of bundles (intrinsic fields, preferred and non-preferred labels, metadata attributes and relationships). The basic syntax defined in the previous section is used in all cases, with a handful of type-specific considerations to keep in mind.

Intrinsic fields

Intrinsic fields are the data fields present in CollectiveAccess regardless of your system configuration. They are simple non-repeating values representing values that are either required for CollectiveAccess to function or included to provide functionality for data imported from early versions of CollectiveAccess. Examples of intrinsic fields present in most or all types of records include "type_id" (the type of the record), "idno" (the identifier for the record) and "extent" (for objects only, the quantity of objects represented by the record).

Templates for intrinsic fields use the basic syntax with a single placeholder that is the name of the field. Example:

This is the extent: ^extent

Labels

Labels are titles for a record. There are two types of labels for most types of records, preferred and non-preferred. A preferred label is the primary title for a record. There can be at most one preferred label per language per record. Non-preferred labels are alternate titles. There can be any number of non-preferred labels for a record.

Templates for labels use the basic syntax with placeholders for all label fields. These fields vary by record type. For objects, for example, fields include name (the title). For entities, there are many more fields corresponding to the parts of the entity name: surname, middlename, forename, prefix, suffix, other_forenames and displayname. Most labels also provide locale_id (the language of the label) and type_id (the optional label type).

Object title: ^title
Entity name: ^surname, ^forename (^prefix)

Metadata elements

Metadata elements are installation-specific data attributes. The vast majority of the metadata stored in your CollectiveAccess system are attribute values entered into various configured elements. Metadata elements may be single values (Eg. a text field, a date field, a length field), or a container containing two or more sub-elements. Elements may repeat any number of times depending in the limitations set in your individual configuration.

Templates for metadata elements use the basic syntax with placeholders for each sub-element when handling a container, or a single placeholder when handling a simple element. All placeholder names correspond to the element codes of the elements and/or sub-elements. Example (simple element):

Description: ^description

Example (container):

Description: ^description (^description_type)

Relationship templates

Templates for relationship bundles – information about entities, places, occurrences, Etc. related to a record – are similar to templates for metadata elements, intrinsic fields and labels with a few additional considerations. Because they refer to data in related records, as opposed to data in the record at hand, the placeholders are longer and more specific. Placeholders for relationships can be any bundle in the related record, including intrinsics, metadata elements and preferred labels. For intrinsic and metadata elements placeholders are field names and element codes respectively. For preferred labels, placeholders are preferred_labels followed by a period and a label field. For example:

The related entity name is ^preferred_labels.surname, ^preferred_labels.forename

In addition to the placeholders for the related record the following special placeholders are available for all relationships:

Placeholder Description
^relationship_typename The relationship type as text for display.
^relationship_type_id The numeric internal relationship type_id.
^relationship_type_code The code for the relationship type as defined in the configuration profile.
^label The preferred label for the related record in the user's current locale, ready for display. This is an alternative to the preferred_labels.<field_name> construction.

If you wish to restrict the relationships you are displaying to specific types or relationship types, you can qualify your placeholders using the same "%" options syntax used for delimiters. For example, to pull a list of related entities delimited with semicolons and related with relationship type "buyer" use a placeholder like this:

^ca_entities.preferred_labels.displayname%delimiter=;_%restrictToRelationshipTypes=buyer

You can specify multiple values by separating the values with a | ("pipe") character. Ex.

^ca_entities.preferred_labels.displayname%delimiter=;_%restrictToRelationshipTypes=buyer|seller%restrictToTypes=individual|organization

The above displays a semicolon delimited list of entity names related as either buyer or selling and restricted to entities of type individual or organization.

Other Options

Placeholder Description
^DATE Displays today's date in any bundle display template.
Namespaces

Variants
Actions
Navigation
Tools
User
Personal tools