This project is read-only.

Template Driven Module Development

Introduction

Template based content generation is widely used in present. Many DotNetNuke modules have an administration page where you can create a HTML template and wrap blocks of content provided by module with your own HTML markup. XsltDb allows you to create content templates editable by webmasters in a few minutes.

ann-template-setup.PNG

Example.

This example demonstrates features of XsltDb that allow you to define and apply templates. All objects are hardcoded into configuration to let you see the whole picture. In next samples below I’ll show how to create webmaster-editable content templates.

<!-- Create a simple template with 2 tags: [IMAGE] and [TITLE]-->
<xsl:variable name="template"><![CDATA[
<div style="width:200px;">
<div style="float:left;">[IMAGE]</div>
[TITLE:Normal]
</div>
]]></xsl:variable>

<!-- Create sample XML thah will be used as a data source when processing template -->
<xsl:variable name="data">
<data>
  <image-url>/images/green-ok.gif</image-url>
  <title>Lorem ipsum dolor sit amet, consectetur adipisicing elit</title>
  <link>http://dotnetnuke.com</link>
</data>
</xsl:variable>

<!-- Create a simple template processor for [title] and [image] tags -->
<mdo:template name="announcement">

<xsl:template name="image">
  <xsl:param name="xml" />
  <img src="{$xml//image-url}" />
</xsl:template>

<xsl:template name="title">
  <xsl:param name="xml" />
  <xsl:param name="p1" />
  <!-- Use calss 'Normal' by default for parameterless [TITLE] tags -->
  <a href="{$xml//link}" class="{mdo:iif($p1, $p1, 'Normal')}">
    {{$xml//title}}
  </a>
</xsl:template>

</mdo:template>

<!-- Apply template and output resulting HTML -->
<xsl:value-of
  select="mdo:apply-template($template, 'announcement', $data)"
  disable-output-escaping="yes" />
Here we see 3 principal sections:
  1. <xsl:variable name="template"> definition of content template
  2. <xsl:variable name="data"> definition of data xml that template will be applied to.
  3. <mdo:template name="announcement"> - definition of template processor descriptor
After we defined that sections we can use mdo:apply-template() function to execute processor and get resulting HTML that can be output to the page.

XsltDb Template Syntax

When XsltDb parses enduser template it searches areas included in square brackets and tries to find appropriate xsl:template inside mdo:template section. If it finds right template it executes found template and replaces tag with the template output. If template is not found XsltDb outputs tag itself. When searching template for a tag XsltDb by default matches tag name and template name. And it also supports a list of optional parameters separated by colons. So if webmaster uses a tag like
  • [TITLE:linkClass:linkTarget]
You can get linkClass and linkTarget as separate template parameters. By default linkClass will be $p1 and linkTarget will be $p2

<xsl:template name="title">
  <xsl:param name="xml" />
  <xsl:param name="p1" />
  <xsl:param name="p2" />
  <a href="{$xml//link}" class="{mdo:coalesce($p1, 'Normal')}">
  <xsl:if test="$p2">
    <xsl:attribute name="target">{{$p2}}</xsl:attribute>
  </xsl:if>
    {{$xml//title}}
  </a>
</xsl:template>

There is a generalized syntax for getting values from underlying XML. If tag starts with "xml/" it is simply translated as XPath expression for the XML passed to mdo:apply-template.
  • [xml/title]
This will be translated to title tag into xml passed to the mdo:apply-template. Actually, "xml/" is replaced by "current()/*/". For example, you can address attributes of root node as
  • [xml/@attr-name]

Template Processor Syntax

Template processor is a section of XsltDb configuration inside mdo:template tag. This section is a set of xsl:template - tags that is used to process tags in content template. Every content template tag matches xslt:template by tag name or regular expression. Every tag template accepts an $xml parameter that is used to access data passed to mdo:apply-template function. This allows us to once create an xml with all data required for the template and then use it in all tag templates without having to query database for each tag.
Every tag can be appended by parameters using colon. But if you want to use custom syntax inside "[…]" you can define regular expression with named groups that will be converted into tag template parameters

<xsl:template name="title">
<regex>title:(?'linkClass')(:(?'linkTarget'))</regex>
  <xsl:param name="xml" />
  <xsl:param name="linkClass" />
  <xsl:param name="linkTarget" />
  <a href="{$xml//link}" class="{$linkClass}">
  <xsl:if test="$linkTarget">
    <xsl:attribute name="target">{{$linkTarget}}</xsl:attribute>
  </xsl:if>
    {{$xml//title}}
  </a>
</xsl:template>
Here attributes are named clearly and linkClass is mandatory when linkTarget is optional. By default all tag parameters are optional.

Template As Module Setting

XsltDb provides mdo:setup that allows you to create settings on module administration page. Now let’s create a module setting where webmaster will provide a custom template. This form must have a tags description section and a template editor area. This can be done as follows:

1. Add an mdo:setup section to the configuration

<mdo:setup>
  <section>Announcement Template Setup</section>
  <markup>
    Setup a template that will be used for each announcement. Use the following tags:
    <ul>
      <li><b>[IMAGE]</b> - Announcement image, rendered as 'img' tag</li>
      <li><b>[TITLE:linkClass:linkTarget]</b> - Title of news that is rendered as 'a'
         tag with the following attributes
         <ul>
           <li><b>linkClass</b> - css class name,</li>
           <li><b>linkTarget</b> - target window to open the article (_blank, _parent, _self, _top)</li>
         </ul>
      </li>
    </ul>
  </markup>
  <setting type="longtext" name="announcement-template"/>
</mdo:setup>
2. Read template value from the settings using hardcoded one as default

<xsl:value-of 
  select="mdo:apply-template(mdo:get-module-setting('announcement-template', $template), 'announcement', $data)"
  disable-output-escaping="yes" />


Applying Template Multiple Times

Here I will show you how to query database and apply template to each row. As a data source I will use a list of packages installed into your DNN host. To reuse XML tags introduced into previous samples I give right names to the columns of record set.

<xsl:variable name="sql">
  select
    Description as title,
    Url as link,
    '/images/green-ok.gif' as [image-url]
  from dnn_Packages where len(Description) &gt; 0
</xsl:variable>
<xsl:for-each select="mdo:sql($sql, 'mod')//mod">
  <xsl:value-of select="mdo:apply-template(
    mdo:get-module-setting('announcement-template', $template), 'announcement', current())"
  disable-output-escaping="yes" />
</xsl:for-each>

Conclusion

As you see you can elegantly hide all logics and defaults of your module letting webmaster to create simple content template with few tags and bring site individual look and feel. Tag templates allow you to use syntax of XsltDb so you can query database and access DNN / ASP.NET objects.

Last edited Aug 9, 2010 at 7:07 AM by findy, version 14

Comments

No comments yet.