Implementing Themes

Themes have long been a core component of the Liferay platform, and over the years their implementation has evolved to incorporate modern web development practices. Because of this evolution, it’s helpful to distinguish between the traditional approach to developing themes and the modern approach.

The classic approach to theme implementation is creating theme plugins, which use a combination of HTML, CSS, JavaScript (JS), and FreeMarker. These resources are built into a Web Archive (WAR) file and deployed to your Liferay instance. With the plugin approach, you control the entirety of your site’s look and feel with developer resources.

The modern evolution of implementing themes with plugins is using theme client extensions. Like plugins, client extensions also provide the means to customize site styling with CSS resources, but they are intended to be used alongside other Liferay features such as fragments, templates, and style books. In this lesson, you’ll learn about the benefits and challenges of theme plugin development and why client extensions are now the recommended approach for implementing themes.

Developing Theme Plugins

Theme plugins give developers control over all aspects of the portal presentation. Liferay provides tools to facilitate theme development, such as theme templates and Clay CSS resources, along with extension points for granular modifications of various elements. Theme plugins are highly configurable and customizable, but the same characteristics that make them so powerful also present challenges for development.

Plugins are bulky and come with significant maintenance overhead. Even small customizations often require a complete theme to be created, even if most of it is boilerplate or templated code. Plugin development is not only slow and costly, but also makes upgrading your Liferay version more difficult. Because theme plugins are deployed into Liferay and often override platform classes and templates, upgrading versions also requires updating themes to fix broken or outdated references. 

The tight coupling with the core platform is a major disadvantage because it makes theme plugins incompatible with Liferay SaaS. While plugins are compatible with the PaaS and self-hosted deployment approaches, they are no longer the recommended method of implementing themes. Instead, you should use frontend client extensions in conjunction with Liferay’s other native design elements whenever possible. 

Customizing Styles with Client Extensions

Liferay frontend client extensions provide a modern, streamlined approach to customizing themes and styling websites. The primary advantage of using client extensions over traditional plugins is that client extensions are deployed outside of Liferay. This simplifies maintenance and protects both the core platform and any extensions during upgrades that might otherwise cause breaking changes. Additionally, client extensions are compatible with all deployment types. 

There are two client extensions that are particularly relevant to theme implementation: the theme CSS client extension and the global CSS client extension.

Theme CSS Client Extension

The theme CSS client extension provides much of the same functionality as theme plugins, without any of the drawbacks of traditional plugin development. Using this client extension, you can replace all the styling of a site with custom settings. Note that when replacing a theme, you must include any existing styling that you wish to keep. So, while you benefit from all the advantages of the modern client extension approach, overriding themes this way is still a complex and resource-intensive process. If you need to completely redefine your site’s theme with custom styling, use the theme CSS client extension.

Liferay recommends limiting how often you replace or overhaul the entire theme of your site. Instead, one of the best ways to leverage the theme CSS client extension is to create frontend token definitions. Frontend tokens represent styling rules that you can configure with style books. Each token corresponds to a CSS variable, and the collection of all tokens is called the frontend token definition.

Global CSS Client Extension

With the global CSS client extension, you can add and modify styling across your site without having to override the entire theme. Because this client extension is not tied directly to the theme, it is much more versatile. You can implement one-off styling changes or modify specific parts of the platform without worrying about the elements that you are not changing. This flexibility makes the global CSS client extension the first choice for styling customizations in Liferay.

You can use both the theme CSS and global CSS client extensions together to style your website. Establish your foundational styling and structures first with the theme CSS client extension, and then use the global CSS client extension to tailor specific sections or elements to your desired look and feel.

When using the global CSS client extension, it’s best to modify the existing CSS class variables that Liferay provides out of the box. This reduces maintenance demands and enables more reuse of existing resources. If you find Liferay’s existing CSS variables insufficient for your design needs, you should use the theme CSS client extension to create a frontend token definition with new custom variables.

Conclusion

The implementation of themes in Liferay has changed dramatically as the platform has adopted modern web development best practices. While the traditional approach of developing theme plugins is powerful, it is weighed down by costly upgrades and limited integration with other platform design elements. The modern paradigm of frontend client extensions resolves these issues while offering the same rich functionality and granular control over site styling. For these reasons, Clarity has elected to use frontend client extensions in their solution.

Next, you’ll help them customize their site styling by adding a frontend token definition.