Liferay DXP Theme Generator

Liferay DXP theme generator tutorial guide on  theme generator tools installation and sample theme creation. Liferay DXP has moved theme generation,migration to NodeJS using yomen,gulp and theme generator plugins. There is no drastic changes in the theme structure from Liferay 6.2 to Liferay 7 themes and you can still use create themes using eclipse under Liferay Plugin SDK and Modules.

Liferay theme generator has below tasks:

• Theme creation (Liferay6.2 and & versions)
• Layouts
• Themelets creation
• Migrating old themes Liferay 7 version

What is Theme?

Look and feel of the applications are managed through themes with CSS, JS and Templates.Click here to access the list of theme tutorials that explained for Liferay 6.2. Liferay DXP uses Theme Generator Node plugin to create themes.

What is Themelets?

Themelets are reusable components that can be included in theme which  contains css ,java script and templates code  fragments that can would reusable  across the application

Lets look into  Liferay DXP theme creation and you need to install below software’s::

1. NodeJS –  for yomen,gulp and generator-liferay-theme
2. Ruby Installed – Ruby is to create SaSS and Compass CSS elements
3. Yo – Node JS plugin
4. Gulp – Node JS Plugin

Liferay theme generator installation steps:

Download and Install NodeJS and dependencies:

• Download NodeJS from https://nodejs.org/download/release/v4.4.2/. Install only Version 4.42 because for latest version liferay theme generator is not working. I tried with  latest version(6.9.1), bu faced some couple of issues.
• Install NodesJS and Node Package Manager (NPM) should also be installed along with Node.js
• open command prompt check the  node js and npm versions
  • node -v
  • npm -v.
• Configure the NPM Path and environment
  • When you run NodeJS  plugin manager, plugins will be installed into  USER_HOME\AppData\Roaming\npm. We will create a directory to keep these plugins at one directory. so create .npmrc config file and  set manually npm-packages path.
  • Create .npmrc file at user  Home directory
  • In Windows, create .npmrc file at  C:/User/{user-name} with below parameters:

    • prefix=C:/Users/jay/.npm-packages
      NPM_PACKAGES=C:/Users/jay/.npm-packages
      NODE_PATH=%NODE_PATH%:%NPM_PACKAGES%/lib/node_modules

  • In Linux – create .npmrc file at /users/[username]/.npm-packages

  • prefix= /users/jay/.npm-packages
    NPM_PACKAGES= /users/jay/.npm-packages
    NODE_PATH=${NODE_PATH}:${NPM_PACKAGES}/lib/node_modules

• Install yomen plugin by giving below command  :  npm install -g yo 

  

• Install gulp :  npm install -g gulp

• Install liferay theme generator :   npm install -g generator-liferay-theme

• check the yomen nad gulp commands in the command prompt:
  •  yo -v
  • gulp -v
  •  Ideally they should work. if yo and gulp commands are not working, then add .npm-packages directory  to windows PATH variable for quick fix.
•  yo,gulp  packages are downloaded to /User/{user-home}/.npm-packages and set this .npm-packages path to Windows PATH variable.
• verify yo command in the command prompt and you will get below screen 
  

  Ruby setup and Installation

• Liferay themes generator uses NodeJS SaSS and Compas and again it requires visual studio, so  we will use ruby sass and compass instead NodeJS css components.
• Download and Install Ruby from here http://rubyinstaller.org/downloads/
• add the  ruby bin  path to windows PATH variable, so that you can access gem in command prompt.
•  Execute below commands by opening ruby commander: I faced issues with SSL issue while executing commands, so bypass requests over HTTP instead on HTTPS.

1. gem sources -r https://rubygems.org
   gem sources -a http://rubygems.org 
   gem install sass compass 

Liferay Themes Generator

The below  3 steps involved in theme creation

• Create Theme
• Modify theme to use Ruby CSS
• Create Theme Structure
• Deploy Theme

Step1: Create Theme

• Verify  below commands in command promot, otherwise update windows PATH to NodeJS plugins directory
  • yo (Check here for additional commands: https://www.npmjs.com/package/generator-liferay-theme)
  • gulp
  • gem -v
•  Liferay Work space folder has theme to contain all theme projects. Navigate to  lifearay-workspace\themes in the command prompt and execute below command:
  • yo liferay-theme 

Step2: Update Theme to use Ruby SaSS and Compass

• Node JS uses Node’s Sass by default and need to change this with Ruby
• Edit package.json in javasavvy-theme folder and
  • set rubySass to true
  • templateLanguage  to vm (by default it set to “ftl”)
  •  change <template-extension>vm</template-extension> in liferay-look-and-feel.xml file. otherwise you will get below error: SERVLET_CONTEXT_/templates/portal_normal.ftl does not exist

  • {
     "name": "javasavvy-theme",
     "version": "1.0.0",
     "main": "package.json",
     "keywords": [
     "liferay-theme"
     ],
     "liferayTheme": {
     "baseTheme": "styled",
     "screenshot": "",
     "rubySass": true,
     "templateLanguage": "vm",
     "version": "7.0"
     },
     "devDependencies": {
     "gulp": "^3.8.10",
     "liferay-theme-tasks": "*",
     "liferay-theme-deps-7.0": "*"
     },
     "publishConfig": {
     "tag": "7_0_x"
     }
    }

• Go to  javasavvy-theme directory and run the below command:  npm i –save gulp-ruby-sass

Step3 : Create Theme Structure using gulp build

• Execute the below command to  create theme structure:
  • gulp build
• Now Theme structure is created  like  below and we need to copy the files from build to src directory.
• Plugin SDK theme development uses _diffs folder to modify theme, but  theme generator uses src folder.
• dist folder contains generated theme war files

Step4: Deploy the theme

Run command : gulp deploy to deploy the theme. It will copy the javaasvvy-theme.war to  deploy folder under bundles directory

you can change the deployment directory also  in liferay-theme.json file which can be found in theme root directory

 "LiferayTheme": {
 "appServerPath": "D:\\liferay-work\\LR7EE\\lds\\workspace\\liferay-workspace\\bundles\\tomcat-8.0.32",
 "deployPath": "D:\\liferay-work\\LR7EE\\lds\\workspace\\liferay-workspace\\bundles\\deploy",
 "url": "http://localhost:8080",
 "appServerPathPlugin": "D:\\liferay-work\\LR7EE\\lds\\workspace\\liferay-workspace\\bundles\\tomcat-8.0.32\\webapps\\javasavvy-theme",
 "deployed": true,
 "pluginName": "javasavvy-theme"
 }
}

Note: you might get the below error:

[18:18:44] Starting ‘build:compile-ruby-sass’…
[18:18:53] error build/_css/aui/lexicon/lexicon-base/mixins/_nameplates.scss (Line 14: Invalid CSS after “(max-width: “: expected expression (e.g. 1px, bold), was “$screen-xs-max)”)

then edit the file “\javasavvy-theme\node_modules\liferay-frontend-theme-unstyled\css\aui\lexicon\lexicon-base\_nameplates.scss” and  comment below code:

//.nameplate-label-autofit-xs-max {
// @include nameplate-label-autofit('max-width: $screen-xs-max');
//}

After deploying theme, you may see below warning but still liferay 7 supports velocity:

9 WARN  [Refresh Thread: Equinox Container: 7023f7e4-d0b3-0016-19e8-d1eb27696407][ThemeHotDeployListener:129] Support of Velocity is deprecated. Update theme javasavvy to use FreeMarker for forward compatibility.