Modifying Site Appearance

Themes have long been the primary mechanism for customizing the appearance of a Liferay site with custom CSS. Complementary design tools, such as master pages and style books, extend and enhance the visual foundation provided by themes. Traditionally, themes were built using OSGi plugins. This approach requires redeployments even for minor CSS changes and can lead to unnecessary inefficiencies during project delivery. Liferay recommends frontend client extensions as the preferred method for efficient, flexible site customization.

This lesson focuses on utilizing theme CSS and global CSS client extensions to extend Liferay’s out-of-the-box styling capabilities.

Building Themes with Clay

Clay is Liferay’s design component library. Built on Bootstrap, Clay is the foundational framework for defining design elements, layout structures, and component styles for your site. Clay provides a wide selection of custom components (e.g., modals, icons, management bars, etc.) that align with Liferay’s user interface guidelines, along with a set of SCSS variables that you can override to tailor those components to your brand and visual identity. See Clay's documentation to learn more about the framework.

The theme CSS client extension overrides two files, main.css and clay.css, to modify the styling elements of your site’s theme. With this approach, you can rewrite Clay variables as needed rather than starting from scratch. By reusing predefined variables, you ensure that all your components adhere to a cohesive design language and responsive layout, enhancing both the developer and user experiences. You should use Clay as much as possible; for situations where the predefined variables are not sufficient, you also have the option of adding a custom SCSS file with your own components.

The foundational styling supplied by Bootstrap and extended by Clay simplifies maintenance and supports updates across the entire theme. By using this approach, you minimize redundancies and keep your design scalable. Developers also benefit from community-driven improvements and updates without risking style fragmentation or unexpected interactions. Understanding Clay is critical for effectively employing theme CSS client extensions. Now, let’s take a closer look at the client extension itself.

Using Theme CSS Client Extensions

The theme CSS client extension provides two types of resources: CSS style sheet and frontend token definition. The first type of resource includes main.css, clay.css, and any additional custom styling elements you want to implement. These resources are common to both the client extension paradigm and the legacy plugin approach.

The second type of resource, frontend token definition, is used with Liferay style books. A style book provides visual rules for applying a consistent experience across a site’s pages. These rules are represented by tokens. A frontend token definition is a collection of all tokens for a style book.

Anatomy of Theme CSS Client Extensions

As with all client extensions, the client-extension.yaml file for theme CSS client extensions contains an assemble block that specifies the source and target locations for resources that should be included in the deployment.

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

The extension definition block contains the core configurations for the client extension, as in the following example from liferay-sample-theme-css-3.

liferay-sample-theme-css-3:
    clayURL: css/clay.css
    clayRTLURL: css/clay_rtl.css
    mainURL: css/main.css
    mainRTLURL: css/main_rtl.css
    frontendTokenDefinitionJSON: src/frontend-token-definition.json
    name: Liferay Sample Theme CSS 3
    type: themeCSS

This table provides descriptions of the properties in the extension definition.

Deciding Between Custom Themes and Style Books

Deploying a theme CSS client extension with CSS style sheet resources will trigger a new theme registration in the Liferay portal. Once registered, the client extension is treated as a regular theme: you can choose to apply it to master pages, page templates, or individual pages. At runtime, when a page is being rendered, Liferay will load the resources from the associated theme. This mirrors the functionality of custom themes developed with the traditional plugin approach.

With the introduction of Liferay style books, you can customize your site appearance even with out-of-the-box themes. You can use the theme CSS client extension to provide a frontend token definition that redefines token values to match your branding needs. At present, there is no way to extend existing style books with additional tokens. If your solution requires additional tokens, you must use the theme CSS client extension to create a custom style book.

You can avoid the overhead of implementing a custom theme by leveraging style books. Of course, custom themes will continue to be supported in Liferay, but a careful analysis is required to determine whether style books are a better option for your particular needs. In either case, the theme CSS client extension is the recommended method of interacting with Liferay themes and style books.

Take the Mastering Liferay Design Elements course (coming soon) to learn more about style books.

Using Global CSS Client Extensions

While themes are a powerful tool for modifying your site’s appearance, it can be challenging to use them if your design elements aren’t built with Clay. Even if they are, you may want to implement unique styling components that do not rely on Clay or other Liferay design tools like style books. In these situations, and in general, you should leverage the global CSS client extension to customize the look and feel of your site.

Rather than embedding custom CSS in a theme, the global CSS client extension adds CSS resources directly to a page or element. These resources can live inside Liferay, or they can be hosted externally and referenced from Liferay. Global CSS client extensions provide a modular, flexible approach to styling. Unlike themes, global CSS enables you to specify only the resources you need on a particular page, foregoing the need to load resources that are not going to be used. For this reason, global CSS client extensions should be your primary tool for deploying custom style sheets, as long as you don’t need to define any style book tokens.

Note that you can use theme CSS and global CSS client extensions together in your solution. The load order is critical: global CSS is loaded after theme CSS. This means that you can implement a theme CSS client extension that governs your overall structure, layout, and styling, but you can override the theme on specific pages with a global CSS client extension. While Liferay recommends the global CSS client extension as your first option, it does not necessarily have to be your only option.

Anatomy of Global CSS Client Extensions

The global CSS client extension contains a single URL reference to a CSS file. This URL may reference an external resource, or it can reference a CSS file that is bundled with the client extension itself. The assemble block uses an include directive to indicate the source folder containing the CSS resource.

assemble:
    - include: static/*.css

The extension definition block contains the URL reference, as in the following example from liferay-sample-global-css.

liferay-sample-global-css:
    name: Liferay Sample Global CSS
    type: globalCSS
    url: global.*.css

This table provides descriptions of the properties in the extension definition.

Conclusion

By using a combination of theme CSS and global CSS client extensions, you can implement custom styling for your website with more efficiency and greater control than you can with traditional theme plugins. Next, you’ll help Clarity leverage these client extensions to modify the theme for one of their sub-brands: Clarity Kids.