Liferay has made theme development a much more streamlined and enjoyable experience for front-end developers in their DXP release. To start, they allow the use of standard tools in theme development that are well known to modern front-end developers. Node.js, npm, yeoman and gulp are integral pieces of the Liferay DXP theme development process, just as they are in non-Liferay front-end development. Additionally, they use the Bootstrap 3 front-end framework and extend it with Clay – a web implementation of their Lexicon design language. These tools allow for a modern and consistent UI, based on the principles of responsive design.

In this post, I’m going to walk you through the migration of a Liferay 6.2 theme to Liferay DXP.

Theme Migration Steps

To start, the official Liferay site has a nice tutorial for migrating a theme from 6.2 to DXP. This post is going to act as a companion to that article, as I’ve gone through the theme migration not only with the tutorial Liferay Lunar Resort 6.2 theme but also on a real-world theme that I upgraded for one of our clients.

One thing to note is that Liferay provides several different tools for the purpose of creating themes. These include a Gradle theme builder plugin, the Blade CLI theme template, the Liferay IDE which uses the theme template under the hood, and finally the Liferay Theme Generator, which runs on the Node.js platform. Since I’m a front-end developer, I’m going to focus on the Liferay Theme Generator, as it uses modern front-end tools that will be familiar to all front-end developers that are starting theme development for Liferay DXP for the first time.

NOTE: Before starting this tutorial, please follow the instructions for installing The Liferay Theme Generator located here.

The theme migration flow is as follows:

  1. Migrate the theme to the Liferay Theme Generator
  2. Run the gulp upgrade task on the migrated theme
  3. Update CSS
  4. Update theme templates
  5. Final steps

Step 1: Migrate the theme to the Liferay Theme Generator

It goes without saying that the first thing you should do with your old theme is to make sure it’s backed up so that you can go back to it in case something goes wrong. Once that’s done, browse to the folder where you want your new theme to live and type:

yo liferay-theme:import

This will run a generator for the npm module called yeoman with the task of importing your original theme. First, you will need to enter the absolute path to the directory that contains your Liferay 6.2 theme and then the import process will begin (the correct path will have a /docroot folder in it). During the import process, you will be prompted for the path to your app server and its development URL (the app server path is the tomcat directory inside the Liferay installation folder and the default URL is These will be added to a liferay-theme.json file which will allow you to deploy your theme easily. When the import is finished you should see a message along the lines of the following:

[00:08:01] Finished 'init' after 19 μs

You’ll need to use the CTRL-C key combination to return to your command prompt.

Step 2: Run the gulp upgrade task on the migrated theme

Now that the theme import is finished, browse into the newly created directory (it will have the same name as your original theme directory) and type:

gulp upgrade

This task will make another backup of your original theme in a folder called backup and it will also generate the core files for the theme, including the .scss, or Sass files. If you are unfamiliar with the Sass CSS preprocessor, it is an extension language that allows you to organize, maintain, and write reusable, clean CSS code. I highly recommended learning it as you will be using it extensively to build your themes in Liferay DXP.

During the upgrade task, you will be prompted to rename some of the scss partial files (prefixing them with an “_” character). You should answer “yes” to these prompts. When the task finishes you’ll see a message like the following:

[00:27:14] Finished 'upgrade' after 1.98 min

Again, you may need to use the CTRL-C key combination to continue. Before you clear your terminal though, you should scroll up and copy the log text starting with:

Bootstrap Upgrade (2 to 3)

And ending with:

Warning: ${theme} variable is no longer available in Freemarker templates, see for more information.

Paste this into a text file as you’ll need to reference it while updating the CSS and your templates in the next steps. Here is the output from my console (using the Liferay 6.2 Lunar Resort Theme):

Bootstrap Upgrade (2 to 3)

File: src/css/_aui_variables.scss
    Line 5: "$white" has been removed
    Line 11: "$baseBorderRadius" has changed to "$border-radius-base"
    Line 15: "$btnBackground" has changed to "$btn-default-bg"
    Line 16: "$btnBackgroundHighlight" has been removed
    Line 17: "$btnBorder" has changed to "$btn-default-border"
    Line 18: "$btnDangerBackground" has changed to "$btn-danger-bg"
    Line 19: "$btnDangerBackgroundHighlight" has been removed
    Line 21: "$btnInfoBackgroundHighlight" has been removed
    Line 21: "$btnInfoBackground" has changed to "$btn-info-bg"
    Line 22: "$btnPrimaryBackground" has changed to "$btn-primary-bg"
    Line 23: "$btnPrimaryBackgroundHighlight" has been removed
    Line 24: "$btnSuccessBackground" has changed to "$btn-success-bg"
    Line 25: "$btnSuccessBackgroundHighlight" has been removed
    Line 26: "$btnWarningBackground" has changed to "$btn-warning-bg"
    Line 27: "$btnWarningBackgroundHighlight" has been removed
    Line 29: "$dropdownLinkBackgroundActive" has changed to "$dropdown-link-active-bg"
    Line 30: "$dropdownLinkBackgroundHover" has changed to "$dropdown-link-hover-bg"
    Line 31: "$dropdownLinkColorActive" has changed to "$dropdown-link-active-color"
    Line 31: "$white" has been removed
    Line 34: "$navbarBackgroundHighlight" has been removed
    Line 35: "$navbarBorder" has changed to "$navbar-default-border"
    Line 36: "$navbarBackground" has changed to "$navbar-default-bg"
    Line 36: "$navbarLinkBackgroundActive" has changed to "$navbar-default-link-active-bg"
    Line 38: "$linkColorHover" has changed to "$link-hover-color"
    Line 38: "$navbarLinkColorHover" has changed to "$navbar-default-link-hover-color"
    Line 39: "$navbarLinkColor" has changed to "$navbar-default-link-color"
    Line 39: "$navbarText" has changed to "$navbar-default-color"
    Line 41: "$errorBackground" has changed to "$error-bg"
    Line 45: "$infoBackground" has changed to "$info-bg"
    Line 47: "$successBackground" has changed to "$success-bg"
    Line 50: "$warningBackground" has changed to "$warning-bg"
File: src/css/custom.css
    Line 201: Padding no longer affects width or height, you may need to change your rule (lines 201-227)
    Line 207: Padding no longer affects width or height, you may need to change your rule (lines 207-226)
    Line 212: You would change height from "62px" to "82px"
    Line 305: Padding no longer affects width or height, you may need to change your rule (lines 305-314)
    Line 308: You would change height from "39px" to "46px"
    Line 403: "nav-collapse" has changed to "navbar-collapse"
    Line 409: Padding no longer affects width or height, you may need to change your rule (lines 409-418)
    Line 490: "btn-navbar" has changed to "navbar-btn"
    Line 490: "btn" has changed to "btn btn-default"
    Line 586: "nav-collapse" has changed to "navbar-collapse"

 Liferay Upgrade (6.2 to 7)

File: portal_normal.ftl
    Warning: <@liferay.dockbar /> is deprecated, replace with <@liferay.control_menu /> for new admin controls.
    Warning: not all admin controls will be visible without <@liferay.control_menu />
    Warning: ${theme} variable is no longer available in Freemarker templates, see for more information.

Step 3: Update CSS

The first section of the log file (_aui_variables.scss) contains warning as to what the upgrade task automatically changed based on the upgrade from Bootstrap 2 to 3. If you examine those lines in the actual file you’ll see where the old code was commented out.

The next file that is referenced (custom.css) shows a number of recommended changes based on the fact that Bootstrap 3 uses the value “border-box” for the box-sizing property. What this means is that any padding that’s been applied to containers with bootstrap classes is no longer added to the total width or height. You should therefore follow the recommendations and manually change the padding to the suggested values.

Finally, if the CSS of your 6.2 theme contained any respond-to responsive mixins, you’ll need to switch them out for a new set of responsive media queries that can be found here under the heading “Updating the Responsiveness.”

Step 4: Update the theme templates

For DXP, Liferay decided to use Freemarker templates rather than Velocity templates because the Freemarker project is still being regularly updated. This means that if your 6.2 theme used Velocity templates, you will need to modify the syntax to work with Freemaker.

To begin, look at the last section of the log from the gulp upgrade task. There will be a reference to the main theme template which is called portal_normal.ftl.The “.ftl” file extension is for Freemarker templates, while Velocity templates had the “.vm” extension. The first thing that must be changed is:

Warning: <@liferay.dockbar /> is deprecated, replace with <@liferay.control_menu /> for new admin controls.

Liferay DXP uses a new control menu and if this line is not changed, you won’t have access to all the admin controls.

The other major change that came with the switch to Freemarker was the removal of the ${theme} variable. This variable allowed access to various tags and utility methods, which now should be accessed directly by tags. For example:


Should now be referenced by the following tag:

< />

For the full list of Liferay DXP “breaking changes” and code replacement, please refer to the following document. Additionally, if you have a navigation.ftl template, make sure you look through it and replace any Velocity syntax with the Freemarker alternative.

A critical update that must be made to your markup is the way Bootstrap 3 column classes work versus Bootstrap 2. You must replace all class references like this:




These classes are documented on the official Bootstrap 3 site.

Final steps

There are two additional steps to the theme upgrade process that are covered in depth in the Liferay document I have referenced multiple times and you would be better served reading about them there.

The first of these is “Updating the Resources Importer,” which includes updating your file, your web content, and your sitemap. This covers the importing of any web content that you have on your old Liferay site into the new site, to make sure it will work within your new theme. Liferay DXP web content should be written in XML and use what are known as structures and templates. Check out this link to learn more about this relationship.

The second step is “Applying Lexicon Design Patterns,” which walks you through applying the classes for a Lexicon based form. Again, Lexicon is Liferay’s UI experience language that extends Bootstrap 3, and Clay is their web implementation of that language. I recommend that you check out these sites as they will help you to make consistent UI with more reusable code.

Deploying your theme

When you are ready to test your theme, browse to your theme directory and type:

gulp deploy

Debugging deployment issues

The Sass compiler does a good job looking for malformed scss/css and if it finds any, will stop the deployment process and let you know where it is in your scss files. You should see the errors in your terminal application that give you the file name(s) and line number(s) where they are occurring. Generally, if your css compiles then you should be good to go, at least in terms of having valid css.

With respect to potential errors in Freemarker templates, for example, portal_normal.ftl, those errors will show up in your Liferay/Tomcat logs, and will also display the file name(s) and line number(s) of the errors. Once all the errors have been fixed, the theme should compile and deploy successfully into your Liferay instance.


As a UI/UX developer, making themes for Liferay is obviously the best part of my job here at Xtivia. When first developing themes for Liferay 6.2, it really felt like the tools were a bit behind the times and working with them was a bit clunky, to say the least. Since the introduction of Liferay DXP however, I’m really impressed that they have embraced the modern front-end toolchain. It makes development of themes more streamlined and more fun!

I hope that this guide will be useful in your Liferay DXP theme development endeavors.

If you have questions on how you can best leverage theme development and/or need help with your Liferay DXP implementation, please engage with us via comments on this blog post, or reach out to us at or [email protected].

Additional Reading

You can also continue to explore Liferay DXP by checking out The Top 10 New Features in Liferay DXP 7 from a functional perspective, or Top 5 New Features in Liferay DXP UI Development and Creating JAX-RS REST Services in Liferay DXP from a development perspective, or Top 5 DevOps Features in Liferay DXP from a devops perspective.

Share This