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 Portal CE 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.

This tutorial demonstrates how to:

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.

    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 let you create themes for 6.2 and 7.0. Versions 8.x.x and up let you create themes for 7.0 and later versions of Liferay Portal.

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

    npm install -g [email protected]^7.x.x
    

    To create themes for 7.0, 7.1, and later versions of Liferay Portal, run this command:

    npm install -g generator-liferay-theme
    

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.

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.

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.

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

yo liferay-theme

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.

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 Portal instance, execute this command:

gulp deploy

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

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

-1 (1 Vote)
Themes Previous