Theme configuration

Themes represent the actual visual presentation of our website. A theme specifies the responsive grid setup, main structural elements and other information that is of a more general nature (content independent). Themes can be made device dependent, for example custom views for desktop and mobile.

A theme always consists of a theme configuration file, called theme.xml, and one or more XSL templates, which are used as a "base" for page templates.

The STK features a lightweight theme, called "theme-sample-site", which may be used as a starting point when creating custom themes.

CSS and JavaScript

In the theme.xml, CSS and JavaScript resources can be specified for each available device class. The resources can be specified with full path or with the shorthand version prefixed with {theme}, which is recommended. In addition, {stk} and {shared} can be used as a shorthand version for the "stk" and "shared" folders.


<style>
    <path>{theme}/main.css</path>
</style>
<!--Equivalent to "/_public/name-of-theme/css/main.css"-->
 
<script>
    <path>{theme}/all.js</path>
</script>
<!--Equivalent to "/_public/name-of-theme/js/all.js"-->

Media specific CSS

<theme>
    <device-classes>
        <device-class name="desktop,unknown">
            <styles>
                <style>
                    <path>{theme}/main.css</path>
                </style>
                <style>
                    <path>{theme}/print.css</path>
                    <media>print</media>
                </style>
            </styles>
        </device-class>
    </device-classes>
</theme>

Conditional CSS and JavaScript

The STK supports conditional CSS and JavaScript (often used for Internet Explorer workarounds), by specifying a condition element on the style or script element.

<theme>
    <device-classes>
        <device-class name="desktop,unknown">
            <styles>
                <style>
                    <path>{theme}/main.css</path>
                </style>
                <style>
                    <path>{theme}/ie6.css</path>
                    <condition>IE6</condition>
                </style>
                <style>
                    <path>{theme}/ltie9.css</path>
                    <condition>lt IE 9</condition>
                </style>
            </styles>
        </device-class>
    </device-classes>
</theme>

Include and exclude filters

In case some CSS or JS resources are to be loaded only on specific pages (or not loaded on specific pages), a include and exclude filter can be specified for the resource in the theme.xml.

<!-- will result in video.js only being loaded on the http://domain/video page -->
<script>
    <path>{theme}/video.js</path>
    <includes>
        <include>/video</include>
    </includes>
</script>

<!-- will result in video.js only being loaded on the http://domain/video page, and all subpages of /video -->
<script>
    <path>{theme}/video.js</path>
    <includes>
        <include recursive="true">/video</include>
    </includes>
</script>

<!-- will result in video.js being loaded on all pages but http://domain/video page -->
<script>
    <path>{theme}/video.js</path>
    <excludes>
        <exclude>/video</exclude>
    </excludes>
</script>

<!-- will result in video.js being loaded on all pages but http://domain/video page and subpages -->
<script>
    <path>{theme}/video.js</path>
    <excludes>
        <exclude recursive="true">/video</exclude>
    </excludes>
</script>

JavaScript placement

The STK uses Head JS for loading JavaScript resources. The main benefit of this is that all JavaScript files can be loaded in parallel without blocking the page load, resulting in faster page rendering. By default (in the sample site), all JavaScript resources are placed in the very bottom of the body element. There are, however, some JavaScripts that require head placement. To accomplish this, you should do two calls to stk:head.create-js , one in head and one in body, specifying the "placement" parameter.

<script>
    <path>//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.6.2/html5shiv.js</path>                    
    <condition>lt IE 9</condition>
    <placement>head</placement>
</script>

Images

The image handling in the STK uses a set of predefined sizes from which the most appropriate size for the current use is selected. These predefined sizes are set by the STK because they match the prescaled versions created by the CMS when an image is uploaded. If for some reason other sizes are required, these can be defined in the theme.xml as shown below:


<device-classes>
    <device-class name="all">
        <image>
            <prescaled>
                <size>64</size>
                <size>128</size>
                <size>256</size>
                <size>512</size>
                <size>1024</size>
            </prescaled>
        </image>
    </device-class>
</device-classes>

Theme configuration example

<theme>
    <region-prefix/>
    <device-classes>
        <device-class name="all">
            <image>
                <format>jpeg</format>
                <quality>80</quality>
                <filters>
                    <filter>rounded(4)</filter>
                </filters>
                <sizes>
                    <size name="full">
                        <filter>scalewidth</filter>
                        <width>1</width>
                    </size>
                    <size name="wide">
                        <filter>scalewide</filter>
                        <width>1</width>
                        <height>0.4</height>
                    </size>
                    <size name="regular">
                        <filter>scalewidth</filter>
                        <width>0.4</width>
                    </size>
                    <size name="list">
                        <filter>scalewidth</filter>
                        <width>0.3</width>
                    </size>
                    <size name="square">
                        <filter>scalesquare</filter>
                        <size>0.4</size>
                    </size>
                    <size name="thumbnail">
                        <filter>scalesquare</filter>
                        <size>0.1</size>
                    </size>
                </sizes>
            </image>
            <scripts>   
                <script>
                    <path>{theme}/less-min.js</path>
                </script>
                <script>
                    <path>//code.jquery.com/jquery-latest.min.js</path>
                </script>
                <script>
                    <path>{stk}/stk.js</path>
                </script>
                <script>
                    <path>{stk}/stk-aria.js</path>
                </script>
                <script>
                    <path>{theme}/all.js</path>
                </script>
                <script>
                    <path>{stk}/filter-check.js</path>
                    <includes>
                        <include recursive="true">/videos</include>
                    </includes>
                    <excludes>
                        <exclude>/videos/test3</exclude>       
                    </excludes>
                </script>
                <script>
                    <path>//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.6.2/html5shiv.js</path>                    
                    <condition>lt IE 9</condition>
                    <placement>head</placement>
                </script>
                <script>
                    <path>{stk}/selectivizr-min.js</path>
                    <condition>lt IE 9</condition>
                </script>
            </scripts>
        </device-class>
        <device-class name="desktop,unknown">
            <layout name="default">
                <row cols="12">
                    <region name="r1-c1">
                        <cols>12</cols>
                    </region>
                </row>
            </layout>
            <styles>
                <style>
                    <path>{theme}/main.less</path>
                </style>
            </styles>
        </device-class>
    </device-classes>
</theme>