Theme Reference Guide

A theme is made up of several files. Although most of the files are named after their matching components, their function may be unclear.

This document explains each file’s usage to make clear which files to modify and which files to leave untouched.

Theme Anatomy

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

Themes developed with the theme generator have the anatomy shown below. Although themes developed with Developer Studio have a slightly different anatomy built with the theme project template, the core theme files are the same. Note that the build folder is shown for reference, and is generated when the theme is compiled.

• theme-name/
  • build/(generated when the theme is compiled)
    • css/
      • _application.scss
      • _aui_custom.scss
      • _aui_variables.scss
      • _base.scss
      • _custom.scss
      • _extras.scss
      • _imports.scss
      • _layout.scss
      • _liferay_custom.scss
      • _liferay_variables_custom.scss
      • _liferay_variables.scss
      • _navigation.scss
      • _portal.scss
      • _portlet.scss
      • _taglib.scss
      • application/
      • aui/
      • aui.scss
      • base/
      • font-awesome.scss
      • layout/
      • main.scss
      • navigation/
      • portal/
      • portlet/
      • taglib/
    • templates/
      • init_custom.ftl
      • init.ftl
      • navigation.ftl
      • portal_normal.ftl
      • portal_pop_up.ftl
      • portlet.ftl
      • (other directories that have been copied from src)
  • dist/ (generated when the theme is compiled. This is where the theme’s war file is placed after a build/deploy.)
  • gulpfile.js
  • liferay-theme.json
  • node_modules/ (generated when an npm install command is run from the root of the theme, and can be deleted at anytime and re-generated by running npm install.)
    • (many directories)
  • package.json
  • src/
    • css/
      • (modified CSS files)
    • images/
      • (many directories)
    • js/
      • main.js
    • templates/
      • (Modified theme templates)
    • WEB-INF/ - lib/
      • liferay-look-and-feel.xml
      • liferay-plugin-package.properties
      • src/
        • resources-importer/
          • (Many directories)

Regarding CSS files, it is recommended that you only modify _custom.scss, _aui_custom.scss, _aui_variables.scss, and _liferay_variables_custom.scss.

You can of course overwrite any CSS file that you wish, but if you modify any other files, you will most likely be removing styling that Liferay DXP 7.0 needs to work properly.

Theme Files

_application.scss

Contains imports for application styles. Generally these files style components that aren’t Liferay specific, i.e. Alloy or Bootstrap components.

_aui_custom.scss

Used for AUI 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 _aui_variables.scss.

_aui_variables.scss

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

_base.scss

Contains imports for the base styles for Liferay.

_custom.scss

Used for custom CSS styles. It is recommended that you place all of your custom CSS modfications in this file.

_extras.scss

Contains styling that is considered non-essential and potentially dated in the near future i.e. box-shadows, rounded corners, etc. This allows for easy maintenance.

_imports.scss

Contains imports for third-party libraries required for the theme e.g. Bourbon, Liferay Mixins, Lexicon Base Variables, and Bootstrap Mixins.

_layout.scss

Contains imports for layout styles and variables.

_liferay_custom.scss

Contains Liferay DXP styles that are compiled in the same scope as Bootstrap/Lexicon.

It’s recommended that you NOT overwrite this file.

_liferay_variables_custom.scss

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

_liferay_variables.scss

Contains variables that are used in _liferay_custom.scss.

It’s recommended that you NOT overwrite this file.

_navigation.scss

Contains imports for navigation styles.

_portal.scss

Contains imports for Portal components.

_portlet.scss

Contains imports for portlet components.

_taglib.scss

Contains imports for taglib styles.

aui.scss

Contains the Lexicon base CSS import. If you want to just use Bootstrap, or use Atlas, you can do so by adding one of the following imports:

@import "aui/lexicon/bootstrap";

or

@import "aui/lexicon/atlas"; 

font-awesome.scss

Contains the Font Awesome icon imports for Liferay.

main.scss

Contains imports for the core CSS files.

init_custom.ftl

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

init.ftl

Contains common FreeMarker variables that are available to use in your theme templates. Useful for reference if you need access to theme objects.

It’s recommended that you NOT overwrite this file.

navigation.ftl

The theme template for the theme’s navigation.

portal_normal.ftl

Similar to the index.html of a website, this file acts as a hub for all of the 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.

gulpfile.js

Defines the required gulp tasks for Node.js tool developed themes.

It’s recommended that you NOT overwrite this file.

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 langauge, version, and base theme, for Node.js tool developed themes. This file can be updated 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]{/docs/7-0/tutorials/-/knowledge_base/t/importing-resources-with-a-theme} configuration settings are also placed in this file. For a full explanation of the properties available for this file please see the 7.0 Propertiesdoc.