Starting out with XSLT in Umbraco

Posted on March 20, 2010 by Frederik Vig in Umbraco

I’ve just started learning Umbraco, which is a popular open source content management system, originally from Danmark, but now with developers across the world. Umbraco stores much of its data as XML in the database, and recommends using XSLT for transforming it to HTML. You can however use regular ASP.NET code if you wish (or a mix of both).

I’m a beginner when it comes XSLT so I browsed through a few tutorials, and read the XSLT recommendation by W3C (along with the XPath and XQuery recommendations), and the Umbraco XSLT reference, to learn the syntax.

Umbraco XSLT snippets

After I was at the point where I could read XSLT (at least the simple ones), and understand it. I created a new blank Umbraco site locally, logged into the administration interface and the developer section.

developer section in Umbraco

Here you can create new XSLT files that you can use in your Umbraco Macros. The cool thing is that Umbraco comes with a few XSLT snippets for the most used tasks.

  • Clean
  • Breadcrumb
  • List Sub Pages As Thumbnails
  • List Sub Pages By Date And Limit
  • List Sub Pages By Document Type
  • List Sub Pages By Level
  • List Sub Pages From A Changable Source
  • List Sub Pages From Current Page
  • List Thumbnails From Current Page
  • List Whole Structure From Current Page
  • Navigation Prototype
  • Related Links
  • RSS Feed
  • Sitemap
  • Table Prototype

These are actually just .xslt files that live in the <site root folder>/umbraco/xslt/templates folder. Here you can modify or add more XSLT snippets if you like. This is also useful if you like to open them in XMLSpy or Visual Studio for intellisense and syntax highlighting.

Custom XSLT snippet in Umbraco

Testing XSLT in Umbraco

Umbraco also gives you the ability to easily test your XSLT. When you open up a XSLT file in Umbraco, you have the “Visualize XSLT” button at the top. Select the XSLT you wish to test, and click “Visualize XSLT”.

Visualize XSLT in Umbraco button

This will open up a dialog where you can choose content pages that you can use to test with.

Visualize XSLT in Umbraco dialog

XML stored in Umbraco database

Umbraco stores much of its content as XML, if we take a look at the table cmsContentXml in an Umbraco database, you can see how the XML is structured.

<node id="1048" version="b4a59e09-6b0e-49fb-93ce-31282bca9cbf" parentID="-1" level="1" writerID="0" creatorID="0" nodeType="1045" template="1042" sortOrder="1" createDate="2008-05-02T09:52:36" updateDate="2010-03-18T21:21:38" nodeName="Runway Homepage" urlName="runway-homepage" writerName="Administrator" creatorName="Administrator" nodeTypeAlias="RunwayHomepage" path="-1,1048">
    <data alias="bodyText"><![CDATA[<p>Runway gives you a bare-bones website that introduces you to a set of well-defined conventions for building an umbraco website.</p> <p>The Runway website is very simple in form and provided without any design or functionality. By installing Runway, you&rsquo;ll begin with a minimal site built on best practices. You&rsquo;ll also enjoy the benefits of speaking the same &ldquo;language&rdquo; as the rest of the umbraco community by using common properties and naming conventions.</p> <p>Now that you know what Runway is, it is time to get started using Runway.</p>]]></data>
    <data alias="siteName">Runway</data>
    <data alias="siteDescription"><![CDATA[Off to a great start]]></data>
</node>

If we use the “Insert xslt:value-of” wizard to insert a new <xsl:value-of> element, we see that the XML elements and attributes from the database get populated in the “prevalues” select box for us.

Insert xslt:value-of wizard

New properties we add the our document types will automatically get added here as well.

Good to know

When going through the various XSLT snippets that Umbraco provides, you’ll notice a lot of the same code, some is from the built in functionality that Umbraco offers, others are more conventions that the Umbraco community use. The umbracoNaviHide property is a good example of such a convention.

<xsl:for-each select="$currentPage/node [string(data [@alias='umbracoNaviHide']) != '1']">

umbracoNaviHide is a boolean property that the editor can use to hide a page from navigation. That is what this part checks for.

[string(data [@alias='umbracoNaviHide']) != '1']

Since umbracoNaviHide is a boolean property, 1 is true and 0 is false. Notice the syntax for the none built in properties.

data [@alias='umbracoNaviHide'])

The xml in the database looks like this.

<data alias="umbracoNaviHide">1</data>

There are more properties that are good to know about. For an up-to-date list see Umbraco’s wiki.

Other resources

Related Posts: