User Tools

Site Tools


opac:bibtemplate

BibTemplate

BibTemplate is an Evergreen-custom Dojo module which can be used to retrieve and format XML data served by the Evergreen unAPI service. unAPI is a protocol for requesting known objects in specific formats, and Evergreen uses this to supply data – bibliographic records, metarecords, monograph holdings information, Located URIs, and more to come – in many different formats from MARCXML to MODS to custom XML applications.

Managing the display of information from raw XML can be difficult, and the purpose of BibTemplate is to make this simpler, as well as move the display closer to the client and away from the source data. This is good from a separation-of-responsibilities perspective, and also makes it easier to contain and control local customization.

Before BibTemplate, only a portion of the total bibliographic data was readily available to Evergreen admins and developers for the purpose of customizing the OPAC. With BibTemplate we hope to break out of this situation, and make OPAC customization more flexible and future-proof.

How to use BibTemplate in Evergreen 1.6

BibTemplate arrived in Evergreen version 1.6.0.0. In this first version the capabilities are somewhat limited, and while you can access all of the bibliographic data that unAPI can deliver, formatting is not as flexible as we want. Also, BibTemplate only knows how to retrieve bibliographic records, not metarecords or direct holdings data, in Evergreen 1.6. However, even with these formatting and display restrictions, enormous progress has been made in providing better and more useful bibliographic data display.

HTML API

BibTemplate follows the Dojo convention of adding attributes to existing (X)HTML in order to progressively change its behavior. The 1.6.0 HTML API consists of a set of attributes that are added to existing OPAC markup, and fall into two classes:

  • The slot marker – Elements that denote the location of bibliographic data to insert
  • The slot formatter – Elements that specify how the named data should be formatted for display
Slot Marker

A slot marker is any displayable HTML element that has a type attribute with a value starting with opac/slot-data. This element will become the container for the formatted data. A slot marker is required in order to retrieve, format and display data using BibTemplate. A slot marker must also have an attribute called query containing a CSS3 selector. This selector is applied to the XML returned by the unAPI service in order to gather the specific XML Nodes that should be considered for formatting.

The slot marker can also specify the format of the data to be returned from the unAPI service. This can be specified by adding +{format} to the type attribute, as in opac/slot-data+mods33-full. The default data format is marcxml-uri, which is an augmented MARCXML record containing Located URI information and unAPI links.

Example of a slot marker:

  <p type='opac/slot-data' query='datafield[tag=245]'></p>
Slot Formatter

A slot formatter is any invisible HTML element which has a type attribute with the value of opac/slot-format. (NOTE: before 1.6.0.4, only <script> elements were supported, though this restriction is now removed to support Internet Explorer.) Only one slot formatter element is allowed in each slot. The text contents of this element are wrapped in a JavaScript function and run for each node returned by the query CSS3 selector specified on the slot marker. This function is passed one argument, called item, which an XML Node captured by the selector. This function should return HTML text. The output for all runs of the slot formatter is concatenated into a single string and used to replace the contents of the slot marker.

The slot formatter is optional, and if not supplied BibTemplate will create a simple function which extracts and returns the text content of the XML Nodes specified in the CSS3 selector.

Example of a slot formatter:

  <td class='rdetail_item' id='rdetail_online' type='opac/slot-data' query='volumes volume uris uri' join=", ">
    <script type='opac/slot-format'><![CDATA[
      var link = '<a href="' + item.getAttribute('href') + '">' + item.getAttribute('label') + '</a>';
      if (item.getAttribute('use_restriction'))
        link += ' (Use restriction: ' + item.getAttribute('use_restriction') + ')';
      return link;
    ]]></script>
  </td>

JavaScript API

In order for BibTemplate to find the slot markers and invoke the slot formatters JavaScript renderer must be instantiated and called. This must be done for each record that is to contribute to a pages display. The API for this is simple and straight-forward:

  dojo.require('openils.BibTemplate'); // Tell Dojo to load BibTemplate, if it is not already loaded
  new openils.BibTemplate({ record : new CGI().param('r'), org_unit : here.shortname() }).render(); // Create a renderer supplying the record id and the short name of the org unit, if known, and call the render() method

The argument hash supplied to the new openils.BibTemplate() constructor can have the following properties:

  • record – The bibliographic record ID
  • org_unit – The relevant Organizational Unit, used to restrict holdings scope as on a search result or record detail page
  • root – The root element within the web page that BibTemplate should search for slot markers

How to use BibTemplate in Evergreen trunk (to become 2.0)

BibTemplate has been evolving since its initial release (and will continue to evolve for some time) and many of the restrictions noted for 1.6.0 no longer apply. In addition, a new templated mode has been added, which makes some tasks, such as complicated formatting and display of a particular datum multiple times, much simpler.

HTML API

BibTemplate follows the Dojo convention of adding attributes to existing (X)HTML in order to progressively change its behavior. The 1.6.0 HTML API consists of a set of attributes that are added to existing OPAC markup, and fall into two classes:

  • The slot marker – Elements that denote the location of bibliographic data to insert
  • The slot formatter and template values – Elements that specify how the named data should be formatted for display
Slot Marker

A slot marker is any displayable HTML element that has a type attribute with a value starting with opac/slot-data. This element will become the container for the formatted data. A slot marker is required in order to retrieve, format and display data using BibTemplate. A slot marker must also have an attribute called query containing a CSS3 selector. This selector is applied to the XML returned by the unAPI service in order to gather the specific XML Nodes that should be considered for formatting.

The slot marker can also specify the format of the data to be returned from the unAPI service. This can be specified by adding +{format} to the type attribute, as in opac/slot-data+mods33-full, or by adding a datatype attribute containing the desired format. As with BibTemplate in 1.6, the default data format for bibliographic records is marcxml-uri, which is an augmented MARCXML record containing Located URI information and unAPI links, though because metarecords are now supported, and cannot be delivered as MARCXML, they have a default format of mods.

In situations where you only care about some of the XML Nodes returned by the CSS3 selector you can supply limit and offset attributes on the slot marker a common use case is to take just the first of a set of Nodes by supplying limit='1' on the slot marker. A templated paging interface can also be built by cloning a template and altering both the limit and offset attributes before calling the render() method.

In addition to the basic formatting mode, which replaced the entire HTML contents of the slot with the concatenated output of all runs of a slot formatter, there is a templated mode. This is enabled by adding a templated attribute to the slot marker with a value of true. This mode causes BibTemplate to take the HTML contents of the slot and treat them as a template, instead of throwing the slot contents away and replacing them with the output of any slot formatter. It also tells BibTemplate to look for any elements marked with a type attribute containing opac/template-value.

Example of a simple slot marker:

  <div type='opac/slot-data' datatype='marcxml' query='datafield[tag=245]' templated='true' limit='1'>
    ...
  </div>
Template Value

When in templated mode, BibTemplate will look for any elements within the slot having a type attribute of opac/template-value. It will extract the text contents of these elements, turn them into a JavaScript function, run this function once per slot with a set of parameters, take the text output of each and assign it to an internal variable with the same name as the name attribute on the template value element, and then replace all occurances of ${name} placeholder within the slot HTML with the value associated with that name.

The parameters passed to the template value function are:

  • item_list – A Dojo NodeList containing the XML Nodes extracted by the slot marker's CSS3 selector.
  • BT – The BibTemplate renderer instance that is rendering this slot
  • slotXML – the XML Document retrieved from the Evergreen unAPI service for this slot
  • slot – The DOM Node of the slot marker

The function generated for each template value element is run just once with these parameters when a slot is rendered.

Example of a template value element and template placeholder:

  <div type='opac/slot-data' query='datafield[tag=245]' templated='true'>
    <span class='hide_me' type='opac/template-value' name='sf_a'>
     var sfa = dojo.query('subfield[code=a]', item_list[0])[0];
     return dojox.data.dom.textContent(sfa) || '';
    </span>
    ${sf_a}
  </div>
Slot Formatter

A slot formatter is any invisible HTML element which has a type attribute with the value of opac/slot-format. (NOTE: before 1.6.0.4, only <script> elements were supported, though this restriction is now removed to support Internet Explorer.) Only one slot formatter element is allowed in each slot. The text contents of this element are wrapped in a JavaScript function and run for each node returned by the query CSS3 selector specified on the slot marker. This function is passed the same set of arguments as the template value functions and one additional argument, called item, which an XML Node captured by the selector. This function should return HTML text.

The output for all runs of the slot formatter is concatenated into a single string. When not in templated mode, the output is used to replace the contents of the slot marker. However, when in templated mode, the output is used to replace only the formatter element itself, allowing both template value rendering and slot formatter rendering within the templated slot.

The slot formatter is always optional. If BibTemplate is in templated mode no default formatter is supplied. If not, BibTemplate will create a simple function which extracts and returns the text content of the XML Nodes specified in the CSS3 selector.

Example of a slot formatter:

  <td class='rdetail_item' id='rdetail_online' type='opac/slot-data' query='volumes volume uris uri' join=", ">
    <script type='opac/slot-format'><![CDATA[
      var link = '<a href="' + item.getAttribute('href') + '">' + item.getAttribute('label') + '</a>';
      if (item.getAttribute('use_restriction'))
        link += ' (Use restriction: ' + item.getAttribute('use_restriction') + ')';
      return link;
    ]]></script>
  </td>

JavaScript API

In order for BibTemplate to find the slot markers and invoke the slot formatters JavaScript renderer must be instantiated and called. This must be done for each record that is to contribute to a pages display. The API for this is simple and straight-forward:

  dojo.require('openils.BibTemplate'); // Tell Dojo to load BibTemplate, if it is not already loaded
  new openils.BibTemplate({ record : new CGI().param('r'), org_unit : here.shortname() }).render(); // Create a renderer supplying the record id and the short name of the org unit, if known, and call the render() method

The argument hash supplied to the new openils.BibTemplate() constructor can have the following properties:

  • record – The ID of the bibliographic record to retrieve.
  • metarecord – The ID of the metarecord to retrieve. This is mutually exclusive with record.
  • org_unit – The relevant Organizational Unit, used to restrict holdings scope as on a search result or record detail page.
  • root – The root element within the web page that BibTemplate should search for slot markers.
  • subObjectLimit – In cooperation with unAPI, specifies a limit to the embedded objects, such as call numbers attached to a bibliographic record, to return for rendering.
  • subObjectOffset – In cooperation with unAPI, specifies an offset to the embedded objects, such as call numbers attached to a bibliographic record, to return for rendering. Used with subObjectLimit, paging interfaces can be built for subordinate, embedded data.
  • tagURI – The complete unAPI tag URI used to request information from Evergreen. This allows direct access to object types that BibTemplated does not know about natively. Tag URIs are constructed as needed by BibTemplate for object types that it knows about.
  • depth – The scoping depth (an integer, defined by actor.org_unit_type.depth) to provide to unAPI in addition to the org_unit.
  • sync – A boolean telling BibTemplate whether it should use an asynchronous callback to render slots, or instead wait for data to return and not pass control back to the browser.
  • locale – The desired locale to be passed to unAPI. This defaults to the Dojo-detected locale, if any, and falls back to en-us. Because it looks for the Dojo-detected locale, it should normally be unnecessary.
opac/bibtemplate.txt · Last modified: 2010/05/05 14:16 by miker

© 2008-2017 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.