XslGenerator Pager
Overview
The XslGenerator includes an optional feature to add page numbers and a search results summary at the bottom of your XSL output, as shown below:
If your results are sorted alphabetically, you may also add a pager with letters for each result. Each letter is hyperlinked to go to the first page with a response beginning with that letter:
Additionally, a results summary may also be output in addition to the pager, as shown in the illustration above of the numeric pager.
Basic Paging – Numeric Pager
If your XML document contains a basic root node with multiple child nodes, for example, a root node called <MemberRoster> with multiple sub-nodes called <Member>:
<?xml version='1.0' encoding='UTF-8'?>
<MemberRoster>
<Member>
<name>John Smith</name>
</Member>
<Member>
<name>Karen Jones</name>
</Member>
<Member>
<name>Father McKenzie</name>
</Member>
</MemberRoster>
If this is your document structure, and you want to page through the <Member>nodes, then you will need to do the following:
a. In the web page content detail definition, you must include the {BeginPagerProperties} metatags with the number of records you want to see per page, as shown here, and the {BeginPagerPropertiesAlphaElement} to specify which Node in the XML to drive paging. (The metatags are case sensitive):
{BeginPagerProperties}10{EndPagerProperties}
{BeginPagerPropertiesAlphaElement}NameOfNodeOnWhichToPage{EndPagerPropertiesAlphaElement}
If you omit this step, the XslGenerator will not build the pager, even if you do steps (b) and (c) below
b. In the XSL stylesheet, you need to add one Xslt Stylesheet Parameter under the stylesheet definition as shown here:
<xsl:param name="pagerNumeric" />
c. Locate the place in your stylesheet where you want the pager bar to appear and add the following:
<xsl:value-of select="$pagerNumeric" disable-output-escaping="yes"/>
Once you have modified your XSL stylesheet, it might look similar to this. Line 3 adds the XSL style sheet parameter, and Line 13 outputs the pager.
Using the Alpha Pager
The alpha pager can be used only when the XML document is already sorted alphabetically by a meaningful data element. The XslGenerator will not resort a document (although you can do sorting through XSL in the XSL stylesheet). To use the alpha pager, you must include the Xml element name on which you want to index the pager between the {BeginPagerPropertiesAlphaElement} and {EndPagerPropertiesAlphaElement} metatags as shown:
{BeginPagerPropertiesAlphaElement}Name{EndPagerPropertiesAlphaElement}
In the example above, the element <Name> must is an XmlElement within the XML node that drives the paging. This value is case sensitive. You must also include the {BeginPagerProperties} metatags with the number of records to show per page.
You may then output the alpha pager where desired by using the pagerAlpha Xslt stylesheet parameter as shown below on lines 4 and 15:
You may also want to include both the numeric and alpha pagers, although it might be confusing to an end user. Generally, if it makes sense to use the alpha pager, then choose it.
Paging Through More Complex Xml Documents
Your XML document might contain a root node and then a nested subnode through which you want to use alpha or numeric paging, for example, a RSS feed in which you want to page through multiple <item> nodes:
<?xml version='1.0' encodeing='UTF-8'>
<rss version='2.0'>
<channel>
<title>RSS Feed</title>
<item>
<title>Short Term Forecast - Wise (Virginia></title>
</item>
<item>
<title>Short Term Forecast - Scott (Virginia></title>
</item>
<item>
<title>Short Term Forecast - Fairfax (Virginia></title>
</item>
</channel>
</rss>
For this XML document, you want the pager to key off the <item> nodes.
Therefore, you must include in the page detail definition add the {BeginPagerPropertiesNode} metatags and enclose the name of the node that should drive the paging:
{BeginPagerPropertiesNode}item{EndPagerPropertiesNode}
The complete definition might look like this:
{BeginPostUrl}http://nytimes.com/services/xml/rss/nyt/HomePage.xml{EndPostUrl}
{BeginXslFileName}style/xsl/rss4.xsl{EndXslFileName}
{BeginPagerProperties}10{EndPagerProperties}
{BeginPagerPropertiesNode}item{EndPagerPropertiesNode}
Restriction on Depth of XML
The pager can work on XML documents that iterate through a node that is at most three nodes deep. For example, you can apply paging to the <State> node to this kind of xml:
<?xml version="1.0" encoding="utf-8"?>
<Country>
<Name>United States</Name>
<States>
<State>
<Name>Alabama</Name>
</State>
<State>
<Name>New Jersey</Name>
</State>
<State>
<Name>Virginia</Name>
</State>
</States>
</Country>
Your pager would look like this:
A N V
The pager would break down, though, by adding an additional <Countries> dimension. The pager cannot iterate through a two-dimensional list as shown below:
<?xml version="1.0" encoding="utf-8"?>
<Countries>
<Country>
<Name>Canada</Name>
<States>
<State>
<Name>Alberta</Name>
</State>
<State>
<Name>Ontario</Name>
</State>
<State>
<Name>Quebec</Name>
</State>
</States>
</Country>
<Country>
<Name>United States</Name>
<States>
<State>
<Name>Alabama</Name>
</State>
<State>
<Name>New Jersey</Name>
</State>
<State>
<Name>Virginia</Name>
</State>
</States>
</Country>
</Countries>
In this instance, the <State> nodes would start to repeat each time you get to a new country, which make paging not very intuitive for an end user who would be looking at something like:
A N J A O Q
If you wanted to look for Alaska, which "A" would you click on? The first or the second? For this reason, the Pager will not function if the Element you indicate is in the 4th level or deeper.
Therefore, this feature should be used on reasonably sized lists that have one level of sorting and where that sorting is on the 3rd or 2nd tier of nodes.
Your overall XML document can go deeper than 3 nodes, but the element on which you're paging must be at most the 3rd tier.
Using the Results Pager Summary
To include the summary results pager, you simply need to include the built-in XSL style sheet parameter element called pagerResults in your XSL document and then output it as shown below. The Xslt stylesheet parameter is shown below on lines 4 and 13:
The XslGenerator also allows the use of these integer Xslt parameters if needed. These parameters are added automatically if you include the {PagerProperties} metatags in your page detail:
- pagerResultsRecordsFrom – the first record shown on the current page
- pagerResultsRecordsTo – the last record shown on the current page
- pagerResultsRecordsCount – the total number of records returned.
These additional two parameters have been added for 2007.01 for additional personalization of a page:
- pagerPreviousURL - the URL portion that is in the "<< Previous" hyperlink.
- pagerNextURL - the URL portion that is in the "Next >>" hyperlink.
Possible usage:
<a href="{$pagerNextURL}"><img src="next.gif" /></a>
Troubleshooting
Q. The pager and all other content is disappearing when I click the pager and there's a message in the error log - "Unable to transform xml through xsl therefore cannot render page. Error: Root element is missing."
A. The root problem is eWeb lacks permission to write to the \CacheRoot folder. Give the "Internet Guest Account" write permission to the \CacheRoot folder. Even if the caching system options are turned off, these privileges are still needed. For more information see XslGenerator Cache
Q. I'm trying to page through a complex document and I cannot get it to output. It just says "No records found". Why won't it work?
A. Could you be trying to iterate through a node that is 4 levels deep, or deeper? See the section above for more guidance.
Q. I added the {BeginPagerProperties} metatag and the XSL parameters to my XSL, and now nothing longer displays.
A. Make sure you also add the {BeginPagerPropertiesAlphaElement} metatags as described above.
Q. Why do I need to add the {BeginPagerPropertiesAlphaElement} metatags when I'm using the Numeric pager and not the Alpha pager?
A. The XslGenerator needs to know which xml node on which to drive pagination, and the {BeginPagerPropertiesAlphaElement} metatags specify the name of the xml node to use. This metatag probably should have been named differently to prevent misleading people into thinking it's used only for the Alpha pager when in fact both the numeric and the alpha pagers use this metatag.