Themes: Frequently Asked Questions

Version 12

    Answers about themes, the Jive SBS way to make user interface changes.

    Where can I find documentation on themes?

    There are a few different ways to make themes. Here's the documentation on each:

    You'll also find an overview in Themes Overview.

    Any gotchas with theming a template include?

    A FreeMarker include is a template that's being included in another template. For example, if you're using a sidebar.ftl in your document.ftl, like so:

    <!-- document.ftl-->
    . . .
    <#include "/template/global/include/sidebar.ftl" />
    . . .
    

     

    • Prior to 2.5, you would have had to theme both document.ftl and sidebar.ftl

    • As of version 2.5, you only need to theme the sidebar.ftl
    •  

    What is the difference between global themes, community themes and URL themes?

    Global themes exist for any request to the system, URL themes are applied to specific URLs (which themselves can be regular expressions) and community themes only apply to requests that are associated with a specific community (other than the root community).  See Mapping Themes to the UI.

     

    What is the order in which theme mappings are applied?

    URL mapping, then community, then global. In other words, first the URL is checked to see if a theme mapping exists. Then the action is checked to see if it's associated with a community. Finally, if there is a global mapping, that mapping is used.  One big difference between version 2.5 and previous versions: the template loader checks each template (including includes) to see if a mapping exists. So if you map a theme that has a single template associated with it to a community and then create a global theme, the  community theme will get picked up for that single template and then the global theme will take over for all other templates associated with that request.

     

    Are there any things that you shouldn't theme or can't theme?

    Yes, the only thing that you can't theme is the file /template/global/include/jive-macros.ftl.

     

    How do I use the new designer toolkit?

    Jive SBS includes a theme resource kit you can use to make changes to global aspects of the UI. For more information, see Customizing UI with the Theme Resource Kit.

     

    How do I reference a resource (JavaScript, CSS, images) that exists in a theme?

    Assuming you had a theme called 'rick' in your themes directory and a directory called 'images' inside the 'rick' theme, you could reference an image in that directory in Freemarker syntax using code like this:

    <img src="<@s.url value="/themes/rick/images/test.png" />" border="0" />

     

    If you had a CSS file in a theme called 'rick', you would reference / import the CSS file into your template using Freemarker syntax that looks like this:

    <link rel="stylesheet" href="<@s.url value='/themes/rick/test.css'/>" type="text/css"
    media="screen" />
    

     

    How long are theme resources held in client cache?

    As of version 3.0.1, certain resources from themes and plugins are cached by default for 28 days. This change ordinarily enhances perfomance for users. It also means that client computers -- including yours while you're developing and your users' after the theme or plugin has been deployed -- might continue to use cached resources for longer than you'd like.

     

    If you want to ensure that the browser displays the latest version of the resource, you can:

    • Clear your browser's cache when you display the page (pressing SHIFT+reload works in most cases).
    • Reconfigure cache age on the server.
    • Deploy your resources with different names that those used previously. The resource won't be in the cache under the new name, prompting the browser to download it to the client.

     

    Resources set for the long cache include the following file types: .js, .css, .gif, .jpe, .jpg, and .png.

    Can I specify a themes directory so that it doesn't have to exist in jiveHome?

    Yes, you can use the Java system property 'themes.directory' when starting the application to specify the name of a directory that it should use when loading themes.

     

    When should I use the theme editor available in the admin console?

    Never. Seriously. Why? The theme editor exists in the admin console to give you the ability to quickly make a simple change, but it lacks syntax highlighting, color coding, tab support, versioning and many other things that developers come to expect from an editor. In short, if you have a serious production site, or even if you are merely developing themes, you shouldn't use the editor in the admin console unless it's an emergency.

     

    What's the best way to develop themes?

    If you are a developer, the following steps incorporate the best practices for developing a theme. First you will need a local development instance. The following directions assume that you have a running local instance, and know where to find your JIVE_HOME directory.

     

    1. Create a new theme in the Admin Console
    2. Find the created theme in your JIVE_HOME/themes/<your_theme>
    3. You'll want to add that <your_theme> directory to your company's source control repository, so that you have back up and versions of your files.
    4. Edit the files in the <your_theme> directory through a text or HTML editor, and view the changes live in your browser
    5. When changes are complete, zip up the <your_theme> directory and deploy to your qa or production server.