User Interface: HTML Delivery in Release 12 / 12a


HTML Delivery in Release 12 / 12a: An Overview

The user interface for release 12/12a uses XSLT for transforming source XML to HTML for the web. The source XML is provided by .xml template files containing DLXS processing instructions that are processed on the fly by the middleware, and then transformed by a virtual XSLT stylesheet, also composed on the fly.

Release 12/12a XML template files differ from HTML template files in Release 11 primarily in the sense that all final HTML markup has been moved into related XSL files, with the XML files generating only XML content to send to the XSLT processor. A host of debugging tools are available for diagnosing and customizing XML output and/or XSL template transformations to HTML. There is also a significant increase in the amount and availability of XML content to all XSL stylesheets for greater flexibility in controlling final output.

XML Templates

XML templates are used to deliver dynamic content from the CGI as well-formed XML to the XSLT processor. In general, the top level structure of XML templates mirrors that of the previous tpl template files, with an XML file for each major page scenario (search, results, header, text, etc.) Each XML template is a combination of static XML markup and processing instructions that are replaced by the cgi with XML compliant string values, or XML node fragments. In order to facilitate more flexibility and increased functionality to the XSLT process, a significant amount of additional data is provided as XML nodes to each processed XML template, including language specific reference tables, CGI, middleware and web environment variables, and references to all collection specific files.

Processing Instructions

Processing instruction tags are parsed and replaced by the middleware and the resulting xml becomes the source tree for the XSLT processor. Processing instruction tags have a slightly different form in Release 12/12a.

<?PI_IDENTIFIER_NAME [modifiername="value"]*?>

where all identifier names are preceded by a question mark and are represented in all capital letters with underscore characters. Zero or more modifier name/value pairs can be included to provide additional parameters. The tag is completed by a trailing question mark and a closing angle bracket. Here are two example PI tags surrounded by xml tags in the xml file.:




Can appear within multiple xml files. If there is a return to results link, the middleware supplies the href value within the IncludeReturnToResults tags. If there is no link, the xml delivered to the processor will contain only the empty tags.


<?CSS_PATH_XML filename="textclass.css"?>


Returns the appropriate contextual path to a collection-specific CSS file, named in the filename modifier (i.e., /DLXSROOT/c/coll/textclass-specific.css).


PIs in Release 12/12a act primarily as simple variable names: replaced by simple strings or even large blocks of well-formed XML.

PIs in Release 12/12a no longer are used as include/exclude instructions: Instead, a number of nodes return binary values indicating if related nodes should be used or not. An example from navheader.xml is ...


The cgi returns the PI with a string, 'true' or 'false' (i.e., <IncludeGoToXcoll>true</IncludeGoToXcoll>). The XSL for this case then acts on a 'true' value to build a link to the cross-collection home page:

<xsl:if test="IncludeGoToXcoll = 'true'">
  <td class="xcollnavcolor" align="center">
    <span class="globnav">

To see a couple of more examples of how PIs are relaced, see PI Examples.

Collection Templates and Class Fallback

Each of the class-specific sections below describes the techniques that are applied within the class architecture to effect changes to overall class look and feel as it is expressed through the templates. It is important to note, however, that the class middleware supports the implementation of customized, collection-specific XML templates collection-specific XSL stylesheets, and optional, supplemental XML nodes. That is, in principle, the fallback mechanism utilized in release 11 and before is the same: when attempting to render a particular page utilizing a specific template, the middleware will first look for the required template in the collection-specific path--using a customized template if it exists--and, if not found there, processing the class version of the same template. The relationship between XML templates and final HTML delivery is different in Release 12/12a, and so the application of fallback is different; and in some places there is new fallback behavior not present in previous releases. The sections below, thus, describe in detail the new application of fallback and the techniques that can be applied to any templates to achieve differentiation in HTMl output.


Main Template Components for Text Class

General Page Layout and Color

In Release 12/12a page delivery in Text Class is still modeled on class-level templates that are shared by all instances of the class and serve as default display for each page scenario. All default Text Class page templates are still based on the same general layout approach, which relies on tables for all general positioning, though release 12/12a relies more heavily on associated CSS style definitions. General layout is shown in Figure 1, which shows top-level tables with borders showing, and using the color scheme for the Voltaire électronique collection. Each header and navigation cell also has a default CSS class value and default background image (the image is now specified in a CSS style definition for each header cell in textclass.css). For more on specifying individual collection appearance, see Specifying individual collection characteristics.

Figure 1: top-level table structure of a typical page.


Figure 2 shows the simple search page for The American Verse collection as it appears normally. Navigation bar labels, page text header markup (not header text content, e.g., "Basic Search"), instruction text and footer text are hard coded, and thus identical across all collections. All other content is specified per collection by processing instructions.

Figure 2: Basic search page for American Verse.


XML Templates and Fallback

Release 11 .tpl template files combined processing instructions with hard-coded HTML markup that was processed in the CGI. In this approach, all the source markup in the Text Class schema was transformed to HTML with perl filters, usually in place of a PI in the .tpl file. Fallback was automatic in the sense that simply creating a template file of the same name in a separate directory would result in that file being pulled into the transformation for the designated page.

In Release 12/12a, the HTML markup for delivery is embedded within XSL templates that transform the XML generated from xml templates. The final process is an XSLT transform, involving one xml file and one xsl file. Those of you familiar with XSLT transformations know that xsl stylesheets can import other stylesheets and utilize the template rules from the imported stylesheet. This is part of a model of modularity inherent in the design of XSLT. But, by default, XSLT does not allow that the imported stylesheets be designated at XSLT transform run time: the paths have to be hard coded in the stylesheet. Many of the XSL stylesheets in Release 12/12a work together, just as if they were all part of a single styesheet compiled via import, but to enable fallback to work at the level of each stylesheet, we designate the dependent XSL stylesheets by name in the xml template. The middleware, then, compiles a virtual stylesheet for the XSLT transform process. An example is shown below for the search page.

Example: fallback in the search page

Building the search page begins with the search.xml template, shown in full below:


<Top xmlns:dlxs="">

  <!-- XSL fallback files -->

  <!-- Custom OPTIONAL XML for top-level file search.xml<2> -->
  <CustomXml><?CHUNK filename="searchextra.xml" optional="1"?></CustomXml>

  <?CHUNK filename="dlxspageglobals.xml"?>

      <Link><?SIMPLE_SEARCH_LINK_XML testforrestrict="1"?></Link>
      <Link><?BOOLEAN_SEARCH_LINK_XML testforrestrict="1"?></Link>
      <Link><?PROXIMITY_SEARCH_LINK_XML testforrestrict="1"?></Link>
      <Label>Word Index</Label>
  <!-- this is for the HTML select element (pulldown) of all groups -->
      <!-- Begin collection specific restrictions -->



Important to note is the XslFallbackFileList node at the top. Each child Filename node indicates an XSL file--each found via fallback--that is required to transform the source tree XML that will result when all the PIs are resolved. The middleware will acquire the paths to each XSL file named and, using those paths in xsl:imports, will compile a single virtual stylesheet in memory, as shown below:

Virtual Stylesheets

virtual transform stylesheet for search.xml
		<?xml version="1.0" encoding="UTF-8" ?>

<xsl:stylesheet version="1.0" 
  <!-- transform.xml is processed by the middleware into an internally    
  referenced XSL stylesheet. This allows fallback processing of the  
  stylesheets imported into the top-level stylesheet. The top-level  
  stylesheet is normally specified by the <?xml-stylesheet           
  type="text/xsl" href="somestylesheet.xsl"?> processing instruction 
  (PI) in the top-level XML file.  In the absence of that PI, an XML 
  XslFallbackFileList node must be present in the top-level XML file 
  to list the XSL files which should appear in XSL import statements 
  to replace the XSL_FALLBACK_FILE_LIST PI below. -->

  <xsl:import href="/l1/web/t/text/bookbagitemsstring.xsl"/>
  <xsl:import href="/l1/web/t/text/search.xsl"/>
  <xsl:import href="/l1/web/t/text/htmlhead.xsl"/>
  <xsl:import href="/l1/web/b/bldemo/navheader.xsl"/>
  <xsl:import href="/l1/web/t/text/footer.import.xsl"/>
  <xsl:import href="/l1/web/t/text/searchforms.xsl"/>
  <xsl:import href="/l1/web/lib/xsl2htmlutils.xsl"/>
  <xsl:import href="/l1/web/t/text/globalvariables.xsl"/>
  <xsl:import href="/l1/web/t/text/headerutils.xsl"/>

 <xsl:output method="html"
   doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"/>

Note that in this case, for the collection with collid 'bldemo' there is a collection-specific copy of navheader.xsl in /l1/web/b/bldemo/. All other files are taken from class directories. (More on the breakdown of xsl and xml files later in this document.)

Fallback is also operating in the resolution of all CHUNK PIs, as in previous releases. In particular in this example are

<CustomXml><?CHUNK filename="searchextra.xml" optional="1"?></CustomXml>


<?CHUNK filename="dlxspageglobals.xml"?>

The first example will insert into search.xml the contents of a searchextra.xml file from the current collection specific directory (e.g., /l1/web/b/bldemo) if it exists, but simply remove the PI if it does not exist. This mechanism allows for the addition of specific XML content, per collection, that is relevant to the search page.

The second example causes the middleware to insert the dlxspageglobals.xml file into search.xml. dlxspageglobals.xml itself references xml for each page header (navheader.xml), footer (footer.import.xml) and a set of global level nodes wrapped in a <DlxsGlobals> node that provide a variety of reference data to facilitate many of the templates in dependent XSL pages.

Fallback Caveats

Note that fallback allows for multiple levels of CHUNK lookups in xml files, which are all processed in sequence into a single source tree.

Fallback is not exercised, however, in the xsl files referenced in the virtual stylesheet. The reason is primarily to make it easier to test XSL transformations "off line" simply by saving the compiled stylesheet and it's import sheets separately, to transform in a local debugger. This approach also provides for client side xsl transformation, when the virtual stylesheet can simple be written to disc and referenced in the xml file sent directly to the user's browser.

Finally, incorporating fallback into the mechanism here interrupts to some degree the facility of importing and either overriding or augmenting template rules from one XSL stylesheet to another. Becaue none of the stylesheets in the virtual stylesheet actually import each other, it is not possible to utilize the apply-imports element. Also, template rules that are identical to the processor--that match the same node--will be executed in reverse occurrence order: the last valid template takes precedence. That effectively means that when two xsl files named in Filename nodes witin a single xml file contain identical, or equally valid, template rules for the same source node, the template rule in the last named xsl file will be applied.

Language Selection by the Middleware

The following describes the mechanism by which the middleware selects a language string lookup XML file, "langmap" for short.

The file naming convention is:


where XX is replaced by a standard IANA primary locale specifier such as "en" so for example for English the language map file would be:


The effective language into which XSL will render the interface is based on a priority scheme involving the following configuration variables:

  1. the database Collection and Group table "languagepriority" fields which are multi-valued fields whose first value lists the default language followed by, in no particular order, the other languages supported for the group or collection.
  2. the Perl global variable @LibGlobals::gLanguageDefaultPriority which is an array of values treated in the same priority fashion as the "langguagepriority" fields in the database.
  3. the "lang" URL parameter.

The effective language is determined by the following alogorithm:

If there is a "lang" URL parameter, its value determines the effective language. If its value is not configured for the effective collection or group mode the default (first) value configured for the mode is used. If the mode does not have *any* "languagepriority" field values configured for the mode the global Perl variable @LibGlobals::gLanguageDefaultPriority is consulted. If the requested language is not present in that list the first value is taken as the effective language. Now the langmap filename can be constructed. It is an error is there is not a langmap file by that name in the target fallback directory for the mode.

If there is *not* a "lang" URL parameter, the effective language is determined, depending on mode, by the first value in the "languagepriority" fields in the Collection or Group fields is supplied else by the first value in the Perl global variable@LibGlobals::gLanguageDefaultPriority.

The lang URL parameter value, if present, is emitted to the XML in the <CurrentCgi><Param name="lang">en</Param> element.

The Effective Language as determined by the above algorithm is emitted as a child of the <DlxsGlobals> XML element named <EffectiveLanguage>.

The langmap file contents is inserted into a parent XML file by PI replacement of the <?LANGMAP?> PI. The langmap file determined by the above priority scheme is selected via the usual fallback protocol based on collection, group and class directories described elsewhere.

XSL Stylesheets

The final core component in Release 12/12a is the array of XSL stylesheets that provide all the template rules for the XSLT tranform process. The stylesheets are where most of the individual collection customizations will be conducted. DLXS middleware for Release 12/12a is build around the libxslt processor. The stylesheets are all XSLT version 1.0, with several utilizing EXSLT extensions (see for more on EXSLT). Table 1 provides a list of all stylesheets available for text class. See also a table of xsl file dependencies by xml filename as an overview of the structure of xsl and a guide for customizing changes.

Table 1
Filename Description
Main top-level stylesheets (all work in consort with xml files of the same name)
bookbag.xsl Main stylesheet for building the bookbag holdings list, and for displaying the email bookbag contents form.
browse.xsl Main stylesheet for displaying dynamic browsing contents, listed according to a variety of sort keys.
browsecolls.xsl Stylesheet for displaying contents of multiple collection groups, for a cross collection interface.
clipviewer.xsl Works with viewer.xsl for displaying page-image based newspaper article clips.
header.xsl Main stylesheet for displaying item bibliographic header and toc displays. Works primarily with header utils.
pageviewer.xsl Works with viewer.xsl for displaying page-image based monographs or journals.
reslist.xsl Main stylesheet for displaying search results.
searchhistory.xsl Main stylesheet for displaying the search history.
search.xsl Main stylesheet for displaying all search pages, for both individual and cross collection contexts.
text.xsl Main stylesheet for displaying encoded texts.
viewer.xsl Common stylesheet --and the primary work horse-- for buidling the pageviewer and clipviewer displays.
ww.xsl Main stylesheet for displaying the word index search forms.
Global stylesheets incorporated in every page
bookbagitemsstring.xsl This stylesheet is responsible for the content of the string indicating the current number of items in the bookbag. In Release 11, this number was provided via a PI in navheader.chnk file. In Release 12/12a, the content is provided in a separate file referenced by an IFRAME element.
footer.import.xsl This stylesheet contains template rules for displaying the footer portion of the page.
globalvariables.xsl A stylesheet that primarily declares xsl global variables that are utilized by other stylesheets for conditional information.
htmlhead.xsl This stylesheet provides just the html head portion of the resulting page.
navbarutils.xsl This stylesheet works in consort with the navheader.xsl file and contains primarily utility templates for building navigation bar 'tabs.'
navheader.xsl This stylesheet, along with navbarutils.xsl, provides the header portion of each page. This stylesheet is the primary component, along with the collection specific CSS stylesheet, for effecting collection look and feel.
Other sub-sidiary stylesheets
results.xsl This stylesheet does most of the heavy lifting for search results--especially the scoped head and breadcrumb head displays--and also is a utility stylesheet for header toc displays, and for text.xsl displays (since these displays also utilize the scoped heads display methods).
searchforms.xsl This stylesheet, utilized by search.xsl, builds all search forms and replaces all search form chnk files from previous releases. Create local versions of this stylesheet to customize certain options in search forms.
text.components.xsl This stylesheet contains most of the template rules for filtering source XML nodes to html.
headerutils.xsl This stylesheet contains template rules for rendering all forms of bibliographic information to a variety of displays, including header, results, text, browse and pageviewer.
viewer.utils.xsl Utility file for the pageviewer and clipviewer displays
viewtextnote.xsl Provides the warning message and link to the viewing the entire item as encoded text.


Specifying Individual Collection Characteristics

Part 1: Modifying XSL or XML for individual collections

To effect collection-specific changes that involve significant re-arrangement of page components, alternative filtering of source nodes, or changes in language labels in the interface, you can create collection specific XML templates or XSL stylesheets--or both--or you can create local language map xml files. Each approach is discussed in the following examples.

Example 1: Changing language labels in the search page

Refer to the previous code sample from search.xml. All the possible variations for a search form, including restrictions by title/author/citation or genre, date, etc, are included in xml nodes in search.xml and handled conditionally in the xsl depending on current searchtype and collection. For a single collection, an optional restriction is by 'genre'. In the xml template, this is reflected in the node:

<GenreSelect> <?GENRE_SEARCH_SELECT_XML?> </GenreSelect>

When the xml template is processed, the <?GENRE_SEARCH_SELECT_XML?> PI is replaced by a node set for building the form select element called 'singlegenre'

<Label>Prose Fiction</Label>
<Label>Prose Non-fiction</Label>


By default, when searchforms.xsl processes a GenreSelect element, it builds a form select element with the label 'Restrict to genre', as seen in figure 3.


Figure 3

The label 'Restrict to genre,' is, like all language strings in the interface, stored in a langmap.en.xml file and referenced by an XSL key() function, as in

<span class="formfont"><xsl:value-of select="key('get-lookup','searchforms.str.19')"/></span>

The key reference above, retrieves the value, in langmap.en.xml, of the following node:

<Item key="searchforms.str.19">Restrict to genre:</Item>

But a different collection may have the singlegenre field mapped to language, instead of traditional literary genre categories, in which case the label should say 'Restrict to language' instead. Substituting language mappings in Release 12/12a is done by creating a local langmapextra.en.xml file in the collection directory. For this collection--if this was the only language substitution for the entire collection--the contents of the langmapextra.en.xml file would be ...

<Lookup id="searchforms">
<Item key="searchforms.str.19">Restrict to language:</Item>

When search.xml is invoked for the specific collection, the contents of the langmapextra.en.xml file will be inserted just before the class langmap.en.xml file. Because the key() function is being used in a single node context, it will return only the first match it makes, the substituted text.

Example 2: Removing search options from the search page

Almost all variations in search form fields are handled automatically by the combination of search.xml and searchforms.xsl That is, the cgi provides node sets for only those elements in the <SearchForm> node (see search.xml sample above) that are relevant to the current search, and the xsl template rules are invoked depending on search type. The exception to this, however, is the <CiteRestrictions> node, included for the portion of the non-bibliographic search forms that allows bibliographic restrictions. This node may be populated even if the collection doesn't provide the functionality. If this is the case, add a local version of the searchforms.xsl file to the collection directory, and remove those xsl templates that build the fields.

Example 3: Substituting XSL template rules for individual collections

There are a variety of reasons why you might want to substitute specific xsl template rules for a particular collection. Two obvious scenarios are 1) to make a more significant structural change to a page header and 2) to process source content nodes (e.g., notes or heads) differently in the full text display.

Scenario 1 is easy. The change to the header can most likely be effected by altering the templates in navheader.xsl. Simply creating a local version of this file in the collection directory will result in it being referenced by fallback each time a page for that collection in invoked. No other file substitutions are necessary.

Scenario 2 can be done with multiple approaches. If, for example, a collection has slightly different data for a text element, such as an L node for poems, that either needs to account for the occurrence of specific data or output similar data differently. The text.components.xsl file has a template rule for the L node. You could simply copy the text.components.xsl file from the class directory and make a change only in that single template rule, leaving all other rules the same. The fallback mechanism would cause text.xml to include the collection version of text.components.xsl and apply its specific template rule for that node.

More likely, though, you may want to substitute only a single xsl template rule (i.e., just the rule for the L node). If there was no fallback mechanism, text.xml would instead reference a single text.xsl, which could use the xsl:import element and thus exploit the import inheritance rules of xslt. By those rules, text.xsl could import text.components.xsl--which would give it access to all the templates in that stylesheet--and add a local substitute template for any of the imported templates, thus overriding the 'default' behavior of the imported template with the local behavior. You can exploit this inheritance capability within the fallback framework. To do so in the text scenario illustrated here would require the following changes:

  1. Create a local empty version of text.components.xsl. This will cause the cgi to grab the local text.components.xsl when compiling the virtual stylesheet.
  2. In the local text.components.xsl, add an xsl import statements that points to the class text.components.xsl file ...

    <xsl:import href="../../t/text/text.components.xsl"/>
  3. Now any xsl template rules you add to this file will override any template rules imported from the class text.components.xsl stylesheet.

There is a short cut to this procedure that can accomplish the same results for most cases. Simply copy the class text.xsl file to the collection directory and add the substitute template to it. You also should make sure, though, that the the Filename node for text.xsl comes after the node for text.components.xsl in text.xml. The reason for this is that when an xslt processor finds two equally valid template rules for a single node, it executes the last rule found (very similarly to the cascade rule of precedence in CSS).

There are, of course, multiple variations on these approaches to template substitution: you can exploit fallback to invoke any number of alternative xsl inclusions.

Specifying Individual Collection Characteristics

Part 2: Look and Feel

Much of the framework for specifying collection look and feel in earlier releases is retained in Release 12/12a. That is, The main header portion of the page, previously included through a navheader.chnk file, is now compiled from a navheader.xml and navheader.xsl file.The same framework for CSS style deification is also retained, which will apply to almost any font, spacing, or color characteristic of common HTML elements in the result tree. The main change in Release 12/12a in this regard is the inclusion of graphics files: there no longer is a PI to build paths to specifically indicated graphic filenames. All references to common graphics in Release 12/12aa hard-coded to the class graphics directory in XSL templates. To include collection specific graphics will require changing an XSL template rule for that collection (see above). Techniques for CSS and header options are detailed in the following sections.

CSS Files

Text class templates utilize two CSS files for controlling most font and color characteristics: textclass.css and textclass-specific.css. textclass.css is stored in at the <root>/t/text/ path and contains all the default style declarations. textclass-specific.css is created for each individual collection and stored at the <root>/c/coll/ path. Reference paths to both stylesheets are now included as node values within the DlxsGlobals node to each page ...



..and the link elements to the files are constructed in the htmlhead.xsl stylesheet.

Because textclass-specific.css is referenced after textclass.css, any style declarations that appear in textclass-specific.css will effectively overwrite matching declarations in textclass.css. This is how fonts and background colors are varied for each collection. (full text of textclass.css)

When creating a local look and feel with textclass-specific.css, you substitute those CSS style rules that effect portions of the page header (or any other styles) that will override for that collection. Refer to this guide to header css styles for more details on creating the textclass-specific.css file.


Header Characteristics

The header of each page template includes that area in the top 75 pixels of the page containing those elements associated with unique collection identity: main collection title, global links, if any, and the main navigation bar. As of Release 12/12a, all header and navigation components are built primarily by the navheader.xml, navheader.xsl, and navbarutils.xsl files, which are incorporated into each of the main functional template files. The relationship between a main template file (e.g., reslist.xml) and navheader.xsl is illustrated in Figure 4 below.


Figure 4 : Template layout showing division between main template content and the navheader .