Learning Umbraco in a week - Day III

 

This is my fifth post of the "Learning Umbraco in a week" series. The main agenda of this post is listed below.

• Introduction to XSLT
• Introduction to XPath
• Basic Structure of XSLT
• How to link XSL Stylesheet to an XML Document?
• How to apply XSL Transform?

Introduction to XSLT 

XSLT is a document that is applied programmatically to an XML Document to manipulate the data. However, the structure of XSLT resembles that of XML, and contains specialized tags to perform specific actions to the data. 

Introduction to XPath 

XPath is a language for navigating in XML documents. Moreover, XPath is used by XSLT to find information in an XML document. 

Basic Structure of XSLT 

The structure of XSLT resembles that of XML, and contains specialized tags to perform specific actions to the data. 

1. Top Declarations 

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE xsl:stylesheet [ <!ENTITY nbsp "&#x00A0;"> ]>
        <xsl:stylesheet     version="1.0"     
            xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
            xmlns:msxml="urn:schemas-microsoft-com:xslt"
            xmlns:umbraco.library="urn:umbraco.library"
            exclude-result-prefixes="msxml umbraco.library">
        <xsl:output method="xml" omit-xml-declaration="yes" />
 
2. The XML declaration
    <?xml version="1.0" encoding="UTF-8"?>

3. The root element that declares the document to be an XSL style sheet is <xsl:stylesheet> or <xsl:transform>.
    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    or
    <xsl:transform version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

4. Parameter Declaration
    This is optional but a very important declaration, as it is the default link to the content published in the site.

    <xsl:param name="currentParam" />

5. Template Declaration
    This is the portion that is responsible for the processing and the output.

    <xsl:template match="/">
    …
    </xsl:template>

6. Closing the Style Sheet
    We close out the stylesheet, since this is XML, everything must be properly structured.

    </xsl:stylesheet>
    or
    </ xsl:transform > 

How to link XSL Stylesheet to an XML Document? 
To link XSL Stylesheet to an XML Document, add the XSL style sheet reference to the XML document, e.g. "sample.xml".

    <?xml-stylesheet type="text/xsl" href=“sample.xsl"?>

How to apply XSL Transform? 
The most easiest way to apply XSL Transforms over an XML Document or Node is by using the Template Element. 

A sample XML Document or Node used in the examples.

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <catalog>
        <cd>
            <title>Empire Burlesque</title>
            <artist>Bob Dylan</artist>
            <country>USA</country>
            <company>Columbia</company>
            <price>10.90</price>
            <year>1985</year>
        </cd>
        . . .
    </catalog> 

A list of XSL Elements commonly used in Transformations are listed below. 

1. The <xsl:template> Element 
A template contains rules to apply when a specified node is matched. The match attribute is used to associate a template with an XML element. The match attribute can also be used to define a template for the entire XML document. The value of the match attribute is an XPath expression (i.e. match="/" defines the whole document).

For example

    <xsl:template match="/">
        <h2>My CD Collection</h2>
        <table border="1">
            <tr bgcolor="#9acd32">
                <th>Title</th>
                <th>Artist</th>
            </tr>  
            …
        </table>
    </xsl:template>

2. The <xsl:value-of> Element 
The <xsl:value-of> element is used to extract the value of a selected node. The select attribute contains an XPath expression. An XPath expression works like navigating a file system; a forward slash (/) selects subdirectories.

For example

    <xsl:template match="/">
        <h2>My CD Collection</h2>
        <table border="1">
            <tr bgcolor="#9acd32">
                <th>Title</th>
                <th>Artist</th>
            </tr>
            <tr>
                <td>
                    <xsl:value-of select="catalog/cd/title"/>
                </td>
                <td>
                    <xsl:value-of select="catalog/cd/artist"/>
                </td>
            </tr>
        </table>
    </xsl:template>

3. The <xsl:for-each> Element 
The <xsl:for-each> element allows you to do looping in XSLT. Filtering the output by adding a criterion to the select attribute in the <xsl:for-each> element.

    <xsl:for-each select="catalog/cd[artist='Bob Dylan']">

Legal filter operators in XSLT are listed below.

• =  (equal)
• != (not equal)
• &lt; less than
• &gt; greater than

For example

    <xsl:template match="/">
        <h2>My CD Collection</h2>
        <table border="1">
            <tr bgcolor="#9acd32">
                <th>Title</th>
                <th>Artist</th>
            </tr>
            <xsl:for-each select="catalog/cd">
                <tr>  
                    <td><xsl:value-of select="title"/></td>
                    <td><xsl:value-of select="artist"/></td>
                </tr>
            </xsl:for-each>
        </table>
    </xsl:template>

4. The <xsl:sort> Element 
The <xsl:sort> element is used to sort the output. To sort the output, simply add an <xsl:sort> element inside the <xsl:for-each> element. The select attribute indicates what XML element to sort on.

For example

    <xsl:template match="/">
        <h2>My CD Collection</h2>
        <table border="1">
            <tr bgcolor="#9acd32">
                <th>Title</th>
                <th>Artist</th>
            </tr>
            <xsl:for-each select="catalog/cd">
                <xsl:sort select="artist"/>
                    <tr>
                        <td><xsl:value-of select="title"/></td>
                        <td><xsl:value-of select="artist"/></td>
                    </tr>
                </xsl:sort>
            </xsl:for-each>
        </table>
    </xsl:template>

5. The <xsl:if> Element 
The <xsl:if> element is used to put a conditional test against the content of the XML.

<xsl:if test="expression">
    ...some output if the expression is true...
</xsl:if>

The value of the required test attribute contains the expression to be evaluated.

For example

    <xsl:template match="/">
        <h2>My CD Collection</h2>
        <table border="1">
            <tr bgcolor="#9acd32">
                <th>Title</th>
                <th>Artist</th>
            </tr>
            <xsl:for-each select="catalog/cd">
                <xsl:if test="price &gt; 10">
                    <tr>
                        <td><xsl:value-of select="title"/></td>
                        <td><xsl:value-of select="artist"/></td>
                    </tr>
                </xsl:if>     
            </xsl:for-each>   
        </table>   
    </xsl:template>

6. The <xsl:choose> Element 
The <xsl:choose> element is used in conjunction with <xsl:when> and <xsl:otherwise> to express multiple conditional tests.

<xsl:choose>
    <xsl:when test="expression">
        ... some output ...
    </xsl:when>
    <xsl:otherwise>
        ... some output ....
    </xsl:otherwise>
</xsl:choose>

The value of the required test attribute contains the expression to be evaluated.

For example

    <xsl:template match="/">
        <h2>My CD Collection</h2>
        <table border="1">
            …
            <xsl:for-each select="catalog/cd">
                <tr>
                    <td><xsl:value-of select="title"/></td>
                    <xsl:choose>
                        <xsl:when test="price &gt; 10">
                            <td bgcolor="#ff00ff"><xsl:value-of select="artist"/></td>
                        </xsl:when>
                        <xsl:otherwise>
                            <td><xsl:value-of select="artist"/></td>
                        </xsl:otherwise>
                    </xsl:choose>
                </tr>
            </xsl:for-each>
        </table>
    </xsl:template>

7. The <xsl:apply-templates> Element 
The <xsl:apply-templates> element applies a template to the current element or to the current element's child nodes. If we add a select attribute to the <xsl:apply-templates> element it will process only the child element that matches the value of the attribute. We can use the select attribute to specify the order in which the child nodes are processed.

For xample

    <xsl:template match="/">
       <html>
            <body>
                <h2>My CD Collection</h2>
                 <xsl:apply-templates/>
            </body>
        </html>
    </xsl:template>

    <xsl:template match="cd">
        <p>
            <xsl:apply-templates select="title"/>
            <xsl:apply-templates select="artist"/>
        </p>
    </xsl:template>

    <xsl:template match="title">
        Title: <span style="color:#ff0000"><xsl:value-of select="."/></span>
        <br />
    </xsl:template>
    <xsl:template match="artist">
        Artist: <span style="color:#00ff00"> <xsl:value-of select="."/></span>   
        <br />
    </xsl:template> 

That's all for this post, in the next post (Learning Umbraco in a week - Day IV) we will have a look at the XSLT Macros in Umbraco.

Learning Umbraco in a week - Day IV

 

This is my fourth post of the "Learning Umbraco in a week" series. The main agenda of this post is listed below.

• What are Umbraco Macros?
• How to use Macros as building blocks in Umbraco?
• How Umbraco uses XSLT?
• Creating XSLT Macro
• Understanding the "currentPage" parameter
• Understanding the XML Document Schema (v4.7)
• XPATH Axes in Umbraco
• A look at XSLT Macro Snippets

What are Umbraco Macros?

Macros are used to get and display data from Umbraco. For example, site maps, navigation, and news lists. This can be done using XSLT. Umbraco includes several pre-built XSLT Macros, and you can also create your own.

Umbraco Macros can also be used to wrap .NET user controls or custom controls, to include those in your Web Page. 

How to use Macros as building blocks in Umbraco?

In Umbraco, Macros are small building blocks of functionality that can be dropped into an editor. Each Macro encompasses a piece of functionality, and provides a simple interface to be able to modify the macro to you requirements. Importantly, Macros can be placed in transforms, templates, and rich-text, and the Umbraco GUI provides a button for this in the relevant section.

How Umbraco uses XSLT?
Umbraco utilizes XSLT to dynamically render content such as navigational structures, lists, and nearly anything you can dream of. This is accomplished through the use of Macros.

Creating XSLT Macro
Creating a Macro in Umbraco is very easy.

For creating an XSLT Macro in Umbraco, follow the steps below.

1. Go to Umbraco Default Page (Admin Page) > Sections > Developer > XSLT Files.
2. Right click on the XSLT Files node, and select create.
3. You will receive a dialog where you can specify the name, select an XSLT template, and specify if you want to automatically create the Macro for this template.
4. Specify the name of the new XSLT file, check Create Macro, and select a template if you desire. Click Create.
5. You have now created the XSLT file and the Macro for rendering the Content.

Understanding the "currentPage" parameter

The currentPage parameter is the complete XML document of the published site, and is how we reference the data stored in each document.

It is important to note that, by default, the context of the XML document is set to the requested Web Page. The XML document, as mentioned before, contains all the content of the published documents. This data is stored in the XML document structured in the same manner as your tree is laid out in Umbraco. So, documents are nested to create the hierarchy that we can easily use. 

An Umbraco Node (The "currentPage" parameter) consists of several common pieces of data, and they are listed below.

1. id
2. version
3. parentID
4. level
5. writerID
6. creatorID
7. nodeType
8. template sortOrder
9. createDate
10. updateDate
11. nodeName
12. urlName
13. writerName
14. creatorName
15. nodeTypeAlias path

All these are store as Attributes of the Document (Also called "Node").

Moreover, the Properties that are added to the Document in Umbraco, and what the user edits are referenced as "Data". Data consists of a couple common pieces of data, which are Attributes on the data elements.  These are listed below.

1. alias
2. versionID

Understanding the XML Document Schema (v4.7)

In Umbraco, each Document Type has it's own Node using the Document Type alias - <Home> as opposed to the previous convention <node documentTypeAlias="home">.

Each Property has it's own Node underneath the Document Type node <umbracoNaviHide> as opposed to the previous convention <data alias="umbracoNaviHide">.

It is important to note that, the difference between a Document Type Node and a Property Node is that the Document Type Node has the blank attribute isDoc <home isDoc"">

XPATH Axes in Umbraco
XPATH works on the premise of Axes, which is how the data relates to the Current Node in Umbraco as well.

• Self Axis - While it is rarely used, the self axis actually returns the node in reference.

                             $currentPage/self::node

• Child Axis - The child axis select the nodes immediately below the node in reference. While the verbose method is rarely used, it is here for reference.

                             $currentPage/child::node
                             $currentPage/node

• Parent Axis - The parent axis allows us to see the node immediately above the node in reference.

                             $currentPage/parent::node 
                             $currentPage/../

• Descendant Axis - The descendant axis retrieves all nodes below the node in reference no matter the depth.

                             $currentPage/descendant::node 
                             $currentPage//node

• Descendant-or-Self Axis - The descendant-or-self axis returns all nodes below the current node, but also returns the node in reference to the command..

                             $currentPage/ descendant-or- self::node

• Ancestor Axis - The ancestor axis selects all nodes that are ancestors, or the parent, and the parent's parent, and so on, to the node in reference..

                             $currentPage/ancestor::node

• Ancestor-or-Self Axis - The ancestor-or-self axis selects all nodes that are ancestors, or the parent, and the parent's parent, and so on, including the node in reference.

                             $currentPage/ancestor-or-self::node

• Preceding Axis - The preceding axis selects all nodes no matter the depth, that are located on parent-level and who are also located before (preceding) its parent of the node in reference.

                             $currentPage/preceding::node

• Preceding-Sibling Axis - The preceding-sibling axis selects all nodes that are located on the same level who are also located before (preceding) the node in reference..

                             $currentPage/ preceding-sibling ::node

• Following Axis - The following axis selects all nodes no matter the depth, that are located on parent-level and who are also located after (following) its parent of the node in reference.

                             $currentPage/following::node

• Following-Sibling Axis - The following-sibling axis selects all nodes that are located on the same level who are also located before (following) the node in reference.

                             $currentPage/following-sibling::node


A look at XSLT Macro Snippets
For a practical understanding of XSLT Macros, a list of XSLT Macro snippets is provided below.

1. For each child Node of a specific Document Type Alias 

<xsl:for-each select="$currentPage/NewsItem"> </xsl:for-each>

However for whatever reason if you want to have a document type alias and a document type property with the same alias it would select both.

<xsl:for-each select="$currentPage/NewsItem [@isDoc]"> </xsl:for-each>

2. For each child Node excluding a specific Document Type Alias 
<xsl:for-each select = "$currentPage/*[not(self::NewsItem)]" > </xsl:for-each>

3. For each child Node 

<xsl:for-each select="$currentPage/* [@isDoc]"> </xsl:for-each>

This example selects all xml nodes underneath the currentPage item using the * selector.

However without the [@isDoc] section it would select all nodes including those which are just document type properties.

4. For each child Node via a selectable source 

This example shows you how to list childnodes from the nodeID of the contentpicker.

<xsl:param name="Source" select = "$currentPage/mySource" />
<xsl:for-each select = "umbraco.library:GetXmlNodeById($Source)/DocType">
</xsl:for-each>

5. For Each node of a specific Document Type Alias 

<xsl:for-each select="$currentPage/ancestor-or-self::Home//MyDocumentType [@isDoc]">
</xsl:for-each>

This example walks upto the top level node/dcoument type with the alias of Home. So this is a fairly expensive XPath call.

Then it looks through all the child nodes no matter how deep to find the node (document type) with the alias of MyDocumentType.

6. Using a Macro parameter to get a Document Type Property 

<xsl:value-of select="$currentPage/* [name() = $myMacroParameter and not(@isDoc)]" />

This example selects the child node where it's name matches the value in myMacroParameter and checks to see if that it does not have the isDoc attribute.

7. Using GetMedia Umbraco Method to load Images 

This code loops through the images in a media folder as specified by a media picker.

<xsl:for-each select="umbraco.library:GetMedia($images, true())/Image">
    <xsl:variable name="picFile" select="umbracoFile"/>
    <xsl:variable name="picW" select="umbracoWidth"/>
    <xsl:variable name="picH" select="umbracoHeight"/>
    <img >
        <xsl:attribute name="src">
            <xsl:value-of select = "$picFile"/>
        </xsl:attribute>
    </img>
</xsl:for-each> 

That's all for this post, in the next post (Learning Umbraco in a week - Day V) we will have a look at .Net Macros in Umbraco.