Skip to main content

Custom themes: Best practices

Use these best practices for your custom FreeMarker and Soy themes.

Note: These suggestions apply only to the custom theme development, not the out-of-the-box Theming Tool.

warning

We strongly recommend that you use the out-of-the-box Theming Tool whenever possible due to upgrade risks when using Soy or FreeMarker themes. Alternatively, you can engage our professional service team to help you develop a custom theme if you don't want to do it yourself. Ask your Jive Software account representative about this service. For more information about the Theming Tool, see Theming community.

Tips ​

  • Set jive.devMode = true
  • Set jive.pageCache.enabled = false
  • Avoid mapping the same theme file in multiple overlapping mappings
  • Don't set locale in themes

Make your plans ​

Think about your changes in terms of the UI regions they touch, then plan your themes as groups of templates corresponding to those UI regions. Also, make a list of the theme files which you want to customize for each theme. Note that this could be different custom versions of the same file for different themes.

Use the right tools ​

Use browser-based tools, such as the Firefox Web Developer and Firebug plugins for the Firefox web browser. These tools are useful for figuring out which CSS classes you should edit to change a particular part of the UI.

Use the Admin Console to create and save your templates, but edit them with your own editor (preferably one that features syntax coloring). The Admin Console provides a way to edit these files, but it's pretty basic. After you save templates, you can find them at a path like the following:

jive_home/themes/theme_name/template_path

For example, if you create a custom template based on custom-css.ftl and associate it with a my_theme theme, you can find it here:

jive_home/themes/my_theme/template/global/custom-css.ftl

Understanding custom themes ​

A custom theme is a set of user interface files — FreeMarker, Soy, CSS, and images — that substitute as custom versions of the files included with the application. When you create a custom theme, you're collecting all of these custom files into a single place and mapping that collection to a particular part of the user interface.

You can write advanced customized themes that change what's on UI pages. You can even restyle particular parts of the application, such as to give certain kinds of content or certain spaces their own character.

Each template that you modify in your custom theme replaces the original core template. For this reason, when you upgrade the core application, you also need to upgrade your custom theme. If you do not upgrade it, you may encounter incompatibility issues or backported bugs because the theme templates are compatible with an older version of the application. Therefore, to make upgrades easier, we strongly recommend doing as little template modification as possible. Instead, you should rely on CSS and jQuery to make customizations.

Use comments wisely ​

Comments in templates in their native language (FreeMarker or Soy) are not rendered on the client side, but comments in the CSS, HTML, or Javascript are rendered on the client side and can cause loading delays.

  • CSS comments: Should organize custom styles.
  • Template comments: Should explain the customization, so that you may carry it over when it's time to upgrade.

Separate structure from style ​

Whenever possible, keep CSS and jQuery separate from the HTML.

  • Don't apply <style> from within a template in the <body>.
  • Don't apply inline styles to HTML elements.
  • Don't use onclick methods to attach JavaScript directly to an element.

If you are concerned about page load times, link to external JavaScript files or stylesheets using the link element in the header (do not use @import because it is a slower, server-heavy method). Remember that these files need to be versioned to clear a user's browser cache. For example, a version can be specified as follows: ${themePath}/styles/global.css?v=1.0, where "1.0" is the version.

Additional resources ​

  • Differences between out-of-the-box and custom themes You can use the out-of-the-box Theming Tool or create custom themes, but you should understand the differences and upgrade risks between the out-of-the-box and custom themes.

  • Custom theme development process You can use these steps to develop your custom theme on your development instance before deploying it to production. Jive supports FreeMarker and Soy themes.

  • Uploading your custom theme When you're finished developing your theme files, you should zip them up and upload them to your instance via the Admin Console.

  • Custom themes advanced topics Here you can find how to build advanced custom themes that add or change CSS classes, map your themes to specific parts of the UI, and change the structure of UI pages.

  • Using Theme Resource Kit The Theme Resource Kit is a set of sample files that make up a theme, arranged in the hierarchy that the application expects. You do not have to use this kit, but it can be helpful to understand the kinds of things you can modify in the application.

Related

Developing custom themes