Sitemason
Build on us
Developers
XSL Template Tutorial
XSL Template Basics
Top & Bottom
Opening HTML
Head
CSS
Body
Introduction to XML
Grabbing Values With <xsl:value-of>
Navigation & XSL Loops
Page Content
Header & Footer Fields
Sidebar Tools
Body Last & Google Analytics
Putting it All Together
XSL Template Basics
XSLT/XHTML basics:
------------------------------------------------
1) always close in-line tags with a forward slash /. <img> and <br> tags are the biggies. Example:
<img src="image.jpg" />
<br />
Other tags such as <form> and <div>, etc. don't close in-line, because they should have a corresponding separate closing tag (i.e. </form> or </div>)
2) You must use hex form for special characters. The biggest culprits are:
->  
© -> ©
If you forget, don't worry, because Sablotron, the XML Parser used by Sitemason, will let you know about it.
3) Look out for curly quotes (usually not a big deal, but they are pesky. You'll usually see them in hard-coded copy, if applicable)
4) For embedded Javascript, again Sablotron is picky. Surround the javascript like this:
<script language="JavaScript" type="text/JavaScript">
<![CDATA[
[ javascript goes here ]
]]>
</script>
------------------------------------------------
1) always close in-line tags with a forward slash /. <img> and <br> tags are the biggies. Example:
<img src="image.jpg" />
<br />
Other tags such as <form> and <div>, etc. don't close in-line, because they should have a corresponding separate closing tag (i.e. </form> or </div>)
2) You must use hex form for special characters. The biggest culprits are:
->  
© -> ©
If you forget, don't worry, because Sablotron, the XML Parser used by Sitemason, will let you know about it.
3) Look out for curly quotes (usually not a big deal, but they are pesky. You'll usually see them in hard-coded copy, if applicable)
4) For embedded Javascript, again Sablotron is picky. Surround the javascript like this:
<script language="JavaScript" type="text/JavaScript">
<![CDATA[
[ javascript goes here ]
]]>
</script>
Top & Bottom
To begin each template, you must open the stylesheet <xsl:stylesheet>, import the shared template <xsl:import />, and state the output method <xsl:output /> as well as open the template <xsl:template>.
Top:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="file://mnt/smapp/custom/templates/lib/shared.xsl" _fcksavedurl="file://mnt/smapp/custom/templates/lib/shared.xsl" />
<xsl:output method="html" encoding="ISO-8859-1" media-type="text/html"/>
<xsl:template match="site">
At the bottom of the document, you must close the stylesheet and template which you opened at the top.
Bottom:
</xsl:template>
</xsl:stylesheet>
Top:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="file://mnt/smapp/custom/templates/lib/shared.xsl" _fcksavedurl="file://mnt/smapp/custom/templates/lib/shared.xsl" />
<xsl:output method="html" encoding="ISO-8859-1" media-type="text/html"/>
<xsl:template match="site">
At the bottom of the document, you must close the stylesheet and template which you opened at the top.
Bottom:
</xsl:template>
</xsl:stylesheet>
Opening HTML
Just like any other HTML document, you must open and close <html>. We use the following line to open <html> before the <head> and after opening the <template>.
<html xmlns="http://www.w3.org/1999/xhtml">
You close <html> the same as any other HTML document, </html>
<html xmlns="http://www.w3.org/1999/xhtml">
You close <html> the same as any other HTML document, </html>
Head
Most of the time, you are going to want to use the standard Sitemason <head> from the shared.xsl template you imported at the top. To do this, simply put:
<xsl:call-template name="head_pre_css" />
And if you intend to use the CSS upload field in Sitemason to manage CSS, include the following in the <head> as well:
<xsl:call-template name="head_post_css" />
If for whatever reason, you do not care for the results of the standard Sitemason <head> included from the shared.xsl template, you can manually change all of those parameters by adjusting the xsl and sticking it in the <head> in place of <xsl:call-template name="head_pre_css" />. Download shared_head_xsl.
<xsl:call-template name="head_pre_css" />
And if you intend to use the CSS upload field in Sitemason to manage CSS, include the following in the <head> as well:
<xsl:call-template name="head_post_css" />
If for whatever reason, you do not care for the results of the standard Sitemason <head> included from the shared.xsl template, you can manually change all of those parameters by adjusting the xsl and sticking it in the <head> in place of <xsl:call-template name="head_pre_css" />. Download shared_head_xsl.
CSS
Using CSS is no different than with any other website. You can either link to your styles, or include them inline:
<link href="http://www.domain.com/screen.css" rel="stylesheet" type="text/css" />
or inline:
<style type="text/css">
.body a:link {
color: #7B68EE;
}
.body a:visited {
color: #7B68EE;
}
.footertext {
font-family: Verdana, Arial, Helvetica, sans-serif;
}
</style>
<link href="http://www.domain.com/screen.css" rel="stylesheet" type="text/css" />
or inline:
<style type="text/css">
.body a:link {
color: #7B68EE;
}
.body a:visited {
color: #7B68EE;
}
.footertext {
font-family: Verdana, Arial, Helvetica, sans-serif;
}
</style>
Body
Just like the <html> & <head>, you will open and close <body> identically to any other HTML page, and closing it with </body> as well.
Introduction to XML
Now we get into the actual content of a website. This is where we introduce XML. Since XSLT just pulls the content out of XML, it's important to be familiar with and be able to read XML. Luckily, there's almost nothing to reading XML. Viewing the XML on all Sitemason web pages is as simple as adding the ?xml query to the end of any URL. For example, to access this page's XML, simply use http://developer.sitemason.com/xsl_templates?xml.
The Firefox browser is the easiest of todays browsers to read XML, since it formats the output really nicely, and color codes and everything. Here's an example of what XML output looks like in Firefox:
The Firefox browser is the easiest of todays browsers to read XML, since it formats the output really nicely, and color codes and everything. Here's an example of what XML output looks like in Firefox:
Grabbing Values With <xsl:value-of />
Any time you want to get the value of an element in XML, you simply have to call it. For example, in the above code snippet, if you wanted to grab the Title of the site which is Sitemason Developer, you'd simply get the value of the Title element, like so:
<xsl:value-of select="title" disable-output-escaping="yes" />
XML is sorted just like a standard file structure for embedded elements, so if you want to grab the title of the current page you are on, you'd use this:
<xsl:value-of select="current_nav/title" disable-output-escaping="yes" />
You will want to set disable-output-escaping to "yes" when you're calling a text field so that if there is HTML in that text field, it doesn't break the templlate.
<xsl:value-of select="title" disable-output-escaping="yes" />
XML is sorted just like a standard file structure for embedded elements, so if you want to grab the title of the current page you are on, you'd use this:
<xsl:value-of select="current_nav/title" disable-output-escaping="yes" />
You will want to set disable-output-escaping to "yes" when you're calling a text field so that if there is HTML in that text field, it doesn't break the templlate.
Navigation & XSL Loops
Just about every website out there uses a structured navigation that lets users easily get around a website. Sitemason does all of the work to keep that navigation organized and even supports multiple levels of navigation, by embedding navigation items within nav elements in the XML. Here's what basic navigation XML looks like:
To get each navigation item into your template, you'll need to loop through the XML and grab each title. To do this you will use an <xsl:for-each> loop.
<div class="navigation_css">
<ul class="parent">
<xsl:for-each select="nav">
<li>
<xsl:if test="currently_displayed">
<xsl:attribute name="class">current</xsl:attribute>
</xsl:if>
<a href="{link}"><xsl:value-of select="title"/></a>
</li>
</xsl:for-each>
</ul>
</div> In general, you're more than likely going to want to style your navigation with CSS, so most often you're going to be putting your loop in a <div>. Additionally, it's becoming more and more standard to always put your navigation items in an unordered list. The above code basically just says, for each time you come across "nav" in the XML, spit out the title within an anchor <a> and put it in an <li>.
Grabbing the URL for the anchor tag introduces another new concept of the curly brackets {}. You can't put a tag inside of a tag, so in XSL if you're already in an anchor tag when you need to grab a URL, you can't use the <xsl:value-of> tag to do so. Instead, XSL uses curly brackets to affectively do the same thing as the <xsl:value-of> tag.
A couple of other quick concepts were introduced in the above example. The <xsl:if> and <xsl:attribute> tags. The <xsl:attribute> tag lets you create id's or classes that are applied to the parent element (in this example the enclosing <li>). The <xsl:if> is a smple IF Statement that says "if a criteria is met, then do something." So in this example, you're assigning the class .current to a navigation item IF it's the page currently being displayed. This affectively lets you give the active nav link an extra style, say bolding that link.
To get each navigation item into your template, you'll need to loop through the XML and grab each title. To do this you will use an <xsl:for-each> loop.
<div class="navigation_css">
<ul class="parent">
<xsl:for-each select="nav">
<li>
<xsl:if test="currently_displayed">
<xsl:attribute name="class">current</xsl:attribute>
</xsl:if>
<a href="{link}"><xsl:value-of select="title"/></a>
</li>
</xsl:for-each>
</ul>
</div> In general, you're more than likely going to want to style your navigation with CSS, so most often you're going to be putting your loop in a <div>. Additionally, it's becoming more and more standard to always put your navigation items in an unordered list. The above code basically just says, for each time you come across "nav" in the XML, spit out the title within an anchor <a> and put it in an <li>.
Grabbing the URL for the anchor tag introduces another new concept of the curly brackets {}. You can't put a tag inside of a tag, so in XSL if you're already in an anchor tag when you need to grab a URL, you can't use the <xsl:value-of> tag to do so. Instead, XSL uses curly brackets to affectively do the same thing as the <xsl:value-of> tag.
A couple of other quick concepts were introduced in the above example. The <xsl:if> and <xsl:attribute> tags. The <xsl:attribute> tag lets you create id's or classes that are applied to the parent element (in this example the enclosing <li>). The <xsl:if> is a smple IF Statement that says "if a criteria is met, then do something." So in this example, you're assigning the class .current to a navigation item IF it's the page currently being displayed. This affectively lets you give the active nav link an extra style, say bolding that link.
Page Content
Since Sitemason handles the templating for individual tools, you don't have to worry about slogging through a bunch of code to deliver content to a page. Add this simple block to pull in all of the code for a page's content from a single Sitemason tool.
<xsl:for-each select="content">
<xsl:apply-templates/>
</xsl:for-each>
<xsl:for-each select="content">
<xsl:apply-templates/>
</xsl:for-each>
Header & Footer Fields
In Sitemason's Site Builder, there is a Header & Footer tab with many fields that give you control over any number of XML elements. You can upload a header image that displays on every page, but is changeable, you can use one field for a slogan, another for a footer or copyright statement. All of these can be pulled out of XML with the <xsl:value-of> tag, or if they're already in a tag (like <meta>), with curly brackets {}. Here are all of those available:
Image Upload Fields: main_image, header_image, bg_image1, bg_image2, image1, image2
<img src="{main_image}" />
<img src="{header_image}" />
<img src="{bg_image1}" />
<img src="{bg_image2}" />
<img src="{image1}" />
<img src="{image2}" />
Image Link Fields: header_image_link, main_image_link, image1_link, image2_link
<a href="{header_image_link}"></a>
<a href="{main_image_link}"></a>
<a href="{image1_link}"></a>
<a href="{image2_link}"></a>
CSS Upload Field: css_link
<xsl:value-of select="css_link" disable-output-escaping="yes"/>
CSS Text Field: css_text
<xsl:value-of select="css_text" disable-output-escaping="yes"/>
Meta: meta_description, meta_keyworkds
<meta name="meta_description" content="{description}" />
<meta name="meta_keywords" content="{keywords}" />
Text Fields: title, slogan, header, footer, copyright, maintainer
<xsl:value-of select="title" disable-output-escaping="yes"/>
<xsl:value-of select="slogan" disable-output-escaping="yes"/>
<xsl:value-of select="header" disable-output-escaping="yes"/>
<xsl:value-of select="footer" disable-output-escaping="yes"/>
<xsl:value-of select="copyright" disable-output-escaping="yes"/>
<xsl:value-of select="maintainer" disable-output-escaping="yes"/>
Text Links: maintainer_url, maintainer_email
<a href="{maintainer_url}"></a>
<a href="mailto:{maintainer_email}"></a>
Image Upload Fields: main_image, header_image, bg_image1, bg_image2, image1, image2
<img src="{main_image}" />
<img src="{header_image}" />
<img src="{bg_image1}" />
<img src="{bg_image2}" />
<img src="{image1}" />
<img src="{image2}" />
Image Link Fields: header_image_link, main_image_link, image1_link, image2_link
<a href="{header_image_link}"></a>
<a href="{main_image_link}"></a>
<a href="{image1_link}"></a>
<a href="{image2_link}"></a>
CSS Upload Field: css_link
<xsl:value-of select="css_link" disable-output-escaping="yes"/>
CSS Text Field: css_text
<xsl:value-of select="css_text" disable-output-escaping="yes"/>
Meta: meta_description, meta_keyworkds
<meta name="meta_description" content="{description}" />
<meta name="meta_keywords" content="{keywords}" />
Text Fields: title, slogan, header, footer, copyright, maintainer
<xsl:value-of select="title" disable-output-escaping="yes"/>
<xsl:value-of select="slogan" disable-output-escaping="yes"/>
<xsl:value-of select="header" disable-output-escaping="yes"/>
<xsl:value-of select="footer" disable-output-escaping="yes"/>
<xsl:value-of select="copyright" disable-output-escaping="yes"/>
<xsl:value-of select="maintainer" disable-output-escaping="yes"/>
Text Links: maintainer_url, maintainer_email
<a href="{maintainer_url}"></a>
<a href="mailto:{maintainer_email}"></a>
Sidebar Tools
Many websites have multiple columns of content. Think of a 3 column website where the left column is devoted to navigation, the center to main content, and the right to a sidebar that has the same content no matter what page you're on, like a calendar or news item list.
Sitemason lets you embed other tool XML into the main XML so you can get the XML for multiple tools in one page. To do this, just assign a tool to one of the placeholders in the "Navigation, Sidebar & Toos" section of the Header & Footer tab. Then, place the below block into your XSL template, replacing the tool # as it pertains to the slot you use:
<xsl:if test="tool1">
<script type="text/javascript" language="JavaScript" src="{tool1}?JS"></script>
</xsl:if>
Sitemason lets you embed other tool XML into the main XML so you can get the XML for multiple tools in one page. To do this, just assign a tool to one of the placeholders in the "Navigation, Sidebar & Toos" section of the Header & Footer tab. Then, place the below block into your XSL template, replacing the tool # as it pertains to the slot you use:
<xsl:if test="tool1">
<script type="text/javascript" language="JavaScript" src="{tool1}?JS"></script>
</xsl:if>
Body Last & Google Analytics
Just like we used <xsl:call-template name="head_pre_css" /> from the shared.xsl template in the head, we also can use another block to simply add often used code blocks to close out a body section of a template. Most notably, to add Google Analytics support, just add this snippet before closing the <body>:
<xsl:call-template name="body_last" />
To actually impliment Google Analytics, you will need to additionally add the analytics User ID into the Sitemason field in the Header & Footer tab, which usually looks like this "UA-333333-1".
<xsl:call-template name="body_last" />
To actually impliment Google Analytics, you will need to additionally add the analytics User ID into the Sitemason field in the Header & Footer tab, which usually looks like this "UA-333333-1".
Putting it All Together
A full functioning Sitemason template can be very small in size. Putting all of the above items into one template yields a paltry 52 line template. Using CSS to position and style all of the <divs> creates an extremely flexible and highly efficient template. Download this basic example template http://developer.sitemason.com/examples/sitemason_template_example_xsl and remember to always save your templates as .xsl files, and upload them to the Uplad Template tab of the Sitemason Site Builder.
110 30th Ave North, Suite 5 | Nashville, TN 37203 | 615-301-2600 | 888-349-5578