Introduction
With the latest release of the UI theme designer (2.2.5) you have now the possibility to add preview pages from a different host or domain.
Preview pages in the UI theme designer help you to see the changes you make in the editor. The UI theme designer comes with a set of predefined preview pages for various SAP UI technologies. But now you have the ability to add your own applications even if they are on a different host or domain. The following paragraph shows an example of the required steps for your preview page.
Prepare your preview page
Before you can add your own application as a preview page it must undergo preparation to be fit for the theming process. Your application should utilize the SAP theming parameters and respond to the Post Message sent from the UI theme designer when any parameter is modified.
The theming parameters are accessible through the open-source
theming-base-content, which presents them as
CSS Custom Properties. For each theme there is a
css_variables.css file containing all parameter definitions. For the purposes of the following, we will leverage the unpkg.com service and enable the direct referencing of npm packages via URL.
- Considering a minimal HTML example, you just add the following element:
<link rel="stylesheet" href="https://unpkg.com/@sap-theming/theming-base-content/content/Base/baseLib/sap_horizon/css_variables.css">
As you now loaded the css_variables.css in your HTML example you can directly start to use the CSS variables:
body {
background-color: var(--sapBackgroundColor);
}
- Whenever a theming parameter is altered in the UI theme designer, a Post Message will be generated containing the css_variables.css, including the updated parameters. The Post message contains an object with the following structure:
{
"type": "theming-ui:theme-changed",
"cssVariables": "<ALL CSS VARIABLES WITH CURRENT VALUE AS STRING>"
}
You need to implement a script to react to the Post Message sent by the UI theme designer and to overwrite the style of the loaded base theme.
In order for this to work you add an additional style tag with the id
cssVariablesStyleTag:
<style id="cssVariablesStyleTag"></style>
- The script part will for example look something like this:
const cssVariablesStyleTag = document.getElementById('cssVariablesStyleTag');
addEventListener('message', ({data}) => {
if (data.type === 'theming-ui:theme-changed') {
cssVariablesStyleTag.textContent = data.cssVariables;
}
});
The script listens to incoming Post Messages and checks the data for the type theming-ui:theme-changed. Then it sets the text content of the style tag cssVariablesStyleTag to all the CSS variables coming from the Post Message.
Below is a complete example on how an application can look like with the integration for the UI theme designer support.
<!doctype html>
<html>
<head>
<title>My Preview Page</title>
<link rel="stylesheet" href="https://unpkg.com/@sap-theming/theming-base-content/content/Base/baseLib/sap_horizon/css_variables.css">
<style id="cssVariablesStyleTag"></style>
<style>body { background-color: var(--sapBackgroundColor); }</style>
</head>
<body>
<script>
const cssVariablesStyleTag = document.getElementById('cssVariablesStyleTag');
addEventListener('message', ({data}) => {
if (data.type === 'theming-ui:theme-changed') {
cssVariablesStyleTag.textContent = data.cssVariables;
}
});
</script>
</body>
</html>
Add your preview in the UI theme designer
In the UI theme designer you can select between different build-in preview pages to see the changes you are planning to do. Additionally you can add your own preview page to directly have the look and feel of your own applications.
Follow these steps to add your own preview page:
- In the left area click on the ⊕ besides the Preview Pages.
- Enter the URL of the application you want to use as a preview page
- Optionally you can enter a name for the preview page
- Press Add.
- A popup will inform you that your preview page is accessed cross origin. Click OK.
- Now click on the left area under Applications on your new preview page.
Your preview page is now open and you can start customizing. Any modifications made will immediately be reflected on your preview page.
Conclusion
Now you can add your own previews to the UI theme designer and make custom theming even more exciting. With just a few lines of code you can prepare your application and add it to the previews in the UI theme designer.
Im looking forward to all your custom preview pages. Let me know in the comments what you think about the new feature.
