Bundling Independent UI Resources via Theme Contributors

Theme contributors are modules that contain CSS and JavaScript resources and apply them to every page. They are independent from specific themes, and you can configure them to override specific styles from themes or even each other. Use themelets instead if you want to include separate UI resources on a page and include them in specific themes.

Many menus in Liferay Portal/DXP are packaged as theme contributors, such as the Site Menu.

If you want to edit or style standard UI components like the Site Menu, then you must deploy your changes with a theme contributor. You can also add new UI components or styles using theme contributors.

Deploy a Simple Theme Contributor

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:2024.q1.1

Sign in to Liferay at http://localhost:8080 using the email address [e-mail] and the password test. When prompted, change the password to learn.

Then, follow these steps to deploy the example theme contributor:

1. Download and unzip the example.

   curl https://resources.learn.liferay.com/dxp/latest/en/site-building/site-appearance/themes/theme-development/bundling-resources/liferay-w9m6.zip -O
   

   unzip liferay-w9m6.zip
   

2. Build and deploy the example.

   cd liferay-w9m6
   

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

   note

   This command is the same as copying module JARs to /opt/liferay/osgi/modules on the Docker container.

3. Confirm the deployment in the Docker container console.

   STARTED com.acme.w9m6.web_1.0.0
   

4. Verify that the theme contributor changed your Site’s background color. Open your browser to https://localhost:8080 and confirm that the Liferay home page’s background is now blue.

Congratulations, you’ve successfully built and deployed a new theme contributor.

Next, you’ll learn how a theme contributor looks with custom CSS changes.

Examine the Example Theme Contributor

A theme contributor is an OSGi module, and must have properties in its bnd.bnd file. Customizations are then added in the resources folder. The example theme contributor uses a custom.css file to change each page’s background color.

Examine the Theme Contributor Properties

The theme contributor’s project has the necessary properties added to its bnd.bnd file to configure it.

Bundle-Name: Acme W9M6 Web
Bundle-SymbolicName: com.acme.w9m6.web
Bundle-Version: 1.0.0
Liferay-Theme-Contributor-Type: CSS
Liferay-Theme-Contributor-Weight: 1
Web-ContextPath: /w9m6-web

A theme contributor’s bnd.bnd file must have these properties for it to function:

Web-ContextPath: sets the context for your theme contributor’s resources. In the example module, the context path is w9m6-web.

Liferay-Theme-Contributor-Type: indicates that your module adds a theme contributor. This property can be any arbitrary value. The example module uses the value CSS.

Liferay-Theme-Contributor-Weight: configures the weight of your theme contributor’s styles versus other contributors. Lower values are given higher priority to override styles from other contributors. The example module uses a weight of 1 to guarantee that the style has the highest priority of any theme contributor.

Once the bnd.bnd file has the necessary properties, the module needs only have the desired customizations.

Examine the Style Customizations

Any desired CSS or JavaScript files must be added to subfolders within the module. CSS files belong in a src/main/resources/META-INF/resources/css/ subfolder, and JavaScript files belong in a src/main/resources/META-INF/resources/js/ subfolder.

The example theme contributor uses a simple CSS style change to make each page’s background blue. This is done with a custom.css file in src/main/resources/META-INF/resources/:

body, #wrapper {
    background: blue;
}

Once all of the desired CSS or JavaScript files are added to the correct subfolders, deploying the module applies them to every page.

Change the Background Color

Now to see how the theme contributor affects your pages, try changing the background color.

1. Open src/main/resources/META-INF/resources/css/custom.css in your project.

2. Change the background color property to another color, like orange:

   body, #wrapper {
       background: orange;
   }
   

3. Build and deploy the example again to your running Docker container:

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

4. Confirm the deployment in the Docker container console.

   STARTED com.acme.w9m6.web_1.0.0
   

5. Verify that the theme contributor changed your Site’s background to the new color. Open your browser to https://localhost:8080 to confirm the change.

Conclusion

Congratulations! You’ve created a theme contributor with a CSS style change. You can also apply specific style changes to your Site’s pages with Style Books.

Related Topics

• Bundling and Installing Resources into Your Theme via Themelets
• Themes
• Using a Style Book to Standardize Site Appearance