Themes
Typically most Channels only contain a small amount of default css and javascript that is provided by the layout and widgets used on a page. Themes are then used to provide the basic creative design of a channel and can then be augmented by Stylesheets and Javascripts. Each theme is composed of three key components:
Frameworks
The basis of most themes usually includes a framework or multiple frameworks from which a core amount of theme functionality is derived. These frameworks could be javascript or css template frameworks that provided a group of files to be included. The framework folder for each theme allows for a pre-existing framework to be dropped into a theme without the need to conform to a specific structure or separate the files.
In some cases, widgets may require specific frameworks to be present so that advanced functionality or features of the widget can be used. For example, the Gallery widget requires the jquery and the colorbox frameworks be part of a theme to be able to support light-box functionality.
In each theme package, frameworks can be found under the "frameworks" folder. See Theme Structure for more details.
Stylesheets
As a part of each theme package stylesheets can be added which allows a theme builder to included the css files that will be loaded up when this theme is active. Each stylesheet that is added to a theme can be added into the css load system along with the system css files and channel level Stylesheets. The properties.xml file allows theme designers to change the ordering of the css to ensure that files are loaded in the correct order. All stylesheet files add to this list will be added to the header of a page using that theme.
In each theme package stylesheet files can be found under the "stylesheets" folder. Some additional stylesheets may be found in frameworks. See Theme Structure for more details.
JavaScripts
Javascript files in themes function exactly the same way as Theme Stylesheets. The can be added in either the framework or "javascripts" folder and then referenced in the properties.xml file. Loading of javascript files also works the same way allowing a theme designer to change the ordering of the javascript files as they appear on the page. In each theme package javascript files can be found under the "javasciripts" folder as well as the "frameworks" folder. See Theme Stylesheets for more details.
Most themes will contain at least one or two framework javascript files such as jquery and then additional files to augment or change the way existing widget looks or act when the theme is used.
Media Assets
Media assets can be thought of as asset with which the theme would not look or function correctly and is used by the designer to include content that must be loaded up through a theme's javascript or stylesheet files. These assets do not have any relationship to Assets in the asset library and are handled outside of that process. Each media asset relies on the theme and browsers ability to interpret the file to be used. Additionally these media files could also include text documents or csv files used by a javascript library to display some meaningful static content. In the most extreme case the media assets could also store custom flash (swf), java applet (jar) or other web app formats that may not work on all browsers or rely on extended functionality.
The following examples display two ways of achieving the same default background design using normal stylesheets and themes.
Example 1: Background via Asset Library
- Upload background.jpg to the Asset library.
- Reference the background.jpg file in a custom unroole stylesheet
- Activate the stylesheet on the channel for the background to take effect.
Example 2: Background via Theme
- Include background.jpg in the media assets folder of a theme.
- Reference the background.jpg file in a css file as part of the theme ex: "body { background-image: url(../media_assets/background.jpg) }"
- Load the theme into the channel to set the default background.
The benefit of adding the media assets to themes over the asset library is that it makes the theme portable and does not rely on the specific assets available on an account or specific setup. Designers should take care to only include the media assets necessary to the theme and not those that are often to change or should be included to the asset library such as PDF's or documents.
Managment
Each theme, when exported from the system, is compiled into a consistent theme package. This file provides a consistent way of moving all of the CSS, JS and Media assets used with an unroole theme from one system to another. Because of the design of Layouts in unroole, all themes can be developed that target a variety of different channels without necessarily requiring layouts on those channel's to follow a specific design.
Properties
Any settings specific to a particular theme can be found in the properties.xml file that is part of every theme archive. The properties file includes the following information:
- Theme Frameworks - The frameworks available from this theme.
- Theme Stylesheets - The order in which the css from the theme in relation to system css will be loaded to prevent errors.
- Theme JavaScripts - The order in which the js from the theme in relation to system js will be loaded to prevent errors.
- Channel Compatibility - The channel types this theme is compatible with.
- Site Layout Restrictions - No longer used.
Please note that for any files referenced in the properties.xml file a relative path including file extensions must be provided. For any files loaded from the framework folder the term ":framework" should be added to the beginning of the path.
Example
An example of a complete properties.xml file can be seen below.
<?xml version="1.0" encoding="UTF-8"?> <theme_package xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="properties.xsd"> <load_files> <frameworks> <folder>colorbox</folder> </frameworks> <javascripts> <file>unroole_system</file> <file>example</file> <file>:framework/colorbox/colorbox/jquery.colorbox</file> </javascripts> <stylesheets> <file>unroole_system</file> <file>example</file> </stylesheets> </load_files> <system> <compatibility> <channel>mobile_api</channel> <channel>website</channel> </compatibility> <site_layout> </site_layout> </system> </theme_package>
Schema
During import the properties.xml file is compared with the following schema for consistency. Any properties.xml file which does not match this schema will not be uploaded into the system.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:element name="theme_package">
<xs:complexType>
<xs:sequence>
<xs:element name="load_files">
<xs:complexType>
<xs:sequence>
<xs:element name="frameworks">
<xs:complexType>
<xs:sequence>
<xs:element name="folder" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="javascripts">
<xs:complexType>
<xs:sequence>
<xs:element name="file" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="stylesheets">
<xs:complexType>
<xs:sequence>
<xs:element name="file" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="system">
<xs:complexType>
<xs:sequence>
<xs:element name="compatibility">
<xs:complexType>
<xs:sequence>
<xs:element name="channel" minOccurs="0" maxOccurs="unbounded">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="mobile_api"/>
<xs:enumeration value="website"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="site_layout">
<xs:complexType>
<xs:sequence>
<xs:element name="layout" type="xs:nonNegativeInteger" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Archive File
A theme archive file in unroole is simply a zip file that conforms to a specific format and structure. The structure used in the zip file mimics the information stored in the properties.xml file. All files included in the following pre-determined folder will be uploaded from the archive into the system. Certain folders such as javascripts and stylesheets will only accept files ending in the css and js extensions. Below is a description of the theme archive contents.
- frameworks - Entire framework folders can be loaded here.
- javascripts - Any javascript files not part of a framework.
- media_assets - Any media assets such as images or videos to be included in the theme.
- stylesheets - Any stylesheet files not part of a framework.
- site_layout - (Optional) Exported HTML of Channel Layouts generated when exporting. These files will be ignored during import.
- unroole_system - (Optional) Additional system files generated on Channel Layouts export. These files will be ignored during import.
Example
Below is an example of a simple theme's archive.
media_assets/ media_assets/sample.png media_assets/sample.mp4 javascripts/ javascripts/sample.js stylesheets/ stylesheets/sample.css frameworks/ frameworks/colorbox/... frameworks/jquery_ui/... site_layout/ site_layout/generic_layout.html site_layout/site_layout_1.html site_layout/my_other_channel_layout.html unroole_system/ properties.xml
Importing
{{:Theme Importing}
Exporting
Any theme for which a user has edit access can be exported from the system. The export feature creates an archive file which contains all of the information about the theme. This includes:
- JavaScript files
- Stylesheet files
- Media Assets
- CSS/JS loading order
Each time a theme is downloaded, it creates a zip archive which contains all the information about that theme. More information on the contents and structure of the package can be found in Theme Package Structure.
An empty theme package can be downloaded using the following process:
- Navigate to the Theme Section of the CMS (On either an Account or Channel).
- Click the 'Export Theme' button on the Theme index page.
- Click 'Submit' to download a new empty theme package.
To make it easier for designers to make changes to a theme without constantly needing to upload new versions, the system supports the ability to export channel layout HTML code along with the theme. When the theme package is built, this html can be loaded into a browser or editor of choice and includes all theme links re-written to be used offline. This allows for designers to make changes outside of the CMS and then only uploading the theme when its ready for testing.
Existing theme packages can be exported using the following process:
- Navigate to the Theme Section of the CMS (On either an Account or Channel).
- Select and show the theme to be exported.
- Click the export button in the action area.
- Select the Channel Layouts (if any are available) to export along with the package.
- Click 'Submit' to download the package.
In addition to existing theme's a blank theme can be exported to aid in building a correctly formed theme package. To export a blank theme:
