Theme for Liferay 7

Theme in Liferay is very important component for any project you will be working. Liferay 7 is coming with many changes and you will need to know the new ways of development in Liferay. This blog will help you understand how you can build theme in Liferay 7 using theme generator. Please note, using plug-in SDK approach to develop custom theme in Liferay 7 is still valid approach.

While writing this blog I am taking assumption that you already know Liferay and what is theme in Liferay. This blog is divided in three blocks,

1. Prerequisite (i.e. environment) to start theme development
2. Steps to build theme.
3. Deploy theme

Install theme generator:

Theme generator has few inline dependencies. To make theme generator work, you need to follow following steps to resolve its dependencies,

1. Install Node.js for Node Package manager (NPM):
   1. Download node.js from following URL and follow its installation steps,
      https://nodejs.org/en/
   2. Validate node JS installation using following command
      

      node -v

      You should get following as output

      V4.4.5

      Note, to avoid version conflict, it is batter to install Long Term Support (LTS) version of Node.js which is 4.4.5 at the time of writing this blog.

      Now that you have successfully install Node Package manager (NPM) in your machine, you are good to proceed with further steps.

2. Setup environment for NPM
   1. Create file with name ‘.npmrc’ in your user’s home directory. This will help to bypass npm permission related issues.

   Tip: In windows you will not be able to create file with name ‘.npmrc’ from user interface. You can use following way to create file in windows,

   • To create ‘.npmrc’ file open command prompt
   • go to the user’s home directory (ex. If you are logged-in using ‘EnProwess’ user. Your home directory should be ‘C:\Users\EnProwess’
   • type following command to create file,
     

     copy NUL .npmrc

   2. As Next step, Open .npmrc file and add following details
      

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

      [username] should be replace with your user’s home directory name (ex. If you are logged-in using ‘EnProwess’ user. This path should look like c:/Users/EnProwess/.npm-packages).

      You may be thinking why you need to set prefix property under this file then here is the answer, prefix property will inform NPM installer to install all belonging packages under the path you set as value to this property.

   3. Next, you need to set environment variable for Node and NPM as follow,
      

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

      Tip: this should be same as prefix value

      NODE_PATH=${NPM_PACKAGES}/node_modules

      PATH=${NPM_PACKAGES}

      Tip: please check your c:/Users/[username]/.npm-packages folder. If batch files are created under /bin folder then you should set PATH as ${NPM_PACKAGES}/bin otherwise keep as I mentioned above.

3. Now it’s time to install Yeoman and gulp using following command,
   

   npm install -g yo gulp

   Tips: if you are wondering what is Yeoman and gulp then don’t get confuse. Yoeman is scaffolding tool and gulp is streaming build system (assume like ant or mevan).

   Congratulations! You’ve completed installing the Themes Generator’s dependencies. You are good to start with running following command to generate theme

   npm install -g generator-liferay-theme

Installing Sass on Windows:

There is additional step you need to perform before you build theme. Liferay 7 support Sass in theme. Sass is an extension of CSS3 which adds nested rules, variables, mixins, selector inheritance, and more. Sass generates well formatted CSS and makes your stylesheets easier to organize and maintain.

Now that you know you will need Sass, lets understand how you can setup Sass. There are two options either you use node-sass or Ruby based Sass. By default, theme generator creates theme projects to use node-sass but you still have option to reconfigure it to use Ruby based Sass and Compass.

If you are thinking why someone will go with ruby based Sass if default is node-sass. The simple reason could be the dependencies node-sass needs to make it work. You need to install node-gyp to make node-sass work. Node-gyp requires python and Visual studio installed on machine. Sometime people does not want to install so many dependencies.

You need to make a simple decision to go with either node-sass or Ruby based sass.

It you have made your mind to go with node-sass, please install node-gyp by following simple steps given in Install node-gyp.

If you want to use Ruby based sass install ruby by downloading Ruby Installer. Install Ruby using installer you just download and run following simple command,

gem install sass compass

Well, you have reach to final stage now. Follow the following simple steps to use theme generator and build your theme
Run following Yeoman command,

yo liferay-theme

Welcome to the interactive commands to generate theme. You will be asked following questions,

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.

You provided required information to Yoeman. Now it will start the default generator to installing additional required software and creating your theme project.

5. You will get prompt to enter your app server’s path. It will save this tomcat server Path in liferay-theme.json in your theme’s root directory. You can change this path in future based on your server path changes.
6. Finally, enter your Liferay instance’s URL, or press enter to accept the default localhost:8080.

With this you are done with building new theme for Liferay 7. Please note that if you opted to use Ruby based Sass earlier you must follow following steps,

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

With this your theme is set to support compass, now 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 following task to generate the base files for your theme. Open the build directory of your theme to view the base files.
   

   gulp build

Deploy Theme:

If you have followed above steps without any issue, you got theme ready. Now you can deploy theme using following gulp command,

gulp deploy

Additional Detail,

You may notice that the folder structure created using theme generator is different then what you used to see in plugin-sdk approach. Since we are talking about building and deploying theme, lets also understand the approach develop custom theme.

• Instead ‘_diff’ folder you will use ‘src’ folder in theme generator approach
• Default theme related files are available under ‘build’ folder
• In-case you want to override the default file you need to copy it from ‘build’ folder to ‘src’ folder. Please make sure you create exact same folder under ‘src’ folder. Ex. If you want to override ‘portal_normal.ftl’ file, you need to copy it in ‘/src/template/portal_normal.ftl’. please note that you will have to create template folder in ‘/src’

I hope this blog will help you understand new changes in Liferay 7. Thanks for reading through this blog. In my next blog I will share detail around Theme Gulp Task and Themelets

Blog By,
Jayesh Prajapati