Rock For Theme Builders

Theming Conventions

One of the design objectives for Rock was the ability to quickly and easily change the theme of an external site without having to change a lot of block settings and HTML. Our goal was for a customer to be able to change the theme setting for an entire site and the whole site design updates. To enable this level of theming a few conventions must be upheld. Each convention is discussed below.

(rough notes to be fleshed out later)

Layout & Zone Names

Layout names must be consistent so that themes all implement the same standard set of layouts. Within each theme the names of the various zones must also be consistent so that the blocks from each page know where to load when the theme is changed.

The standard layouts for external sites are listed below with the names of zones internal to the layout:

Homepage

• Header
• Navigation
• PromotionRotator
• PromotionList
• Footer

XSLT Files

XSLT files are used to define the markup of navigation menus and marketing ad promotion rotators / displays. These files should all be stored in the folder /Assets/Xslt under the theme root. Common naming conventions should be used to allow theme changes without setting changes. The standard XSLT file names are lised below.

• HomepagePromotionRotator.xslt - used on the homepage to provide markup for a promotions rotator.
• HomepagePromotionList.xslt - used for sub-promotions or other lists of promotions.
• PrimaryNavigation.xslt - provides the page's primary navigation on the page.
• SubNavigation.xslt (optional) - provides an optional sub navigation for a page

NOTE: For more tips on using XSLT files see the 'Working With XSLT' section below.

Theme Paths

When designing your themes it is important not to hard-code paths to assets in your block and page settings. For example, if you need to reference an XSLT file in the navigation, it would be unwise to link to ~/Theme/<SpecificThemeName>/Assets/Xslt/PageNavigation.xslt. When the theme is changed you would need to go back and edit all of these settings. Instead, use the theme home notation of ^/Assets/Xslt/PageNavigation.xslt (this is currently a proposal). This matched with standard XSLT names enables fast and painless theme changing.

#Working With XSLT

XSLT (EXtensible Stylesheet Language Transformations) converts a XML file to HTML markup using a set of defined rules. These rules are defined in an XSLT file on the server. While there are several resources to learn XSLT the easiest way is to look at some samples to determine how they work. You can find some good examples in Rock can be found in Assets\Xslt\ and Themes\GrayFrabric\Assets\Xslt.

There are a couple of tricks you should be aware of in working with XSLT in a Rock environment.

General Tips

Below are some general tips to consider when developing XSLT files.

• When working with XSLT it is often helpful to see the XML you are working with. Most blocks that are designed for XSLT transformations should have a 'Debug' setting that will display the contents of the XML file to the webpage.

XSLT Parmameters

There are some standard standard parameters used in Rock's XSLT transformation blocks. Each is listed below:

• application_home - This parameter gives you the application path /, /Rock/, etc. so you can build relative URLS in your XSLT files. To use this parameter be sure you define it after the xsl:output tag.

<xsl:param name="application_path" />

then later in your XSLT you can use it like

<img class="slider-shadow">
   <xsl:attribute name="src">
      <xsl:value-of select="$application_path"/>Themes/GrayFabric/Assets/Images/slider-shadow.png
   </xsl:attribute>
</img>