XSLTsearch 2.8.1 is now available for download at
http://our.umbraco.org/projects/xsltsearch

Please continue to use XSLTsearch 2.8 for Umbraco 3.x, 4.0, and 4.1 sites with the legacy xml schema enabled.

cheers,
doug.

With a quick bit of inline XSLT in your umbraco template you need never worry about it again!

Here's how to do it:

<div id="footer">
    COPYRIGHT &copy; 2009 - 
    <umbraco:Item field="pageName" runat="server" xslt="Exslt.ExsltDatesAndTimes:year()" />, 
    PERCIPIENT STUDIOS. ALL RIGHTS RESERVED.
</div>

There are three points you'll want to keep in mind:

• You must not omit the field="" parameter.
• You must select a field="" that actually exists.
  This is why I used the "pageName" field.
• You can select any field="" you want.
  Remember that the xslt="" command will process the field="" parameter passed in before displaying the output; and in our example the xslt ignores the field being passed in.

Alternatives

Or, if you have some objection to the Exslt extension and want to use only the umbraco library, you can achieve the same result with:

    <umbraco:Item field="pageName" runat="server" xslt="umbraco.library:FormatDateTime(umbraco.library:CurrentDate(), 'yyyy')" />,

Or, if you really want to use a full macro, it would look like this:

<xsl:template match="/">
    <xsl:value-of select="Exslt.ExsltDatesAndTimes:year()" />
</xsl:template>

[EDIT] Or, as Casey points out in the comments... if you have a deep love for all things .NET (or aren't a fan of XSLT) you could put this in your template instead of the umbraco:Item:

    <%= DateTime.Now.Year %>

Conclusion

You can now sleep through New Year's day comfortably, thanks to umbraco and XSLT.

Happy New Year!
doug.

Until recently I have created .net macros for even simple functionality that I would have preferred to put in an easily-maintained XSLT macro. Why? Because I couldn't access a needed namespace from within XSLT.

An example: file level operations

A recent site I worked on needed to display the size of a file. If the file were in umbraco's Media section this would be easy with the built-in umbracoBytes property. But in this case, the file was uploaded rather than placed in umbraco's Media section. Thus, the usual umbraco metadata was not available.

Various solutions presented themselves:

• Add an 'umbracoBytes' property (of type label or static text) to my document type. Umbraco will auto-populate this property when a file is uploaded (this is VERY cool and a great tip to remember!). In my case, however, I had four upload fields in the docType and whatever file was uploaded last would have its filesize placed in the 'umbracoBytes' field. I needed a solution that would work for all the files uploaded.
• Create an event handler setting a unique uploadFile1_umbracoBytes, uploadFile2_umbracoBytes, etc. property when uploading the file. This seemed like too much effort and I would be sure to forget to update the event handler should a fifth upload field be added to the docType later on.
• Create a custom XSLT extension to get the filesize information. This is a good solution but a whole extension seemed rather over-kill for a few lines of C# code.

The C# function I wanted to use was very simple, taking the path to a file and returning the filesize in kilobytes. This could certainly be done as an XSLT extension:

public String uploadFileSize(String filePath) {

    if ((filePath != null) && (filePath.Length != 0)) {
        String localFile = HttpContext.Current.Server.MapPath(filePath);
        if (File.Exists(localFile)) {
            FileInfo fileinfo = new FileInfo(localFile);
            return String.Format("{0:#,###,###.##}", (fileinfo.Length / 1024));
        }
    }
    return null;
}

Using .NET namespaces in your XSLT macros

What I really wanted to do was augment my XSLT macro with that bit of C# code to get the file size from within the XSLT file itself, without needing to create a .NET control, some app_code, an event handler, or custom XSLT extension.

Unfortunately, file level access and many other fun capabilities are not allowed in your umbraco XSLT macros. Not by default, that is. But it's really simple to add that ability with in-line C# (a topic we'll cover in another post) in your XSLT macro.

<msxml:script language="CSharp" implements-prefix="ps">
    <msxml:using namespace="System.IO" />
    <msxml:assembly name="System.Web" />
    <msxml:using namespace="System.Web" />

    <![CDATA[
    public String uploadFileSize(String filePath) {

        if ((filePath != null) && (filePath.Length != 0)) {
            String localFile = HttpContext.Current.Server.MapPath(filePath);
            if (File.Exists(localFile)) {
                FileInfo fileinfo = new FileInfo(localFile);
                return String.Format("{0:#,###,###.##}", (fileinfo.Length / 1024));
            }
        }
        return null;
    }
    ]]>
</msxml:script>

The msxml:using and msxml:assembly statements are the important bits. The msxml:assembly loads the assembly like adding a reference in a .NET project. The msxml:using makes using the functions shorter with no prefix required, just as using System.IO; and using System.Web; in your C# code would do.

I found System.IO was already available so I didn't need to add the assembly statement for it. System.Web was not available so I added it with the msxml:assembly statement.

Completed XSLT macro with in-line .NET code

Here is a complete (and very simple, rather hard-coded) XSLT file. Your macros would probably have more logic in the main template, possibly set the uploadedFile variable with a macro parameter (using a propertyPicker data type), and include additional checks for errors. 

<!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:ps="urn:schemas-percipient-studios"
    xmlns:umbraco.library="urn:umbraco.library"
    exclude-result-prefixes="msxml ps umbraco.library" >

    <xsl:output method="xml" omit-xml-declaration="yes" />

    <xsl:param name="currentPage"/>

    <!-- =========================================================== -->

    <xsl:template match="/">
        <xsl:variable name="uploadedFile" select="$currentPage/data[@alias='uploadedFile']" />
        <xsl:if test="string($uploadedFile) != ''">
            <p>
                The size of the uploaded file is:
                <xsl:value-of select="ps:uploadFileSize($uploadedFile)" /> kb
            </p>
        </xsl:if>
    </xsl:template>

    <!-- =========================================================== -->

    <msxml:script language="CSharp" implements-prefix="ps">
        <msxml:using namespace="System.IO" />
        <msxml:assembly name="System.Web" />
        <msxml:using namespace="System.Web" />

        <![CDATA[
        public String uploadFileSize(String filePath) {

            if ((filePath != null) && (filePath.Length != 0)) {
                String localFile = HttpContext.Current.Server.MapPath(filePath);
                if (File.Exists(localFile)) {
                    FileInfo fileinfo = new FileInfo(localFile);
                    return String.Format("{0:#,###,###.##}", (fileinfo.Length / 1024));
                }
            }
            return null;
        }
        ]]>
    </msxml:script>

    <!-- =========================================================== -->
                
</xsl:stylesheet>

Conclusion

As you can see, extending your XSLT macros with a bit of .NET functionality is very simple and will help you make the most of your macros. And because XSLT macros are compiled, performance is not a problem, though I also cached this macro heavily as well just to be on the safe side.

A fast-paced session for beginners who want to learn from (rather than repeat) others’ mistakes, focusing on concepts, best practices, tips, hidden gems, and "rules of thumb"

For this exercise I am using umbraco 4.0.1 with the Runway package installed.

Create an XSLT macro and insert it into a template

Create a HelloWorld XSLT File

1. In the Developer section of umbraco, right-click the XSLT Files item
2. Select the Create menu, as shown below:
   
3. Specify the Filename as HelloWorld, use the Clean template, and leave the Create macro box checked, then click the Create button, as shown below:
   

Add the Hello World macro to the Homepage template

Now that we have an clean XSLT macro we need to insert it into a page to see its output. You can add macros directly in a template or within a Richtext Editor. We'll work with the Runway Homepage template here and discuss macros in the Richtext Editor (RTE) another time.

1. In the Settings section of umbraco, expand the Templates item
2. Select the Runway Homepage template as shown below:
   
3. Add a new line below the "content" div, as shown below:
   

       <div id="content" class="frontPage">
   
           <umbraco:Item runat="server" field="bodyText"/>
       </div>
   

4. Place the cursor on the empty line and click the Insert Macro icon ()
5. Select the Hello World macro and click the OK button, as shown below:
   
6. The Runway Homepage template should now contain the Hello World macro, as shown below:
   

       <div id="content" class="frontPage">
           <umbraco:Macro Alias="HelloWorld" runat="server"></umbraco:Macro>
           <umbraco:Item runat="server" field="bodyText"/>
       </div>
   

7. Save the Runway Homepage template by clicking the Save icon ( )

View the homepage

If you view the homepage in your browser you'll be disappointed because there is no "Hello, world!" displayed.

As you may have noticed, we never actually added anything to the XSLT to display our message. All we've done so far is create a clean XSLT file and added the macro to the homepage template. These are important steps that you'll repeat many, many times. But how do we get some text output to display?

What you type is what you get with XSLT

Greet the world with XSLT

We've already discussed the various parts of an XSLT file so in this article we'll spend our time focusing on one thing: How can I get my XSLT macro to output text so I can see it?

The most important thing to remember about XSLT is that what you type is what you get. (unless you type an xsl: tag, but we'll talk about that in other posts)

1. In the Developer section of umbraco, expand the XSLT Files item
2. Select the HelloWorld.xslt file
3. Edit the template by typing in the Hello, world! text we want to display, as shown below:
   

   <xsl:template match="/">
       Hello, world!
   </xsl:template>
   

Now when you view the homepage in your browser you'll greet the world.

Include HTML codes as well as text

Remember, what you type is what you get with XSLT. And that includes HTML tags as well. Here are some examples:

Paragraph text

<xsl:template match="/">
    <p>Hello, world!</p>
</xsl:template>

Heading

<xsl:template match="/">
    <h2>Hello, world!<h2>
</xsl:template>

Bold and italic

<xsl:template match="/">
    <em>Hello,</em> <strong>world!</strong>
</xsl:template>

List with a custom class

<xsl:template match="/">
    <ul class="stylish">
        <li>Hello, </li>
        <li>world!</li>
        <li>Hello, </li>
        <li>world!</li>
    </ul>
</xsl:template>

Conclusion

Congratulations, you have successfully created your first XSLT macro in umbraco!

As with all Hello, world! exercises, this one is very basic. In future articles we'll build on these essential steps to perform more interesting activities.

For now, I want you to remember two things from this exercise. First, the steps to create an XSLT macro and then insert that macro into a template. Second, that what you type in XSLT is what you get out of XSLT.

When you create a clean XSLT macro in umbraco 4 you see the following template code (some indenting added for increased clarity):

<?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"/>
    
    <xsl:param name="currentPage"/>
    
    <xsl:template match="/">
        <!-- start writing XSLT -->
    </xsl:template>
    
</xsl:stylesheet>

Before diving in and starting to write an XSLT macro, let's take a moment to understand the anatomy of an umbraco XSLT file. Though you won't often need to change any of the default values, understanding the various parts will be invaluable as we proceed, and we'll refer back to this article often.

Line 1: XML version and encoding

<?xml version="1.0" encoding="UTF-8"?>

Umbraco provides full unicode support for websites, which means you aren't limited to only ASCII or HTML-encoded characters. For instance, the following unicode characters might be used: ä ¿ § ¡ ò مرحبًا καλημέρα müjde. To ensure your XSLT macro honors unicode characters you must always specify the XML encoding.

There is no reason to change this value when using umbraco.

Line 2: !DOCTYPE and !ENTITY

<!DOCTYPE xsl:stylesheet [ <!ENTITY nbsp "&#x00A0;"> ]>

XSLT follows all the formatting rules of XML, such as proper nesting and closing of all tags. Though (x)HTML and XML share many similarities they are not exactly the same. For instance, <br> is valid HTML but <br /> is required in XML/XHTML.

There are five character sequences (or "entities") built-in to the XSL specification. They are: &lt; &gt; &apos; &quot; and &amp; The !DOCTYPE is only required if you wish to specify additional entities.

Besides the five built-in entities, HTML makes use of another character sequence very frequently, the non-breaking space (&nbsp;). Line 2 adds this entity so that you may include non-breaking spaces in your XSLT macros.

If the entity had not been added you would have to use &amp;nbsp; rather than the more traditional &nbsp; in your macros.

TIP: Remember to use &amp; rather than just the & symbol in your XSLT code. Similarly, when comparing values in XSLT you cannot simply use "5 < 10" but must use "5 &lt; 10". This is because the built-in entities resolve the problem of trying to use reserved characters in your XSLT macros. We'll see many examples of this in future articles.

As with line 1, this line rarely needs any modification, though in extreme cases you might wish to add additional entities.

Lines 3 and 18: <xsl:stylesheet> </xsl:stylesheet>

<xsl:stylesheet 
    ...
    ...
</xsl:stylesheet>

These tags enclose the stylesheet instructions themselves. Apart from the header information in the two lines above, all of your XSLT will appear inside these tags.

Lines 4 and 5: XSLT version and namespace

    version="1.0" 
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

Within the opening of the <xsl:stylesheet … > there are a number of elements specifying details about this stylesheet.

Umbraco uses the Microsoft XML Parser (MSXML 6.0), which follows the XSLT 1.0 specification. The XSLT 1.0 specification defines a standard namespace, which is shown on line 5 and needs no modification.

Notice that all XSL functions are pre-pended with the xsl: prefix label to indicate that they are found in the core XSL library built into the MSXML parser.

Note: The XSLT 1.0 specification does not support all the XSLT functions noted at http://www.w3schools.com/Xpath/xpath_functions.asp (a great reference, by the way!), which lists the full set of functions available in the newer XSLT 2.0 specification. I'll discuss which XSLT functions are available in XSLT 1.0 and also explain how you can work around the limitations of XSLT 1.0 to get the same effect as the functions in XSLT 2.0 in another article.

Lines 6 and 7: Additional namespaces

    xmlns:msxml="urn:schemas-microsoft-com:xslt"
    xmlns:umbraco.library="urn:umbraco.library"

You can specify additional namespaces and gain access to functions beyond those built into the core XSL namespace. To access these extra functions you need to add namespaces to the xsl:stylesheet declaration. This is similar to the "include" or "using" feature of other languages.

Umbraco references two additional namespaces by default, as shown in these lines. One for the MSMXL functions (such as node-set()), and the other for the umbraco.library API functions (such as NiceUrl()). We'll discuss the umbraco.library functions in detail in another post.

There is no need to change these lines, though you may wish to include more namespaces to allow you to reference the functions contained in other XSLT extensions, including those you create yourself (a topic we'll talk more about in another article).

Note: Beginning with umbraco 4.0.1, the EXSLT library namespace and functions are also referenced by default, making it easier to use those extended functions within your umbraco macros. The full xsl:stylesheet declaration is shown below (some indenting and line breaks added for clarity):

    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" 
    xmlns:Exslt.ExsltCommon="urn:Exslt.ExsltCommon" 
    xmlns:Exslt.ExsltDatesAndTimes="urn:Exslt.ExsltDatesAndTimes" 
    xmlns:Exslt.ExsltMath="urn:Exslt.ExsltMath" 
    xmlns:Exslt.ExsltRegularExpressions="urn:Exslt.ExsltRegularExpressions" 
    xmlns:Exslt.ExsltStrings="urn:Exslt.ExsltStrings" 
    xmlns:Exslt.ExsltSets="urn:Exslt.ExsltSets"
    exclude-result-prefixes="msxml
        umbraco.library 
        Exslt.ExsltCommon 
        Exslt.ExsltDatesAndTimes 
        Exslt.ExsltMath 
        Exslt.ExsltRegularExpressions 
        Exslt.ExsltStrings 
        Exslt.ExsltSets"
    >

Line 8: Excluding prefixes in the output

    exclude-result-prefixes="msxml umbraco.library">

When you include additional namespaces you should also list them in the exclude-result-prefixes list. Simply list all namespaces you've included (use the prefix after the xslns:) with a space between each prefix.

You only need to modify this line if you include additional namespaces.

Line 10: XSL output method

    <xsl:output method="xml" omit-xml-declaration="yes"/>

This is the line you are most likely to want to change.

By default, umbraco specifies the output method as "xml". This is fine in most cases. But there is one situation that you may encounter in which you might prefer different behavior.

That situation is when you have an empty tag in the output. When the output method is set to "xml" the tag will be simplified or collapsed.

For instance, if your XSLT contained the following:

<div></div>

The output sent to the browser with method="xml" would be:

<div />

Most browsers will not handle this gracefully, your CSS styles will not be applied as expected, and your site may not display correctly.

There are two solutions. One is to include a test in the XSLT to ensure you never output an empty tag that will collapse. The other is to change the XSL output method to "html", which will preserve the expanded tags and not collapse them.

The output sent to the browser with method="html" would be:

<div></div>

Do be aware that the "html" output method relaxes the requirements on the output somewhat and this may introduce issues that could cause your webpages to fail xhtml validation because of un-closed tags, as is appropriate for HTML 4.0 but not XHTML. According to the XSLT specification at http://www.w3.org/TR/xslt#section-HTML-Output-Method, you'll find the following:

The html output method should not output an end-tag for empty elements. For HTML 4.0, the empty elements are: area, base, basefont, br, col, frame, hr, img, input, isindex, link, meta, and param. For example, an element written as <br /> or <br></br> in the stylesheet should be output as <br>

A more interesting situation is that the img tag will not have a closing slash with method="html".

Indeed, you may wish to set all your XSLT macros to use method="html" and reserve method="xml" for special cases,such as when creating RSS feeds that must be in valid XML format with collapsed tags.

Because some tags do not get closed when using method="html" I recommend the use of method="xml" unless you have a specific reason to use method="html". Just be sure to avoid empty tags that would collapse and potentially break your site's css rendering.

Only in very rare and special cases would you want to include the xml declaration (<?xml...?>) in the output, and never for output used in (x)HTML pages no matter what setting you've used for the output method.

Line 12: The currentPage parameter

    <xsl:param name="currentPage"/>

Unlike traditional XSLT in which the entire content of a single file is processed and transformed, a website must include some sense of context.

What page is the website visitor currently viewing? That is what the currentPage parameter is used for. Of all the pages in your site, currentPage will tell you which one is being viewed.

The currentPage parameter is automatically populated by umbraco. It is referenced as $currentPage in your XSLT and you will use it a lot, as we'll see in future articles.

Lines 14 to 16: Template match="/"

    <xsl:template match="/">
        <!-- start writing XSLT -->
    </xsl:template>

Templates are a lot like functions() in other languages. They can be referenced by name (named templates) or they can run automatically when the xml being processed matches a certain condition (match templates).

All xml files will have a root node and will match the root or "/" xpath query. Thus, a match template with match="/" will always be executed, and executed first because the root node in the XML is always the first node.

Or, putting it another way, template match="/" is a lot like the main() or Page_Load() functions in other languages.

We'll discuss xpath as well as match and named templates in detail in other articles. For now, the important thing to understand is that any XSLT code you put in the match="/" template will always be executed when the macro runs.

Conclusion

The pre-defined XSLT templates provided by umbraco can be used "as-is" and few people bother to worry about what all those lines are doing. You, too, might often do that, focusing your efforts on line 15 and writing your own XSLT code.

But understanding each of the lines that make up the structure or "anatomy" of an XSLT file will give you confidence and guidance as you develop your XSLT skills through this series of articles. We will look back to these settings in many of the articles to come.

As an example, suppose you have a blog and want to exclude blog comments from the search results. This is easily done with a one-line addition to the xsltsearch.xslt macro file.

Search for umbracoNaviHide and you'll find the possibleNodes variable in the search template. This is where most of the modifications you might ever want to make would be made.

The search template looks like this (XSLTsearch 2.8):

<xsl:template name="search">
    <!-- Perform the search on the appropriate nodeset and display the output -->
    <xsl:param name="items"/>
    <!-- reduce the number of nodes -->
    <xsl:variable name="possibleNodes" select="$items/descendant-or-self::node[
         string(data [@alias='umbracoNaviHide']) != '1'
         and count(attribute::id)=1 
         and (umbraco.library:IsProtected(@id, @path) = false()
         or umbraco.library:HasAccess(@id, @path) = true())
        ]"/>
    ...

As you can see, the search template that gets all the possible nodes that will be searched. In our example, we want to remove from the search any BlogPostComment nodes. We'll do that by checking the @nodeTypeAlias.

The modified xsltsearch.xslt file that excludes blog post comments would look like:

    <!-- reduce the number of nodes -->
    <xsl:variable name="possibleNodes" select="$items/descendant-or-self::node[
         string(data [@alias='umbracoNaviHide']) != '1'
         and @nodeTypeAlias != 'BlogPostComment'
         and count(attribute::id)=1 
         and (umbraco.library:IsProtected(@id, @path) = false()
         or umbraco.library:HasAccess(@id, @path) = true())
        ]"/>
    ...

This same technique could be used to search within certain document types (rather than to exclude certain document types as we did above). To search only within umbraco content nodes of homepage and webpage document types we would modify the possibleNodes variable like this:

    <!-- reduce the number of nodes -->
    <xsl:variable name="possibleNodes" select="$items/descendant-or-self::node[
         string(data [@alias='umbracoNaviHide']) != '1'
         and (
            @nodeTypeAlias = 'homepage'
            or @nodeTypeAlias = 'webpage'
            )
         and count(attribute::id)=1 
         and (umbraco.library:IsProtected(@id, @path) = false()
         or umbraco.library:HasAccess(@id, @path) = true())
        ]"/>
    ...

Or perhaps you have created your own document type property called  'searchHide' rather than assuming that any page that does not appear in the navigation should not appear in the search results either. If so, you would simply change the umbracoNaviHide alias to that of your property:

    <!-- reduce the number of nodes -->
    <xsl:variable name="possibleNodes" select="$items/descendant-or-self::node[
         string(data [@alias='searchHide']) != '1'
         and count(attribute::id)=1 
         and (umbraco.library:IsProtected(@id, @path) = false()
         or umbraco.library:HasAccess(@id, @path) = true())
        ]"/>
    ...

Though these examples are simple, more advanced modifications can be handled in the same way.

For instance, it would be a small matter to create a custom search form that included checkboxes for the areas or docTypes of your site to search (such as FAQs, News, Support, Products, etc.). You could simply add a macro parameter and pass in the nodeTypeAlias(es) according to the user's selection rather than hard-coding them as we've done here.

Many websites will not need to modify XSLTsearch because of the many built-in options it provides; but it is nice to know that it is so easy to customize XSLTsearch to meet your site's unique needs if you need to.