Using a Theme Sprite Map Client Extension
Available Liferay 7.4 U45+/GA45+
With a theme sprite map client extension, you can override the default Clay sprite map used for icons on a page. Start with the sample workspace to build and deploy your client extension.
An SVG sprite map is an image that contains several icons grouped together, each with a unique ID. You can load the SVG and reference the individual icons by ID. This provides a slight performance improvement, as you can download and cache the sprite map once to display all the site icons.
To start developing client extensions,
Install Java (JDK 8 or JDK 11).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
Now you have the tools to deploy your first theme sprite map client extension.
Examine the Theme Sprite Map Project
The theme sprite map client extension is in the sample workspace’s
client-extensions/liferay-sample-theme-spritemap-1/ folder. It is defined in the
liferay-sample-theme-spritemap-1: name: Liferay Sample Theme Spritemap 1 type: themeSpritemap url: spritemap.svg
The client extension has the ID
liferay-sample-theme-spritemap-1 and contains the key configurations for a theme sprite map client extension, including the type and the sprite map file to add. See the Theme Sprite Map YAML Configuration Reference for more information on the available properties.
It also contains the
assemble YAML block:
assemble: - from: assets into: static
This specifies that everything in the
assets/ folder should be included as a static resource in the built client extension
.zip file. The SVG sprite map in a theme sprite map client extension is used as a static resource in Liferay.
The sample project’s
assets/spritemap.svg is a copy of the Clay icons sprite map used in Liferay. You won’t notice any changes in the UI as all the icons used in Liferay are present in the example sprite map.
Since a sprite map client extension replaces the entire sprite map on the selected page, make sure that you have all the necessary icons with their corresponding IDs to avoid missing icons.
Modify the Sprite Map
To change a specific icon, you must find the ID of the icon. You can inspect the HTML element to find this.
Given below are the IDs of the icons used on the top navbar.
To swap the pencil icon for a fish,
<symbol>tag corresponding to the ID of
assets/spritemap.svg. You must open the SVG file in a text editor to view this.
<symbol id="pencil" viewBox="0 0 512 512"> <path class="lexicon-icon-body" d="M490.9,363.4l-2.8-5.1C468.3,322.4,359.9,304,358.9,304l-2.4-0.1l-10.8,1.5c-16.9,3.9-31,15.7-50.5,33.8c-25.2-14.7-52.4-37.6-68.7-54.3c-16.7-17.1-39.9-47.7-52.4-71.6c22-21.6,37.4-38.7,38.4-61.7c0-1-13.8-110.1-48.9-131.7l0,0l-5.1-3.1c-9.6-5.7-27.5-16.4-49.3-16.4c-5.4,0-10.8,0.7-17,2.3c-6.9,2-13.3,4.8-20,9.1C55.9,23,26.2,46.7,11.7,78c-13.5,30.8-4.4,187.9,113.4,311c111.6,116.8,241.2,122.7,266.1,122.7c6.4,0,15.1-0.3,22.4-1.6l2.8-0.1l6.7-2.5c32.2-13.2,56.9-41.7,68.4-57.2C518.4,415.5,497.8,376.6,490.9,363.4L490.9,363.4z" fill="none"></path> <path class="lexicon-icon-outline" d="M490.9,363.4l-2.8-5.1C468.3,322.4,359.9,304,358.9,304l-2.4-0.1l-10.8,1.5c-16.9,3.9-31,15.7-50.5,33.8c-25.2-14.7-52.4-37.6-68.7-54.3c-16.7-17.1-39.9-47.7-52.4-71.6c22-21.6,37.4-38.7,38.4-61.7c0-1-13.8-110.1-48.9-131.7l0,0l-5.1-3.1c-9.6-5.7-27.5-16.4-49.3-16.4c-5.4,0-10.8,0.7-17,2.3c-6.9,2-13.3,4.8-20,9.1C55.9,23,26.2,46.7,11.7,78c-13.5,30.8-4.4,187.9,113.4,311c111.6,116.8,241.2,122.7,266.1,122.7c6.4,0,15.1-0.3,22.4-1.6l2.8-0.1l6.7-2.5c32.2-13.2,56.9-41.7,68.4-57.2C518.4,415.5,497.8,376.6,490.9,363.4L490.9,363.4z M445.4,415.1c-10.5,14-27.3,31.3-42.6,38c-1.5,0.2-5.4,0.6-11.6,0.6c-20.7,0-128.8-5.1-224.1-104.8C67,244.3,62.6,119,65.5,100c6.6-12.7,21.2-27.7,38.7-39.8c0.5-0.3,1.9-1.1,3.4-1.6c5.5-1.4,15.6,4.6,21,7.8l2.4,1.5c8.1,13.5,20.6,63.6,23.3,81.2c-3.8,6.4-19.2,21.4-27.7,29.8l-1,1.1c-11.9,12.8-15.5,31.2-8.9,47.3c14.2,32.9,45.9,75.3,68.4,98.3c22.1,22.8,59.4,53.4,93.2,70.6c16.3,8.1,36.3,4.8,49.1-7.5c10.1-9.4,25-23.4,30.6-26.3c17.6,3.4,67.7,18.2,80.8,26.7l1.1,2C446.9,404.3,448.5,411,445.4,415.1L445.4,415.1z"></path> </symbol>
Replace this with a custom icon and give it the same ID (
pencil). Use the below
symbolfor a fish icon.
<symbol id="pencil" viewBox="0 26 100 48"> <path d="M98.5,47.5C96.5,45.5,81,35,62,35c-2.1,0-4.2,0.1-6.2,0.3L39,26c0,4.5,1.3,9,2.4,12.1C31.7,40.7,23.3,44,16,44L0,34 c0,8,4,16,4,16s-4,8-4,16l16-10c7.3,0,15.7,3.3,25.4,5.9C40.3,65,39,69.5,39,74l16.8-9.3c2,0.2,4.1,0.3,6.2,0.3 c19,0,34.5-10.5,36.5-12.5S100.5,49.5,98.5,47.5z M85.5,50c-1.4,0-2.5-1.1-2.5-2.5s1.1-2.5,2.5-2.5s2.5,1.1,2.5,2.5 C88,48.9,86.9,50,85.5,50z"/> </symbol>
Deploy the Sprite Map Client Extension
Start a new Liferay instance by running
docker run -it -m 8g -p 8080:8080 liferay/portal:22.214.171.124-ga75
Sign in to Liferay at http://localhost:8080. Use the email address [email protected] and the password test. When prompted, change the password to learn.
Next, run this command from the client extension project’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
To deploy your client extension to Liferay Experience Cloud, use the Liferay Cloud Command-Line Tool to run
To deploy all client extensions in the workspace simultaneously, run the command from the
Confirm the deployment in your Liferay instance’s console:
Use the New Sprite Map on a Page
The theme sprite map client extension is currently behind a dev feature flag (
LPS-166479). You must not use this client extension in production. Use it only for testing purposes.
Configure a page to use your deployed client extension:
Go to the page, then 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 Sprite Map Client Extension section, click Add ().
Select the newly deployed sprite map, Liferay Sample Theme Spritemap 1.
Scroll down and click Save.
Go back to the page. In the navbar, a fish icon has replaced the pencil () for the edit functionality.
You have successfully used a theme sprite map client extension. Next, try deploying other client extension types.