Tutorial 4 - Custom Modules

In this tutorial we will look at how to create and use custom modules written in XSL. A custom module is a module defined by an XSL template that provides some custom functionality. A custom module package, or ModPack, is a set of custom modules defined in an XML file. Custom modules can help eliminate a lot of duplicate code and provide some dynamic content.

For example, you may want a custom module that implements the behavior of a navigation bar. In this tutorial we create two pages and add a navigation bar to allow us to navigate from one page to the other. The link for the current page will also be highlighted.

Don't be scared by the XSL here. Chances are you won't need to write your own custom modules. You may be able to find ModPacks that suit your needs or have someone create one for you. But you should learn how to use them. So if you don't understand XSL just skip that section and go on the the next.

The examples can be viewed in the following files.
tutorial/tutorial4/tutorial4a.xml
tutorial/tutorial4/tutorial4b.xml
tutorial/tutorial4/common.xml
tutorial/tutorial4/navigation.xsl

First we need to define the custom module in navigation.xsl. Actually we need two custom modules; One to set the id of the page and another to define a navigation item.

First we'll look at the navItem module. It defines the behavior of a navigation item. A navItem should have an id, a URL that links to a page, and a label. The XSL template matches on the <navItem> element. It creates a span element and sets the font-weight to bold if the id of the navItem matches the id of the page. Then it creates a hyperlink that links to the page.

<xsl:template match="mp:navItem">
  <span>
    <xsl:if test="//mp:navData/@pageId = @id">
      <xsl:attribute name="style">font-weight:bold;</xsl:attribute>
    </xsl:if>

    <a href="{@url}">
      <xsl:value-of select="@label"/>
    </a>
  </span>
</xsl:template>
      

The other module we need matches on the <navData> element and is used only to define the page id. If you look at the navItem template it looks at //mp:navData/@pageId to determine which page we're on. Since this template doesn't need to output any data it doesn't do anything.

<xsl:template match="mp:navData">
  <!-- This module doesn't output anything -->
</xsl:template>
      

Now we will look at how to call these custom modules. They are called similar to a normal module except you can specify attributes for the parameters required by the module, and no name or ref attribute is necessary. Here's how we call the navData module to set the page id.

<mp:navData pageId="page1"/>
      

And here is how we call the navItem module.

<mp:navItem id="page1" label="Page 1" url="tutorial4a.html"/>
      

You should notice how the navItems are defined in the page template in common.xml. Now we have a page layout that includes a banner, a navigation bar, and a section for page content.

After compiling you should see tutorial4a.html created.

<Previous Tutorial