Percipient Studios logo

Your first umbraco XSLT macro

05 May 2009
Filed under: xslt - by Douglas Robar

The first program you write when learning a new language is the obligatory "Hello, world!" program. Having already considered the anatomy of an umbraco XSLT file it is time to take make our first umbraco macro following this long-standing and useful tradition.

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:
    HelloWorld-create xslt menu
  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:
    HelloWorld-create macro dialog

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:
    HelloWorld-runway homepage template 01
  3. Add a new line below the "content" div, as shown below:
        <div id="content" class="frontPage">
            <umbraco:Item runat="server" field="bodyText"/>
  4. Place the cursor on the empty line and click the Insert Macro icon (HelloWorld-insert macro icon)
  5. Select the Hello World macro and click the OK button, as shown below:
    HelloWorld-Insert macro dialog
  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"/>
  7. Save the Runway Homepage template by clicking the Save icon ( HelloWorld-save icon)

View the homepage

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

HelloWorld-homepage with no output

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!

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

HelloWorld-homepage with raw output

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 match="/">
    <h2>Hello, world!<h2>

Bold and italic

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

List with a custom class

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



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.

5 comments for “Your first umbraco XSLT macro”

  1. Gravatar of Tarek Faham
    Tarek Faham says:
    This is really very important, especially for beginners.

    Though XSLT are somehow complex to understand and implement (due to lack of smart editor like that of VS), but they are very powerful.

    I wanted to know if it is possible using XSLT Macro to render a given Document using its ID with a given template. How ?

  2. Gravatar of Douglas Robar
    Douglas Robar says:
    @Tarek This is rather off-topic and would be better asked on the umbraco forum.

    But for a quick pointer, check out umbraco.library:RenderTemplate(). Note that this function does not work in umbraco 4.0.0, but does in all other umbraco versions.

  3. Gravatar of Tarek Faham
    Tarek Faham says:
    Thanks doug, that is exactly what I am looking for, a quick pointer...

    I can find my way through for more details.

  4. Gravatar of Jegan
    Jegan says:
    Could you please guide me how to show a common content, which need to be displayed in all pages(including child pages) using macro. How the folder structure need to be and how we need to write the xslt. Thank you
  5. Gravatar of Jegan
    Jegan says:
    Please mail the reply in
powered by <XSLTsearch>


Follow Us

RSS Feed
Follow us on Twitter
Follow us on Flickr