Liferay’s Theme Builder is used to build Liferay DXP theme files in your project. You can incorporate the Theme Builder into your Maven project to generate WAR-style themes deployable to Liferay DXP.
The easiest way to create a Liferay theme with Maven is to create a new Maven project using Liferay’s provided Theme archetype; Theme Builder is configured in the new project by default. In some cases, however, this may not be convenient. For instance, if you have a legacy theme project and don’t want to start over, generating a new project is not ideal.
For cases like this, you should manually configure your Maven project to leverage Theme Builder. You’ll learn how to do this next.
-
Configure Liferay’s Theme Builder plugin in your project’s
pom.xml
file:<build> <plugins> <plugin> <groupId>com.liferay</groupId> <artifactId>com.liferay.portal.tools.theme.builder</artifactId> <version>1.1.7</version> <executions> <execution> <phase>generate-resources</phase> <goals> <goal>build</goal> </goals> <configuration> <diffsDir>${maven.war.src}</diffsDir> <name>${project.artifactId}</name> <outputDir>${project.build.directory}/${project.build.finalName}</outputDir> <parentDir>${project.build.directory}/deps/com.liferay.frontend.theme.styled.jar</parentDir> <parentName>_styled</parentName> <templateExtension>ftl</templateExtension> <unstyledDir>${project.build.directory}/deps/com.liferay.frontend.theme.unstyled.jar</unstyledDir> </configuration> </execution> </executions> </plugin> </plugins> </build>
The above configuration applies the Theme Builder plugin and then defines the Theme Builder’s execution and configuration.
- The
executions
tag configures the Theme Builder to run during the
generate-resources
phase of your Maven project’s build lifecycle. Thebuild
goal is defined for that lifecycle phase. - The configuration defines tag several important properties. For more info on these properties, see the Theme Builder Plugin article.
- The
executions
tag configures the Theme Builder to run during the
-
Apply the CSS Builder plugin, which is required to use Theme Builder:
<plugin> <groupId>com.liferay</groupId> <artifactId>com.liferay.css.builder</artifactId> <version>2.1.3</version> <executions> <execution> <id>default-build</id> <phase>compile</phase> <goals> <goal>build</goal> </goals> </execution> </executions> <configuration> <docrootDirName>target/${project.build.finalName}</docrootDirName> <outputDirName>/</outputDirName> <portalCommonPath>target/deps/com.liferay.frontend.css.common.jar</portalCommonPath> </configuration> </plugin>
You can learn more about the CSS Builder’s Maven configuration by visiting the Compiling Sass Files in a Maven Project tutorial.
-
You can configure your project to exclude Sass files from being packaged in your theme. This is optional, but is a nice convenience to keep any unnecessary source code out of your WAR. Since the Theme Builder creates a WAR-style theme, you should apply the maven-war-plugin so it instructs the WAR file packaging process to exclude Sass files:
<plugin> <artifactId>maven-war-plugin</artifactId> <version>3.0.0</version> <configuration> <packagingExcludes>**/*.scss</packagingExcludes> </configuration> </plugin>
-
Insert the
<packaging>
tag in your project’s POM so your project is correctly packaged as a WAR file. This tag can be placed with your project’sgroupId
,artifactId
, andversion
specifications like this:<groupId>com.liferay</groupId> <artifactId>com.liferay.project.templates.theme</artifactId> <version>1.0.0</version> <packaging>war</packaging>
-
Building themes requires certain dependencies. You can configure these dependenices in your project’s
pom.xml
as directories or JAR files. If you choose to use JARs, you must apply the maven-dependency-plugin and have it copy JAR dependencies into your project from Maven Central:<plugin> <artifactId>maven-dependency-plugin</artifactId> <executions> <execution> <phase>generate-sources</phase> <goals> <goal>copy</goal> </goals> <configuration> <artifactItems> <artifactItem> <groupId>com.liferay</groupId> <artifactId>com.liferay.frontend.css.common</artifactId> <version>${com.liferay.frontend.css.common.version}</version> </artifactItem> <artifactItem> <groupId>com.liferay</groupId> <artifactId>com.liferay.frontend.theme.styled</artifactId> <version>${com.liferay.frontend.theme.styled.version}</version> </artifactItem> <artifactItem> <groupId>com.liferay</groupId> <artifactId>com.liferay.frontend.theme.unstyled</artifactId> <version>${com.liferay.frontend.theme.unstyled.version}</version> </artifactItem> </artifactItems> <outputDirectory>${project.build.directory}/deps</outputDirectory> <stripVersion>true</stripVersion> </configuration> </execution> </executions> </plugin>
This configuration copies the
com.liferay.frontend.css.common
,com.liferay.frontend.theme.styled
, andcom.liferay.frontend.theme.unstyled
dependencies into your Maven project. Notice that you’ve set thestripVersion
tag totrue
and you’re setting the artifact versions within eachartifactItem
tag. You’ll set these versions and a few other properties for your Maven project next. -
Configure the properties for your project in its
pom.xml
file:<properties> <com.liferay.css.builder.version>2.1.3</com.liferay.css.builder.version> <com.liferay.frontend.css.common.version>2.0.4</com.liferay.frontend.css.common.version> <com.liferay.frontend.theme.styled.version>2.0.28</com.liferay.frontend.theme.styled.version> <com.liferay.frontend.theme.unstyled.version>2.2.5</com.liferay.frontend.theme.unstyled.version> <com.liferay.portal.tools.theme.builder.version>1.1.7</com.liferay.portal.tools.theme.builder.version> </properties>
The properties above set the versions for the CSS and Theme Builder plugins and their dependencies.
You’ve successfully configured your Maven project to build a Liferay theme with Theme Builder!