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.
CAUTION:
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 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

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.