Skip directly to searchSkip directly to the site navigationSkip directly to the page's main content

View System Documentation - XSLT Design

The IBIS-PH View System utilizes XSLT as the presentation layer for virtually all of its available pages. XSLT is a special XML file that contains reserved programming constructs that control/manipulate XML document elements. For the IBIS-PH View System, these XSLTs pull the XML element's data and wrap it within some HTML so that an HTML page can be created based in the XML's data elements. XSLT consists of templates that can either be "called" like a programming language function/method/procedure or can be "matched and applied" in an even driven fashion (as the XML file is being parsed, templates are applied based on the current XML element's tag name). The bulk of the IBIS-PH View System's XSLTs utilize the "called" template approach as it better supports a page layout API implementation (although the "apply/match" templates are also used when applicable). This page provides an overview of the XSLT design and introduces the concept of the system's page layout template API.

This page is not meant to provide much information about how XSLTs work in general nor to document XSLT functions etc. There are many good tutorials and references available on the web that cover this information in great detail. The balance of this page describes the IBIS-PH View System's XSLT API philosophy and design. The IBIS-PH View System XSLT list provides a list of all XSLTs that are available on the system. This list contains a clickable XSLT Filename link that displays that XSLT's internal documentation page. This documentation page offers a description on what that XSLT is used for/contains as well as descriptions and parameter definitions for all of its templates, global variable definitions, and global parameter definitions.

Terminology


XSLT Directory Structure

The XSLT directory structure is key for how this system's XSLTs work. The hierarchy starts with the general XSLT template definitions at the root and gets more page and XML data template specific implementations as the directory hierarchy is traversed deeper. These directories match very closely the main application modules that comprise the IBIS-PH View System.

XSLT Template Definition Precedence and Overrides

The heart of the System's XSLT strategy is the ability to import other XSLTs with the last template definition taking precedence over previously implemented and imported templates and/or variables. Example: If an XSLT file named "a.xslt" contains a template named "myTemplate" and if "b.xslt" imports the "a.xslt" then defines its own template named "myTemplate" the actual template used will be the one defined in the "b.xslt" file because it was the last one defined.

Overriding a defined template with a blank, stubbed out version provides a mechanism to turn off that particular template/code.

File Naming Conventions

The root XSLT directory contains a set of common XSLTs that are used by most pages within the IBIS-PH View System. Files that begin with an underscore "_" represent files that are not directly associated with an end user page. These are files that contain common, imported templates and variables (think of these as template libraries or Java packages). Files that do NOT begin with the "_" character are page creation XSLTs. That is they are used for a specific XML document set to produce a specific type of page to be displayed by the system. For example, the "/_common.xslt" contains generic common, non HTML specific templates that are imported by and used by a page creation XSLT to help create the page. An example a page creation XSLT is the "/query/module/result.xslt" file. This file imports many "_" type XSLTs that define general purpose templates, the page's layout control, site specific template overrides, and related Query Module XML document specific templates. This importing helps keep the file more maintainable as well as providing reusable modular XSLTs. The main body of the "/query/module/result.xslt" templates deals with implementing overridden "html" API templates that are very specific to the query module result XML elements. These overridden "html" templates are the last ones defined which means that they are the ones that take precedence over any other previously defined templates and thus are able to create the desired result page.

XSLT files that are not named with a "Page" contain XSLT code that is a library of templates or an API definition with the variables and templates being named with a "Filename." type prefix.

Template API Naming Conventions

If a template is to be used outside of its file's boundaries (e.g. an API type call, or simply imported for modularity) it should be named with its containing file as a prefix so that an XSLT developer can identify where the template is defined and how it is intended to be used. For example all of the "_html.xslt" templates have a "html." prefix. The "_common.xslt" templates all have a "common." prefix. Templates that are either called or defined that do not have some sort of "name." prefix are defined and used within that XSLT file and should not be called/used outside of that XSLT file. For example the "/query/result/_values_2d.xslt" contains a template named "queryResult2dDataTableRow". This template is internally used by the "values.queryResult2dDataTable" template (which is meant to be called externally). In the Java world, this template would be a protected or private method.

XSLT Basic Template Design

To allow for different agencies to customize the IBIS-PH View System to their own look and needs, and to help keep the site's pages consistent and as maintainable, a basic XSLT API and file directory structure was implemented. The heart of this is XSLT's ability to import other XSLTs with the last template definition taking precedence over previously implemented and imported templates and/or variables. The XSLT directory structure is also a key for this system as the XSLTs are organized in a hierarchy starting with the general XSLT template definitions at the root and going down into more specific system module/section implementations. The IBIS-PH View System's XSLTs that produce the actual page are located in lower directory levels. They typically import upper directory XSLTs which contain the more general/generic shared templates and API page definition templates. The more general/generic XSLTs are imported first followed by importing more module specific XSLTs (which may include overriding already defined templates). The page specific XSLTs finally implement XML element page specific templates (which again may include overriding previously defined imported templates). The following diagram shows this template import relationship with general layout templates being imported first with the latter XSLT templates specific to the actual XML data elements.



HTML API

The core page layout control API is defined in a file named "_html.xslt" which is located in the root XSLT directory structure. The main point of this XSLT is to define a page layout control structure. Pages are built by the main control structure template calling a series of named and templates (kind of like an API). Most of the templates contained within the file are directly related to the control structure. The other non layout related templates contained within the file are simply common HTML related helpers that are kept in the file for convenience and because they generate HTML elements. For the page layout templates, most contain HTML code and calls to other "html." templates. Other layout related templates are simply stubbed out API type templates much like a Java abstract class. These stubbed out templates are intended to be implemented in more page specific XSLTs or within a localized "_html.xslt" or "SiteSpecific.xslt". These stubbed templates need to exist so that the system will function (if a template is called and it is not defined the transformation will fail). The following diagram shows the basic layout and template APIs provided and used by all of the system's XSLTs used to create HTML output pages.


Note that the orange sections are meant to be implemented in site specific XSLTs

Local XML Specific "html." Templates

Some XSLT module/section/sub-directories contain a file named "_html.xslt". These XSLTs contain XML or page specific "html.xxxxx" templates. This XSLT will only contain "html." template overrides for the specific page and the specific XML data elements. An example of this is the indicator profile org units vs. the query module org units. Both show the same org unit information but both differ on their XML structure and thus need specialized templates to pull the appropriate org unit data. So a small "_html.xslt" file is located within that specific directory that contains the code to deal with how to lookup that particular XML's org unit element.

Site Specific

In every XSLT module/section/sub-directory there should be a file named "SiteSpecific.xslt". This is a hooking mechanism that allows each module's/section's XSLT files within the system to contain any site specific/deployment specific overridden XSLT template code. This is also a file where new site specific APIs can be defined. Unlike the stubbed out API templates these files do NOT need to exist for the system to function. However, it is strongly recommended that they be left as blank files (or with internal XML comments) so that it is a documented part of the system.

Utah's HTML and Site Specific API

The following diagram shows the Utah page layout implementation. The main change from the standard HTML templates is overriding the standard, previously defined "html.contentContainer" template with a site specific version that implements an HTML table. This new site specific version calls a template named "siteSpecific.leftNavigation" for its left cell's contents then calls the standard "html.content" template called for its right cell's contents. The "siteSpecific.leftNavigation" template is defined at a high and is implemented as an API extension which is meant to be overridden as needed in sub "SiteSpecific.xslt" files. Utah also implements specific banner, header, and footer templates as well as some module specific Milonic Menu Javascript code implemented in the overridden "html.otherJavascript" template.




XSLT Transformation Caching Note: The IBIS-PH View System utilizes XSLT transformer caching to improve system performance. If an imported XSLT is modified, the application needs to be reset or the XSLT cache cleared because the cache only checks the main XSLT container file's date and time or modification (it does not check for any included or imported XSLT file changes). Another way to reset/clear the cache is to restart the Java application server.

Internal XSLT Documentation

The XSLTs created for the system have a special documentation feature. Utilizing the "xmlns:doc" XML namespace, a special documentation XSLT is used to pull documentation information from the source XSLT to build a page that describes that XSLT. This page includes a summary of what that XSLT is used to create, what XSLTs it imports, what each template does, a description of each of the template's parameters, descriptions of applied templates etc.

Note that for every XSLT that has a "doc:" element/attribute, the special XSLT result output prefix exclusion should be included. If it is not, then the HTML containing element will have a "doc:" namespace element attribute definition. This is true for ALL XSLTs regardless of whether it is imported with the main container XSLT having the statement or not.

Example: 
<xsl:stylesheet version="1.0"
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
	xmlns:doc="http://www.ibisph.org/xslt/doc"

	exclude-result-prefixes="doc"
>

For an XSLT to be included in the system's XSLT documentation an entry needs to be made in the "xml/doc/xslt_list.xml" XML file that provides the XSLT filename to be documented.