The theme development approach drastically changed in Liferay 7 (DXP). In liferay 6.2 we could easily develop child theme from existing parent theme like classic theme. However its not straight forward in liferay DXP. Along with liferay 7 it has introduced various tool and technologies like node, npm, OSGI, blade CLI etc. Theme development in liferay 7 may be cumbersome for those developers who are not much acquainted with Liferay 7 environment. This article gives quick start guide for liferay theme development with Maven approach.
Approach:
Liferay provides maven archetype for theme development. We will generate the project structure by maven in command prompt and import in eclipse.
Command to generate Project Structure:
We are creating sample-theme which is the artifact name. You can change it accordingly.
mvn archetype:generate -DgroupId=com.proliferay -DartifactId=sample-theme -DarchetypeGroupId=com.liferay -DarchetypeArtifactId=com.liferay.project.templates.theme
Alternatively you can generate archetypes in interactive mode. To generate the project structure using interactive mode you can type the below command in the command prompt. You can select option 1 and follow the steps.
mvn archetype:generate -Dfilter=theme
The directory structure of the project would be
Now we can import the project as maven project into our favorite IDE eclipse
Adding CSS and Template Files:
Once project structure is created you might be thinking where to add css, template and other files like images, js etc. Yes all have to go inside webapp as shown in the above. You can crate below directories manually inside the webapp directory to add various static resources.
css (already created by maven)
images (for images required for the theme)
js (js files required for the theme)
templates (it may contains either free marker templates or velocity templates)
Understanding the POM
The backbone of a maven project is pom.xml which contains dependencies and various maven plugins. The generated pom.xml contains all the necessary dependencies as well as plugins and almost no need of any further modifications in it.
Parent Theme:
The parent theme is specified in the pom by <parentName>_styled</parentName> which is the default.
In liferay DXP it has two base themes, called styled and unstyled. The styled theme inherits from the unstyled theme and simply adds some additional styling on top.So inside parentName tag we can have either _styled or _unstyled based on our needs.
Sass files compilation:
Using sass files (i.e., files extension with scss) in liferay theme is optional. However it has lots of advantages over plain css. In build life cycle these sass files must be converted to css files. After all browser understand only the css but not the sass files. So if our maven project contains sass files it must be converted to corresponding css files before packaging as WAR file. This job is done by below plugin which is already configured in the pom.xml
<plugin>
<groupId>com.liferay</groupId>
<artifactId>com.liferay.css.builder</artifactId>
<version>1.0.23</version>
<executions>
<execution>
<id>default-build-css</id>
<phase>compile</phase>
<goals>
<goal>build-css</goal>
</goals>
</execution>
</executions>
<configuration>
<docrootDirName>${com.liferay.portal.tools.theme.builder.outputDir}</docrootDirName>
<precision>9</precision>
</configuration>
</plugin>
You can simply compile sass files to css by mvn compile command
Template Files:
A liferay theme either contains free marker templates or velocity templates. By default maven will use free marker as template files. However this default behavior can be overridden to use velocity templates as below
<plugin>
<groupId>com.liferay</groupId>
<artifactId>com.liferay.portal.tools.theme.builder</artifactId>
<version>1.1.1</version>
<executions>
<execution>
<phase>generate-resources</phase>
<goals>
<goal>build-theme</goal>
</goals>
<configuration>
<diffsDir>src/main/webapp</diffsDir>
<outputDir>${com.liferay.portal.tools.theme.builder.outputDir}</outputDir>
<parentName>_styled</parentName>
<templateExtension>vm</templateExtension>
</configuration>
</execution>
</executions>
</plugin>
Excluding SASS files in WAR distribution:
Its better idea not to keep unnecessary files in WAR which are not required at the run-time for the browser. To exclude SASS files in WAR below plugin is configured
<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>3.0.0</version>
<configuration>
<packagingExcludes>**/*.scss</packagingExcludes>
<webResources>
<resource>
<directory>${com.liferay.portal.tools.theme.builder.outputDir}</directory>
<excludes>
<exclude>**/*.scss</exclude>
</excludes>
</resource>
</webResources>
</configuration>
</plugin>
Creating the replica of Liferay Classic Theme:
Till Liferay 6.2 this task was relay easy to accomplish. However in Liferay 7 we cant directly create a child theme of classic theme. However this is also possible in different way. If you have liferay source code you can copy the existing classic theme source code (css, js, images and templates folder) directly into your project webapp directory.
Note:
You can look the path liferay-portal-7.0.x\modules\apps\foundation\frontend-theme in liferay source code for classic theme.
Creating the WAR:
Execute the below command
mvn install
Download:
Remember this is barebone theme.It does not contain rich styling. You must have to add those.
