If you want to package UI resources independent of a specific theme and include them on a Liferay DXP page, Theme Contributors are your best option. If, instead, you’d like to include separate UI resources on a Liferay DXP page that are attached to a theme, you should look into themelets.
A Theme Contributor is a module that contains UI resources to use in Liferay DXP. Once a Theme Contributor is deployed to Liferay DXP, it’s scanned for all valid CSS and JS files, and then its resources are included on the page. You can, therefore, style these UI components as you like, and the styles are applied for the current theme.
This tutorial demonstrates how to
- Identify a Theme Contributor module.
- Create a Theme Contributor module.
Next, you’ll learn how to create a Theme Contributor.
In Liferay versions prior to 7.0, the standard UI for User menus and navigation (the Dockbar) was included in the theme template. Starting in Liferay DXP 7.0, these standard UI components are packaged as Theme Contributors.
For example, the Control Menu, Product Menu, and Simulation Panel are packaged as Theme Contributor modules in Liferay, separating them from the theme. This means that these UI components must be handled outside the theme.
If you want to edit or style these standard UI components, you’ll need to create your own Theme Contributor and add your modifications on top. You can also add new UI components to Liferay DXP by creating a Theme Contributor.
To create a Theme Contributor module, follow these steps:
To identify your module as a Theme Contributor, add the
Web-ContextPathheaders to your module’s
bnd.bndfile. For example, see the Control Menu Theme Contributor module’s
Bundle-Name: Liferay Product Navigation Control Menu Theme Contributor Bundle-SymbolicName: com.liferay.product.navigation.control.menu.theme.contributor Bundle-Version: 1.0.0 Liferay-Releng-Module-Group-Description: Liferay-Releng-Module-Group-Title: Product Navigation Liferay-Theme-Contributor-Type: product-navigation-control-menu Web-ContextPath: /product-navigation-control-menu-theme-contributor -include: ../../../../../marketplace/web-content-management/bnd.bnd
The Theme Contributor type helps Liferay DXP better identify your module. For example, if you’re creating a Theme Contributor to override an existing Theme Contributor, you should try to use the same type to maximize compatibility with future developments. The
Web-ContextPathheader sets the context from which the Theme Contributor’s resources are hosted.
Because you’ll often be overriding CSS of another Theme Contributor, you should load your CSS after theirs. You can do this by setting a weight for your Theme Contributor. In your
bnd.bndfile, add the following header:
The higher the value, the higher the priority. If your Theme Contributor has a weight of 100, it will be loaded after one with a weight of 99, allowing your CSS to override theirs.
src/main/resources/META-INF/resourcesfolder in your module and place your resources (CSS and JS) in that folder.
Build and deploy your module to see your modifications applied to Liferay DXP pages and themes.
That’s all you need to do to create a Theme Contributor for your site. Remember, with great power comes great responsibility, so use Theme Contributors wisely. The UI contributions affect every page and aren’t affected by theme deployments.