Using a Theme CSS Client Extension

Liferay 7.4+

With a theme CSS client extension, you can override the current theme’s CSS files (main.css and clay.css) to change the look and feel of a page. Start with a client extension from the sample workspace.

Beginning with Liferay DXP 7.4 Q2/Portal 7.4 GA120, you can provide a frontend token definition in a theme CSS client extension. Earlier releases required a theme module. You must use at least version 10.1.1 of the workspace plugin, com.liferay.gradle.plugins.workspace. Set this in the settings.gradle file at the root of the workspace:

classpath group: "com.liferay", name: "com.liferay.gradle.plugins.workspace", version: "10.1.1"

Prerequisites

Install a supported version of Java.

note

Check the compatibility matrix for supported JDKs, databases, and environments. See JVM Configuration for recommended JVM settings.

Download and unzip the sample workspace:

curl -o com.liferay.sample.workspace-latest.zip https://repository.liferay.com/nexus/service/local/artifact/maven/content\?r\=liferay-public-releases\&g\=com.liferay.workspace\&a\=com.liferay.sample.workspace\&\v\=LATEST\&p\=zip

unzip com.liferay.sample.workspace-latest.zip

Now you have the tools to deploy your first theme CSS client extension.

Examine How the Theme’s Styles are Overridden

The theme CSS client extension is in the sample workspace’s client-extensions/liferay-sample-theme-css-1/ folder. It is defined in the client-extension.yaml file:

liferay-sample-theme-css-1:
    clayRTLURL: css/clay_rtl.css
    clayURL: css/clay.css
    mainRTLURL: css/main_rtl.css
    mainURL: css/main.css
    name: Liferay Sample Theme CSS 1
    type: themeCSS

The client extension has the ID liferay-sample-theme-css-1 and contains the key configurations for a theme CSS client extension, including the type and path to the CSS resource files. See the Theme CSS YAML Configuration Reference for more information on the available properties.

It also contains the assemble YAML block:

assemble:
    - from: build/buildTheme/img
      into: static/img
    - from: build/buildTheme/images
      into: static/images

These directives ensure that after building the theme CSS client extension, images needed by the CSS are included as static resources in Liferay. The base theme referenced in the package.json file provides the images assembled from build/buildTheme/images, the base theme’s CSS requires them. The images assembled from build/buildTheme/img come directly from the client extension’s src/img folder.

The package.json file contains the following code:

{
   "dependencies": {
      "sassy-inputs": "1.0.6"
   },
   "liferayDesignPack": {
      "baseTheme": "styled"
   },
   "main": "package.json",
   "name": "@liferay/liferay-sample-theme-css-1",
   "version": "1.0.0"
}

The dependencies section includes the sassy-inputs library. This is not used in the example, but shows how to import and use an npm module in your theme CSS client extension. The liferayDesignPack section declares the base theme used for the styles. Using the styled theme ensures that the existing styles specified on pages, fragments and widgets are not impacted. The other fields main, name and version provide required metadata.

note

You can set the base theme to styled or unstyled. The unstyled theme contains a set of basic styles and the styled theme contains all styles from the unstyled theme along with additional styling. All themes in Liferay use the unstyled or styled theme as the base.

If you apply the theme CSS client extension to a page that uses a different theme, the client extension’s styling replaces the styling from the theme. If you have custom styles in your original theme, make sure you add those to the _custom.scss file so that those elements are not affected when you apply the client extension.

If you change the theme of a page that already uses a theme CSS client extension, the client extension is removed.

The src/css/_custom.scss file contains this SCSS:

@import 'sassy-inputs/sass/main';

header {
   background-image: url(../img/header_bg.jpg);
}

The first line imports the npm module added in package.json. The CSS modifies the header to use an image as its background.

note

Your code is present inside _custom.scss while the client-extension.yaml file points to clay.css and main.css. This is because the theme CSS client extension runs the full Clay CSS build process resulting in a compiled clay.css and main.css file that also contains the compiled CSS code from _custom.scss.

Modify the Theme CSS

Add CSS to create a hover effect for all images. Open the _custom.scss file and add a declaration for img:hover:

img:hover{
   border: 2px solid red;
   border-radius: 10%;
}

This defines images as having a 2px red border and rounded edges on hover.

Now deploy the client extension.

Deploy Your Theme CSS Client Extension

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.120-ga120

Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com and the password test. When prompted, change the password to learn.

Once Liferay starts, run this command from the client extension’s folder in the sample workspace:

../../gradlew clean deploy -Ddeploy.docker.container.id=$(docker ps -lq)

This builds your client extension and deploys the zip to Liferay’s deploy/ folder.

note

To deploy your client extension to Liferay SaaS, use the Liferay Cloud Command-Line Tool to run lcp deploy.

tip

To deploy all client extensions in the workspace simultaneously, run the command from the client-extensions/ folder.

Confirm the deployment in your Liferay instance’s console:

STARTED liferay-sample-theme-css-1_1.0.0

Apply the Theme CSS Client Extension to a Page

You can apply the theme CSS client extension to all pages at once. In fact, to provide a frontend token definition using a theme CSS client extension, you must apply the client extension this way:

Open Site Menu (Site Menu), expand Site Builder, and click Pages.
Click Options (Options) → Configuration.
Scroll down to Theme CSS Client Extension and apply it to all pages.

To configure a single page to use your theme CSS:

On a page, click Edit () at the top.
In the sidebar, navigate to the Page Design Options menu () and click Configuration () at the top of the menu.
In the Theme CSS Client Extension section under the Look and Feel tab, click Add ().
Select the newly deployed client extension, Liferay Sample Theme CSS 1.
Scroll down and click Save.

In the page editor, the background on the header is an image, and every link that you hover over has changed background and text color. To see your changes applied on the page outside Edit mode, you must publish the page.

The new theme appears on the selected page.