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 you can do via the Admin Console, not the out-of-the-box Theming Tool.

Do and Don't

Do set jive.devMode = true
Do 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'll touch, then plan your themes as groups of templates corresponding to those UI regions. Also, make a list of the theme files you'll 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. Here's a shot of Firebug displaying HTML markup and CSS style corresponding to a blog post title. 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'll 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'll find it here:

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

(or .soy)

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 will need to be versioned to clear a user's browser cache (example: ${themePath}/styles/global.css?v=1.0 where "1.0" is the version).