=====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**:
<code html>
  <p type='opac/slot-data' query='datafield[tag=245]'></p>
</code>

==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**:
<code html>
  <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>
</code>

====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:

<code javascript>
  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
</code>

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**:
<code html>
  <div type='opac/slot-data' datatype='marcxml' query='datafield[tag=245]' templated='true' limit='1'>
    ...
  </div>
</code>

==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:

<code html>
  <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>
</code>

==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**:
<code html>
  <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>
</code>

====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:

<code javascript>
  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
</code>

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.