Custom themes: Frequently asked questions

Here you can answers for some question about developing custom themes for Jive.

Which kind of theme should I use?

We strongly recommended using the out-of-the-box Theming Tool because it makes upgrades much easier. For more information, see Theming community.

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:

For an overview, see Developing custom themes.

Any requirements for theming templates?

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 this:

<!-- 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). For more information, see Mapping custom themes to UI.

What is the order in which theme mappings are applied?

URL mapping, then community, then global. The 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 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 or 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+R 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?

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. 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, note that any changes you make here are immediately deployed on the site.