From unroole CMS wiki
Jump to: navigation, search

Unroole Admin Panel - Themes Channel.png

The theme index panel visible at the channel level. These themes are only available for use on this channel.

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. Each theme is composed of four key components:

These components combine with the CSS/JS/HTML generated by a Layout and then augmented by Stylesheets and JavaScripts to provide the final design of a channel. To use a theme on a particular channel see Theme Queue.

There are two types of themes in unroole, basic and public. Basic themes are the most common form of a theme and can be applied to a channel to change its overall style and appearance. Public themes are themes that are visible to all users.


Unroole Admin Panel - Theme Framework.png

The highlighted area displays the JavaScript from the themes framework being loaded before the CMS system JavaScript files.

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.


Unroole Admin Panel - Themes Stylesheets.png

The highlighted panel displays the stylesheet files that will be loaded as part of the theme. In this case the system css files are loaded after the reset.css.

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.


Unroole Admin Panel - Themes Javascripts.png

The highlighted panel displays the stylesheet files that will be loaded as part of the theme. In this case the system css files are loaded after the reset.css.

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

Unroole Admin Panel - Themes Media Assets.png

Highlighted some image media assets that are used as part of a theme.

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

  1. Upload background.jpg to the Asset library.
  2. Reference the background.jpg file in a custom unroole stylesheet
  3. Activate the stylesheet on the channel for the background to take effect.

Example 2: Background via Theme

  1. Include background.jpg in the media assets folder of a theme.
  2. Reference the background.jpg file in a css file as part of the theme ex: "body { background-image: url(../media_assets/background.jpg) }"
  3. 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.


Unlike other resources in the system, themes cannot be updated. Instead themes provide a mechanism for sharing and exporting to overcome the inability to update. The different actions available for theme management are:


Unroole Admin Panel - Themes Upload.png

Theme packages can be uploaded a either the Account or Channel level.

Importing theme archives is a critical part of the design process of unroole. To use a theme it must first be imported into the system via an archive upload or shared.

Unroole Admin Panel - Themes Channel New.png

Each theme that is uploaded can have a name and description which are useful for internal admin categorization of similar themes.

To upload an existing theme from an archive file follow the steps below.

  1. Navigate to the theme section.
  2. From the index panel click the "Upload" button.
  3. Enter a name for the theme
  4. (optional) Enter a description for the theme
  5. Select the theme archive file that will be uploaded.
  6. Click "Submit" to upload the archive.

The system always checks for consistency and format during an archive's import process. Any archives which are not of the correct format will fail to upload correctly. This ensures that only themes which are compatible with unroole will be available for use.


Unroole Admin Panel - Themes Sharing.png

By clicking the share button of a theme, the admin is able to make this theme public or move it to another Account.

Sharing themes is a good way of moving a theme to another account that the user has access to without needing to go through the theme export/import cycle. Sharing a theme between accounts creates a copy of that theme that can be managed independently from the original. To share a theme follow these steps:

  1. Navigate to the Theme section of an Account or Channel.
  2. Select and view the theme to be shared.
  3. Click the "Share" button from the action menu.
  4. Adjust the name/description of the theme after it is shared.
  5. Select the locations to share this theme.
    • Publicly - Makes a copy of the theme for public use.
    • Accounts - Makes a copy of this theme on either the current or another account the user has theme management access to.
  6. Click 'Submit" to share this theme.

Unroole Admin Panel - Themes Sharing Form.png

Themes can be shared not only to other accounts, but also publicly on the system. Themes shared publicly can no longer be managed by the original sharing user but can be used by all accounts.

Although a theme on an Account or Channel can be shared, only an Account can be used as a share destination. To share a theme specifically with another channel, an admin must export/import the theme to the destination channel. To share a theme with a channel follow these steps:

  1. Navigate to the Theme section of an Account or Channel.
  2. Select and view the theme to be shared.
  3. Click the "Export" button from the action menu.
  4. Click "Submit" to export the theme to an archive.
  5. Navigate to the Theme section of the Channel used as the destination.
  6. Click "Upload a Theme"
  7. Select the previously created theme archive to upload.
  8. Click 'Submit" to add this theme to the channel.


Unroole Admin Panel - Themes Queue.png

Themes currently queued on a website channel. The currently en-queued theme has an arrow pointing to it.

The theme queue allows for themes on a channel to be scheduled similarly to Pages. This queue allows for amins to manage not only the current active theme but also the themes that will become active in the future. This feature should be used in tandem with both Page Scheduling and the Channel Layout Queue when managing the overall design of the website. The queue can be used to automate the process of changing a channel's design such as the following examples

  • Holiday/Promotions - To modify the design of a channel during a holiday and set it back afterwards.
  • Upgrades - To schedule the channel's default design to automatically change during off peak hours.
  • Testing - To apply channel wide design changes on a staging channel when testing.

Any theme available on either a Channel or it's corresponding Account can be added as follows:

  1. Navigate to the "Theme Queue" section of a channel.
  2. Click the calendar icon beside a theme shown in the bottom panel of the "Theme Queue" section.
  3. Change the date/time
    • Click the date field and use the quick change menu to schedule the date the theme will go live.
    • Alternatively change date text to reflect the new date/time.
  4. Click "Schedule" to add the theme to the queue.

Theme entries can be removed by using the "x" item beside each theme in the queue. The theme queue allows for the same theme to be queued multiple times however once a theme has been queued it cannot be deleted until all of its queued entries have been removed.

Unlike a basic theme a public theme cannot be directly en-queued in a channel. This prevents any updates to that theme from breaking the visual style of a site. Instead public theme's can be copied into a user's account or channel where an exact copy is made as a basic theme.


Unroole Admin Panel - Themes Export.png

Every theme can be exported into a theme package for use in other accounts or setups.

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:

  1. Navigate to the Theme Section of the CMS (On either an Account or Channel).
  2. Click the 'Export Theme' button on the Theme index page.
  3. Click 'Submit' to download a new empty theme package.

Unroole Admin Panel - Themes Export Channel Layouts.png

When exporting a theme from a channel you can export some Channel Layouts as part of the package to make editing the theme outside of the editor easier.

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:

  1. Navigate to the Theme Section of the CMS (On either an Account or Channel).
  2. Select and show the theme to be exported.
  3. Click the export button in the action area.
  4. Select the Channel Layouts (if any are available) to export along with the package.
  5. 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:

  1. Navigate to the Theme Section of the CMS (On either an Account or Channel).
  2. Click "Export"
  3. You should be prompted to export a new blank theme. From this point follow the steps outlined when exporting a normal theme.


Unroole Admin Panel - Themes Delete.png

Clicking the delete button on a theme removes it from the system. Only theme's that are not currently in use can be deleted.

Deletion of a theme works similar to other resources in the system.

  1. Navigate to the "Theme" Section of an Account or Channel.
  2. Find the theme to be removed.
  3. Click the "delete" button on the theme to be removed. Either use the quick action from the index panel or the delete button from the show view of a theme itself.