Liferay Theme Generator

The Liferay Theme Generator is an easy-to-use command-line wizard that streamlines the theme creation process. It is independent of the Liferay Plugins SDK, and generates themes for Liferay Portal 6.2, Liferay DXP 7.0, and up. It is just one of Liferay JS Theme Toolkit. This tutorial focuses on using the Liferay Theme Generator to create themes. In just a few steps, you’ll have a working Liferay theme.

Note: The Liferay Theme Generator is unsupported. The tool is still in development and is not guaranteed to work on all platforms and environments.

This tutorial demonstrates how to:

• Install the Liferay Theme Generator

• Generate a theme

The first step is to install the Liferay Theme Generator.

Installing the Theme Generator

The Liferay Theme Generator has several dependencies. Follow these steps to install them:

1. Install Node.js, if it’s not already installed. We recommend installing v6.6.0, which is the version Liferay Portal 7.0 supports.

   To test your Node.js installation, execute the following command:

   node -v
   

   The resulting output should look similar to this:

   v4.2.2
   

   Note: To avoid any potential compatibility issues, we recommend installing the Long Term Support (LTS) version of Node.js–at the time of this writing, the LTS version is v4.2.2.

   Node Package Manager (npm) is installed along with Node.js.

2. Set up your npm environment.

   First, create an .npmrc file in your user’s home directory. This helps you bypass npm permission-related issues.

   In the .npmrc file, specify a prefix property like this one:

   prefix=/Users/[username]/.npm-packages
   

   Set the prefix value based on your user’s home directory. The location you specify is where global npm packages are to be installed.

   Next, set the NPM_PACKAGES system environment variable to the prefix value you just specified:

   NPM_PACKAGES=/Users/[username]/.npm-packages (same as prefix value)
   

   As a last npm configuration, since npm installs Yeoman and gulp executables to ${NPM_PACKAGES}/bin on UNIX and to %NPM_PACKAGES% on Windows, make sure to add the appropriate directory to your system path. For example, on UNIX you’d set this:

   PATH=${PATH}:${NPM_PACKAGES}/bin
   

3. Install Yeoman and gulp globally by executing the following command:

   npm install -g yo gulp
   

   You’ve completed installing the Liferay Theme Generator’s dependencies.

4. Install the Liferay Theme Generator. 7.x.x versions of the Theme Generator create themes for 6.2 and 7.0. 8.x.x versions create themes for 7.0 and 7.1. 9.x.x versions create themes for 7.2 and up.

   To create themes for 6.2 or 7.0, run the following command:

   npm install -g generator-liferay-theme@7.x.x
   

   To create themes for 7.0 or 7.1 versions of Liferay DXP, run this command:

   npm install -g generator-liferay-theme@8.x.x
   

If you are on Windows, you must do additional setup for generated themes to use Sass.

Installing Sass on Windows

To use Sass on Windows, you must use either Sass from node-sass or Sass from Ruby. By default, the generator creates theme projects to use node-sass; but you can reconfigure them to use Ruby based Sass and Compass. Since node-sass indirectly requires Visual Studio, developers who are not already using Visual Studio may opt to use Ruby based Sass and Compass instead of node-sass.

Note: If your theme was built with an older version of the Liferay Theme Generator and specifies the "liferay-theme-deps-7.0": "1.0.0" dependency in its package.json, npm install may fail in Liferay DXP due to its dependency on node-sass v3.13.1. To fix this issue, change the dev dependency in your package.json to "liferay-theme-deps-7.0": "7.0.0" and rebuild your theme. We recommend that you use the latest 7.x.x version of the Theme Generator and dependencies in your package.json to ensure full compatibility.

This section explains both Sass installations.

Installing Sass from node-sass

By default, the generator uses Sass from node-sass. node-sass requires node-gyp, which in turn requires Python and Visual Studio. The node-gyp installation instructions explain how to set up node-gyp, Python, and Visual Studio. Since Visual Studio is a particularly large dependency, if you aren’t already using Visual Studio you might want to consider using Ruby Sass instead of node-sass.

Installing Ruby Sass and Compass

As an alternative to using Sass from node-sass, you can use Sass from Ruby. Liferay themes require using Compass along with Ruby based Sass. In order to install and use Sass and Compass, you must install Ruby via the Ruby installer.

Note: Sass version 3.5 has compatibility issues with Compass. We recommend that you install Sass version 3.4.0 as shown in the command below.

The following commands install the Sass and Compass gems:

gem install sass -v "=3.4.0"

gem install compass

After creating a theme project in the next section, you’ll learn how to configure a project to use Ruby based Sass and Compass.

Now that you’ve installed the Liferay Theme Generator and theme dependencies, you can generate a theme.

Running the Liferay Theme Generator

When you installed the Liferay Theme Generator, you also installed three sub-generators with it: a layout template creator, a themelet creator, and a theme importer. For the purposes of this tutorial, the focus will be on the default Liferay Theme Generator.

Note: If you run into permissions issues during theme generation, make sure you have read/write access to all folders on your system.

From a directory in which you want to create a theme, run the following command:

yo liferay-theme

Note: Some theme options are deprecated for 7.0 (such as Velocity theme templates). To view the deprecated options, run the generator with the --deprecated flag:

yo liferay-theme --deprecated

The Liferay Theme Generator prompts you for the following things:

1. Enter a name for your theme.

2. Enter a theme ID, or press enter to accept the default.

3. Select the version of your Liferay instance (e.g., 7.0).

4. Choose a template language. Note that Freemarker is used by default; you can only select Velocity if you run the generator with the --deprecated flag.

   Based on the inputs up to this point, the default generator starts installing additional required software and creating your theme project.

5. When prompted, enter your app server’s path. The information you provide is added to the liferay-theme.json in your theme’s root folder. you can change the path in that file if you change app servers.

6. Finally, enter your Liferay instance’s URL, or press enter to accept the default localhost:8080.

The generator creates a new theme project in your current directory. The theme inherits styles from the liferay-theme-styled theme. Note that you can switch to using a different base theme by executing the gulp extend command.

Note: The liferay-theme-styled and liferay-theme-unstyled themes are base themes. They’re analogous to Java APIs. Liferay’s Classic theme and other themes that use liferay-theme-styled or liferay-theme-unstyled as a base theme are analogous to API implementations–they’re not meant to be extended. Extending Liferay’s Classic theme is strongly discouraged.

Important: By default, your theme is based off of the styled theme and uses lib-sass/bourbon, instead of Compass. If, however, you are on Windows and are using the Ruby version of Sass, you must configure the theme to support Compass. To do so, follow these steps:

1. Open the package.json file found in the root folder of your theme, and locate the rubySass property and change it from false to true.

   Now that your theme is set to support Compass, you must install the Ruby Sass middleware and save it as a dependency for your theme.

2. Run the following command to install the Ruby Sass middleware:

   npm i --save gulp-ruby-sass
   

   The --save flag adds Ruby Sass to the list of dependencies in your theme’s package.json file. Your theme is ready to use.

3. Run the gulp build task to generate the base files for your theme. Open the build folder of your theme to view the base files.

There you have it! You now have a working theme. At the moment, the theme is a bit bare bones, but you have everything you need to develop it.

The generated theme’s structure differs slightly from a theme created in the Liferay Plugins SDK. In a theme generated in the Liferay Plugins SDK, you put changes in a _diffs folder. In a theme generated by the Liferay Theme Generator, you put changes in the src folder.

To develop your theme, copy the build files into your src folder. For instance to make a change to the portal_normal.ftl theme template, you would create a templates folder in your src folder, and copy the portal_normal.ftl file from the build/templates folder into the src/templates folder. This gives you the base template to build on. It is important that you mirror the folder structure in order for the changes to be applied.

Another noticeable difference in the generator created theme is that all CSS files have been converted to Sass SCSS files. Sassy CSS (SCSS) is the new main syntax which allows you to use the latest CSS3 styles and leverage Sass syntax advantages, such as nesting and variables.

To deploy your theme to your configured Liferay DXP instance, execute this command:

gulp deploy

You can apply your theme by following the instructions found in the Creating and Managing Pages User Guide.

Note: By default theme images are cached by the browser. If you need to update images in the theme, it is best practice to use versioning in the image URL. For example, background-image:url("../images/image.jpg?v=1") . You can then just update the version each time you update the image, which will remove the potential for any caching issues.

Now that you’ve created a theme and deployed it, you can use the theme project’s gulp tasks to further develop and manage your theme. These offer basic functions, such as build and deploy, as well as more complex interactions, such as auto deploying when a change is made and setting the base theme.

There you have it! You’re ready to design a terrific theme!

Related Topics

Theme Gulp Tasks

Themelets

Importing Resources with a Theme