Example

Part of the installation of ITP/OnLine is a custom1.zip file. This file contains an example extension to an ITP/OnLine application. This extension serves to illustrate xslt customization. The customization in the custom1 application adds buttons at the top of the forms, so that the end user doesn't have to scroll down to submit a long form.

The custom1 application is not installed by default. In order to install it, follow these steps:

• Go to the configuration page of your ITP/OnLine installation. Refer to the Configuration chapter in the general ITP/OnLine Server Manual for more information on this subject.
• In the field Application Name, fill out "custom1" and click Submit.
• In the folder OnLine application, a subfolder custom1 will be created. Copy the contents of the subfolder sample2 to this location.
• Unzip the contents of the custom1.zip file to the subfolder. Make sure the unzip does not introduce an extra level custom1; a subfolder xslt should occur immediately below the existing folder custom1.
• For ITP/OnLine ASP.NET only, go back to the configuration page and click the link Deploy next to the application custom1.

The application custom1 is an addition to the application sample2 that is installed by default. It adds the following files:

• \css\topbuttons.css. A css file with a small number of extra style definitions for the new buttons.
• \xslt\custom\button.xsl. An xsl-file that overrides the templates produceButtons, produceButton, and produceButtonLabel from the Customization Layer. These templates produce the actual buttons.
• \xslt\custom\form.xsl. An xsl-file that overrides the template produceFormBody from the Customization Layer. This template positions the buttons at the top of the form.
• \xslt\custom\page.xsl. An xsl-file that overrides the template producePageCSS from the Customization Layer. This template includes the additional topbuttons.css stylesheet.

The other files in the folder \xslt\custom are irrelevant. They merely serve as a starting point for other customizations. Uncomment a template in order to override it.

Important general features illustrated by the customization are:

• The use of the custom parameter to distinguish between traversals.
• Reuse of default behavior by calling the _default templates. This avoids unnecessary duplication of code.

The override of the template produceFormBody looks like this:

<xsl:template name="produceFormBody">

  <xsl:param name="interactinfo"/>

  <xsl:param name="custom"/>

  <!-- an additional table with a single row of buttons at the top of the form -->

  <tr>

    <td>

      <xsl:call-template name="produceButtons">

        <xsl:with-param name="interactinfo" select="$interactinfo"/>

        <xsl:with-param name="custom" select="'topbuttons'"/>

      </xsl:call-template>

    </td>

  </tr>

  <xsl:call-template name="produceFormBody_default">

    <xsl:with-param name="interactinfo" select="$interactinfo"/>

    <xsl:with-param name="custom" select="$custom"/>

  </xsl:call-template>

</xsl:template>

This introduces an extra row with buttons above the standard content of the form. The content of this row is determined by a call to the template produceButtons. This introduces an extra traversal of the buttons in the XForms. In order to distinguish this traversal from the standard traversal, which produces the standard buttons, the value topbuttons is passed for the 'custom' parameter. This illustrates the intended use of this parameter.

The override of the template produceButtons looks like this:

<xsl:template name="produceButtons">

    <xsl:param name="interactinfo"/>

    <xsl:param name="custom"/>

    <xsl:choose>

      <xsl:when test="$custom='topbuttons'">

        <div class="topbuttons">

          <!-- only produce the ok and the back button (css will order) -->

          <xsl:call-template name="applyNamedButtons">

            <xsl:with-param name="names" select="'ok back1'"/>

            <xsl:with-param name="custom" select="$custom"/>

          </xsl:call-template>

        </div>

      </xsl:when>

      <xsl:otherwise>

        <xsl:call-template name="produceButtons_default">

          <xsl:with-param name="interactinfo" select="$interactinfo"/>

          <xsl:with-param name="custom" select="$custom"/>

        </xsl:call-template>

      </xsl:otherwise>

    </xsl:choose>

  </xsl:template>

Based on the value of the custom parameter, the template either produces the new buttons or falls back on default behavior. At the top of the form only the buttons OK and (possibly) the Back are produced inside a div with class "topbuttons". This is done by:

• calling the template applyNamedButtons from the Support Library,
• passing identifications of the buttons to be produced (space separated),
• passing the value topbuttons for the custom parameter.

The template applyNamedButtons will pass this value on to the template produceButton. The order in which the identifiers are passed determines the order in which the corresponding buttons are produced. Buttons are only produced when they are part of the XForms.

Even though we want the Back button to be presented to the left of the OK button, we produce the latter first. This is because we want the OK button to be the default button on the form. The positioning of the buttons on the page will be arranged in the cascading stylesheet.

The override of the template produceButton looks like this:

  <xsl:template name="produceButton">

    <xsl:param name="buttoninfo"/>

    <xsl:param name="custom"/>

    <xsl:choose>

      <xsl:when test="$custom='topbuttons'">

        <button id="{$buttoninfo/submission}" name="{$buttoninfo/submission}" type="submit" class="{$buttonclassbase}">

          <xsl:attribute name="onClick">

            setSubmission('<xsl:value-of select="$buttoninfo/submission"/>');

          </xsl:attribute>

          <xsl:call-template name="produceButtonLabel">

            <xsl:with-param name="buttoninfo" select="$buttoninfo"/>

            <xsl:with-param name="custom" select="$custom"/>

          </xsl:call-template>

        </button>        

      </xsl:when>

      <xsl:otherwise>

        <xsl:call-template name="produceButton_default">

          <xsl:with-param name="buttoninfo" select="$buttoninfo"/>

          <xsl:with-param name="custom" select="$custom"/>

        </xsl:call-template>

      </xsl:otherwise>

    </xsl:choose>   

  </xsl:template>

Again, the custom parameter determines whether or not to fall back on default behavior. The new buttons are produced directly below the div that was produced by the template produceButtons. The button label is produced by calling the template produceButtonLabel, again passing the value topbuttons for the custom parameter.

The override of the produceButtonLabel template looks like this:

  <xsl:template name="produceButtonLabel">

    <xsl:param name="buttoninfo"/>

    <xsl:param name="custom"/>

    <xsl:choose>

      <xsl:when test="$custom='topbuttons'">

        <xsl:choose>

          <xsl:when test="$buttoninfo/submission='ok'">

            <xsl:text disable-output-escaping="yes">&amp;gt;&amp;gt;</xsl:text>

          </xsl:when>

          <xsl:when test="$buttoninfo/submission='back1'">

            <xsl:text disable-output-escaping="yes">&amp;lt;&amp;lt;</xsl:text>

          </xsl:when>

          <xsl:otherwise>

            <xsl:call-template name="produceButtonLabel_default">

              <xsl:with-param name="buttoninfo" select="$buttoninfo"/>

              <xsl:with-param name="custom" select="$custom"/>

            </xsl:call-template>

          </xsl:otherwise>

        </xsl:choose>

      </xsl:when>

      <xsl:otherwise>

        <xsl:call-template name="produceButtonLabel_default">

          <xsl:with-param name="buttoninfo" select="$buttoninfo"/>

          <xsl:with-param name="custom" select="$custom"/>

        </xsl:call-template>

      </xsl:otherwise>

    </xsl:choose>   

  </xsl:template>

Again, the custom parameter determines whether or not to fall back on default behavior. The buttons OK and Back will respectively be represented by >> and <<.

The override of the template producePageCSS looks like this:

  <xsl:template name="producePageCSS">

    <xsl:param name="interactinfo"/>

    <xsl:param name="custom"/>

    <xsl:call-template name="producePageCSS_default">

      <xsl:with-param name="interactinfo" select="$interactinfo"/>

      <xsl:with-param name="custom" select="$custom"/>

    </xsl:call-template>

    <link rel="stylesheet" type="text/css" href="css\topbuttons.css"/>

  </xsl:template>

This template simply adds a reference to the topbuttons.css stylesheet, again using the default behavior to produce the standard set of references. The template topbuttons.css contains a small number of style instructions, making sure that the buttons are rendered a bit smaller and that the OK button is presented to the right of the Back button.

A visual representation of these customizations can be found in Appendix B.