Theme Reference Guide

A theme is made up of several files. Although most of the files are named after their matching components, their functions may be unclear. This reference guide explains each file’s usage to make clear which files to modify.

Theme Anatomy

There are two main approaches to theme development for Liferay DXP 7.1: themes built using the Node.js build tools with the theme generator and themes built using Dev Studio DXP.

Themes developed with the theme generator have the anatomy shown below. Although themes developed with Dev Studio DXP have a slightly different anatomy built with the theme project template, the core theme files are the same.

• theme-name/
  • src/
    • css/
      • _clay_custom.scss
      • _clay_variables.scss
      • _custom.scss
      • _liferay_variables_custom.scss
    • images/
      • (custom images)
    • js/
      • main.js
    • templates/
      • init_custom.ftl
      • navigation.ftl
      • portal_normal.ftl
      • portal_pop_up.ftl
      • portlet.ftl
    • WEB-INF/
      • liferay-look-and-feel.xml
      • liferay-plugin-package.properties
      • src/
        • resources-importer/
          • (Many directories)
  • liferay-theme.json
  • package.json

Regarding CSS files, you should only modify _clay_custom.scss, _clay_variables.scss, _custom.scss, and _liferay_variables_custom.scss.

You can of course overwrite any CSS file you want, but if you modify any other files, you’re removing styling that Liferay DXP 7.1 needs to work properly.

Theme Files

_clay_custom.scss

Used for Clay custom styles, i.e. styles for a third party Bootstrap theme. Anything written in this file is compiled in the same scope as Bootstrap/Lexicon, so you can use their variables, mixins, etc. You can also implement any of the variables you define in _clay_variables.scss.

_clay_variables.scss

Used to store custom Sass variables. This file gets injected into the Bootstrap/Lexicon build, so you can overwrite variables and change how those libraries are compiled.

_custom.scss

Used for custom CSS styles. You should place all of your custom CSS modifications in this file.

_liferay_variables_custom.scss

Used for overwriting variables defined in _liferay_variables.scss without wiping out the whole file.

init_custom.ftl

Used for custom FreeMarker variables i.e. theme setting variables.

navigation.ftl

The theme template for the theme’s navigation.

portal_normal.ftl

Similar to a static site’s index.html, this file acts as a hub for all theme templates.

portal_pop_up.ftl

The theme template for pop up dialogs for the theme’s portlets.

portlet.ftl

The theme template for the theme’s portlets. If your theme uses Application Decorators, you can modify this file to create application decorator-specific theme settings. See the Portlet Decorators tutorial for more info.

liferay-theme.json

Contains the configuration settings for your app server, in Node.js tool-based themes. You can change this file manually at any time to update your server settings. The file can also be updated via the gulp init task.

package.json

Contains theme setting information such as the theme template language, version, and base theme, for Node.js tool developed themes. You can update this file manually. The gulp extend task can also be used to change the base theme.

main.js

Used for custom JavaScript.

liferay-look-and-feel.xml

Contains basic information for the theme. If your theme has theme settings, they are defined in this file. For a full explanation of this file, please see the Definitions docs.

liferay-plugin-package.properties

Contains general properties for the theme. Resources Importer configuration settings are also placed in this file. For a full explanation of the properties available for this file please see the 7.1 Properties documentation.