Select Parameters Utility: Example

The Select Parameters Utility helps you create dynamic web pages. You can use it to let users of your webpages select the parameters that they want to apply within the stylesheet.

This page gives a simple example of using the Select Parameters Utility to allow users to select what function they want to see an explanation of. Say you had some XML like: 

<functions>
  <function>
    <defn>string concat(string, string, string*)</defn>
    <desc>The concat function returns the concatenation of its arguments.</desc>
  </function>
  <function>
    <defn>boolean starts-with(string, string)</defn>
    <desc>The starts-with function returns true if the first argument string starts with
    the second argument string, and otherwise returns false.</desc>
  </function>
  <function>
    <defn>boolean contains(string, string)</defn>
    <desc>The contains function returns true if the first argument string contains the
    second argument string, and otherwise returns false.</desc>
  </function>
  <function>
    <defn>string substring-before(string, string)</defn>
    <desc>The substring-before function returns the substring of the first argument string
    that precedes the first occurrence of the second argument string in the first argument
    string, or the empty string if the first argument string does not contain the second
    argument string. For example, substring-before("1999/04/01","/") returns 1999.</desc>
  </function>
  <function>
    <defn>string substring-after(string, string)</defn>
    <desc>The substring-after function returns the substring of the first argument string
    that follows the first occurrence of the second argument string in the first argument
    string, or the empty string if the first argument string does not contain the second
    argument string. For example, substring-after("1999/04/01","/") returns 04/01, and
    substring-after("1999/04/01","19") returns 99/04/01.</desc>
  </function>
</functions>

And you have a stylesheet that uses a parameter to determine what function to display: 

<xsl:param name="function" select="'starts-with'" />

<xsl:template match="/">
  <html>
    <head>
      <title>Function Descriptions</title>
    </head>
    <body>
      <h1>Function Descriptions</h1>
      <xsl:apply-templates select="functions/function[contains(defn, concat($function, '('))]" />
    </body>
  </html>
</xsl:template>

<xsl:template match="function">
  <h2>Function: <xsl:value-of select="defn" /></h2>
  <p><xsl:value-of select="desc" /></p>
</xsl:template>

You want to let your users select which function they want to view the details of dynamically, using a drop-down list.

First, you need to import the selectParameters stylesheet into your stylesheet: 

<xsl:import href="selectParameters.xsl" />

Second, you need to call the 'insert-selectParameters-form' template at the point within your stylesheet where you want the form to be placed, for example: 

<xsl:template match="/">
  <html>
    <head>
      <title>Function Descriptions</title>
    </head>
    <body>
      <h1>Function Descriptions</h1>
      <p>Select the function that you wish to learn about:</p>
      <xsl:call-template name="insert-selectParameters-form" />
      <xsl:apply-templates select="functions/function[contains(defn, concat($function, '('))]" />
    </body>
  </html>
</xsl:template>

Third, you need to add the 'http://www.jenitennison.com/xslt/doc' namespace to your stylesheet as an extension prefix, which means adding a namespace declaration and the 'extension-element-prefixes' attribute to the xsl:stylesheet element, to give something like: 

<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:doc="http://www.jenitennison.com/xslt/doc"
                extension-element-prefixes="doc">

Finally, you need to add some documentation within your stylesheet for the parameter that you want the users to be able to change. This should give a label for the form where they select the value of the parameter, and give any options for that parameter if applicable. The 'name' attribute of the 'doc:param' element should be the same as the name of the parameter that you're documenting. 

<doc:param name="function">
  <doc:label>Function: </doc:label>
  <doc:choice><doc:value>concat</doc:value><doc:choice>
  <doc:choice><doc:value>starts-with</doc:value><doc:choice>
  <doc:choice><doc:value>contains</doc:value><doc:choice>
  <doc:choice><doc:value>substring-before</doc:value><doc:choice>
  <doc:choice><doc:value>substring-after</doc:value><doc:choice>
</doc:param>

See the end result [only in MSXML July or later] .

More Information

Instructions

Parameter Documentation

How it Works

/xslt/utilities/selectParameters-example.xml by Jeni Tennison; generated using SAXON 6.5 from Michael Kay