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 annpm install
command is run from the root of the theme, and can be deleted at anytime and re-generated by runningnpm install
.)- (many directories)
package.json
src/
css/
- (modified CSS files)
images/
- (many directories)
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.