Themes are a new and exciting feature for Jive Forums that will provide a single forums instance the ability to display various UI customizations based on the content being viewed. Whether you want to brand each forum by providing unique themes, or you want one forum in English and another in Chinese, themes can solve these challenging problems gracefully and with ease.
Managing Existing Themes
Once a theme is created and installed, it will show up in the admin console ("User Interface" -> "Custom Themes"). The installed themes can be mapped globally or to specific categories, forums, or URL patterns. Jive Forums ships with two themes, the default theme and a sample "metallic" theme.
The global theme will be used throughout the application as the base theme. In addition to specifying the global theme, other themes can be specifically mapped to the application. Below is a list of the types of mappings that can be created:
URL:
Associate a theme to a URL pattern (using regular expressions). If the requested URL
matches one of these URL mappings, then the specified theme will be displayed.
LOCALE:
Associate a theme to a specific locale (ie, "zh" for Chinese, "fr" for French).
FORUM:
Associate a theme to any page that has a handle on a forum object. Some examples are the
forum, thread, message pages, as well as poll and announcement pages for a specific forum.
CATEGORY:
Associate a theme to any page that has a handle on a category object, as well as any
children of the category. Some examples are category, forum, thread, messages pages, as
well as poll and announcement pages for a specific category.
How do I Create a New Theme?
Note:: Before attempting to create a custom theme, you should read the default skin overview.
The first step is to create a directory with the desired theme name. The files in a theme directory are as follows:
The theme.xml file specifies the main decorator. A sample file might look like the following:
Finally, create the decorator file specified in your theme.xml, in this case, decorator.ftl. All template files, including the decorator, should be created in the templates directory.
There are a few important things to note regarding the example above. First is that the decorator file is a SiteMesh decorator file. The decorator overlays most of the forums application skin to provide a consistent look and feel. The following tags are used to insert the specific page's content:
${page.title} - Inserts the title of the requested page.
${page.head} - Inserts everything between the <head> tag in the requested page.
${page.body} - Inserts everything between the <body> tag in the requested page.
Also, the following utility classes are pre-loaded in the FreeMarker context and available to use as desired:
com.jivesoftware.base.JiveGlobals
com.jivesoftware.base.JiveConstants
com.jivesoftware.util.LocaleUtils
com.jivesoftware.util.StringUtils
com.jivesoftware.base.action.util.DateUtils
com.jivesoftware.base.license.LicenseUtils
Custom images, stylesheets, and other resources can be loaded from the theme directory by referringto them in the following manner: <@ww.url value='/themes/THEMENAME/PATHTOFILE'/>.
The <@ww.url> and <@ww.text> tags in the above example are used to build valid URLs and internationalize text, respectively. In addition to the these tags, there are many other WebWork tags that can be useful in building custom template files.
All templates must be valid Freemarker template files.
How do I Install a New Theme?
Simply copy the folder containing your theme to the jiveHome/themes directory and restart the application server. Navigate to the Custom Themes page ("User Interface" -> "Custom Themes") in the admin console to manage.
NOTE: If the theme does not appear in the admin console after the system restart, check the error log in the jiveHome/logs directory. The application will not load invalid or corrupt themes and will note it in the error log.
What Theme will be Displayed?
By default, themes will be loaded in the following order:
URL
LOCALE
FORUM
CATEGORY
For example, if you have a theme mapped to the URL pattern 'forum.jspa' and you have a different theme mapped to a specific forum, the theme mapped to the URL pattern will be displayed. Of course, the order of these mappings can be modified in the admin console.
NOTE:If the requested URL matches multiple URL mappings, there is no guarantee which theme will be returned. Therefore, it is very important that the URL mappings are distinct URL patterns. Forum and Category mappings will inherit from their parent object's mappings. For example, if you map a theme to the ROOT category, all other categories and forums will inherit the same theme mapping, unless they specify their own.
How do I Override a Specific Page in the Application?
Any view in Jive Forums can be overridden by creating a similarly named template file in the templates directory. For example, the viewforum.jsp page can be overridden by creating a file viewforum.ftl and placing it in the templates directory of a specific theme.