Theme Builder Gradle Plugin

The Theme Builder Gradle plugin lets you run the Liferay Theme Builder tool to build the Liferay theme files in your project.

The plugin has been successfully tested with Gradle 4.10.2.

Usage

To use the plugin, include it in your build script:

buildscript {
    dependencies {
        classpath group: "com.liferay", name: "com.liferay.gradle.plugins.theme.builder", version: "2.0.7"
    }

    repositories {
        maven {
            url "https://repository-cdn.liferay.com/nexus/content/groups/public"
        }
    }
}

apply plugin: "com.liferay.portal.tools.theme.builder"

The Theme Builder plugin automatically applies the war plugin. It also applies the com.liferay.css.builder plugin to compile the Sass files in the theme.

Since the plugin automatically resolves the Liferay Theme Builder library as a dependency, you have to configure a repository that hosts the library and its transitive dependencies. The Liferay CDN repository hosts them all:

repositories {
    maven {
        url "https://repository-cdn.liferay.com/nexus/content/groups/public"
    }
}

Tasks

The plugin adds one task to your project:

Name	Depends On	Type	Description
buildTheme	-	BuildThemeTask	Builds the theme files.

The plugin also adds the following dependencies to tasks defined by the com.liferay.css.builder and war plugins:

Name	Depends On
buildCSS	buildTheme
war	buildTheme

The buildCSS dependency compiles the Sass files contained in the directory specified by the buildTheme.outputDir property. Moreover, the war task is configured as follows

• exclude the directory specified in the buildTheme.diffsDir property from the WAR file.
• include the files contained in the buildTheme.outputDir directory into the WAR file.
• include only the compiled CSS files, not SCSS files, into the WAR file.

The buildTheme task is automatically configured with sensible defaults:

Property Name	Default Value
diffsDir	project.webAppDir
outputDir	"${project.buildDir}/buildTheme"
parentFile	The first JAR file in the parentThemes configuration that contains a META-INF/resources/${buildTheme.parentName} directory, or the first WAR file in the parentThemes configuration whose name starts with ${parentName}-theme-.
parentName	"_styled"
templateExtension	"ftl"
themeName	project.name
unstyledFile	The first JAR file in the parentThemes configuration that contains a META-INF/resources/_unstyled directory.

BuildThemeTask

Tasks of type BuildThemeTask extend JavaExec, so all its properties and methods, such as args and maxHeapSize, are available. They also have the following properties set by default:

Property Name	Default Value
args	Theme Builder command line arguments
classpath	project.configurations.themeBuilder
main	"com.liferay.portal.tools.theme.builder.ThemeBuilder"

Task Properties

Property Name	Type	Default Value	Description
diffsDir	File	null	The directory that contains the files to copy over the parent theme. It sets the --diffs-dir argument.
outputDir	File	null	The directory where to build the theme. It sets the --output-dir argument.
parentDir	File	null	The directory of the parent theme. It sets the --parent-path argument.
parentFile	File	null	The JAR file of the parent theme. If parentDir is specified, this property has no effect. It sets the --parent-path argument.
parentName	String	null	The name of the parent theme. It sets the --parent-name argument.
templateExtension	String	null	The extension of the template files, usually "ftl" or "vm". It sets the --template-extension argument.
themeName	String	null	The name of the new theme. It sets the --name argument.
unstyledDir	File	null	The directory of Liferay Frontend Theme Unstyled. It sets the --unstyled-dir argument.
unstyledFile	File	null	The JAR file of Liferay Frontend Theme Unstyled. If unstyledDir is specified, this property has no effect. It sets the --unstyled-dir argument.

The properties of type File support any type that can be resolved by project.file. Moreover, it is possible to use Closures and Callables as values for the String properties to defer evaluation until task execution.

Additional Configuration

There are additional configurations that can help you use the CSS Builder.

Liferay Theme Builder Dependency

By default, the plugin creates a configuration called themeBuilder and adds a dependency to the latest released version of the Liferay Theme Builder. It is possible to override this setting and use a specific version of the tool by manually adding a dependency to the themeBuilder configuration:

dependencies {
    themeBuilder group: "com.liferay", name: "com.liferay.portal.tools.theme.builder", version: "1.1.7"
}

Parent Theme Dependencies

By default, the plugin creates a configuration called parentThemes and adds dependencies to the latest released versions of the Liferay Frontend Theme Styled, Liferay Frontend Theme Unstyled, and Liferay Frontend Theme Classic artifacts. It is possible to override this setting and use a specific version of the artifacts by manually adding dependencies to the parentThemes configuration. For example,

dependencies {
    parentThemes group: "com.liferay", name: "com.liferay.frontend.theme.styled", version: "VERSION"
    parentThemes group: "com.liferay", name: "com.liferay.frontend.theme.unstyled", version: "VERSION"
    parentThemes group: "com.liferay.plugins", name: "classic-theme", version: "VERSION"
}

Specifying dependency versions is not required when leveraging workspace’s Target Platform functionality. All dependencies with the group ID com.liferay or com.liferay.portal are automatically set when targeting a platform. For external theme dependencies (e.g., classic-theme with the group ID com.liferay.plugins), you can find the version used by your specific Liferay DXP instance by leveraging the Gogo shell. In a Gogo shell prompt, execute the following command:

lb -s theme

This lists the deployed theme bundles and their versions. Extract the versions for the theme dependencies you want to leverage and add them to your configuration.