Themes: Frequently Asked Questions

Which kind of theme should I use?

We strongly recommended using the out-of-the-box theming tool because it makes upgrades much easier. To learn more about this tool, be sure to read about it here.

Where can I find documentation on theming in the application?

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

• Use the out-of-the-box Theming Tool. We strongly recommend this tool because it makes upgrades much easier.
  
• Customizing UI with the Custom Theme Resource Kit
• Custom Themes Advanced Topics
• Guide to Using Google Soy Templates in Jive 5

You'll also find an overview in Custom 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" />
. . .

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 Custom 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. 

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 custom theme resource kit?

Jive includes a theme resource kit you can use to make changes to global aspects of the UI. For more information, see Using 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 custom theme resources held in client cache?

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 than 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 custom 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 custom 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 on your production instance, 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. In addition, be aware that any changes you make here are immediately deployed on the site.