|
| 1 | +--- |
| 2 | +parser: v2 |
| 3 | +author_name: David Klug |
| 4 | +author_profile: https://github.com/david-klug-sap |
| 5 | +auto_validation: true |
| 6 | +time: 20 |
| 7 | +tags: [ tutorial>advanced, tutorial:how-to, software-product>sap-business-technology-platform, software-product>ui-theme-designer] |
| 8 | +primary_tag: software-product>ui-theme-designer |
| 9 | +--- |
| 10 | + |
| 11 | +# Add a Cross Origin Preview for the UI Theme Designer |
| 12 | +<!-- description --> Add a custom cross origin preview page for the UI theme designer to see the changes directly in your own application UIs. |
| 13 | + |
| 14 | +## Prerequisites |
| 15 | + - [You have set up the SAP Launchpad Service](btp-app-work-zone-subscribe) |
| 16 | + - You have a user with the **Subaccount Administrator** role collection in the subaccount where you set up the SAP Launchpad Service. |
| 17 | + |
| 18 | + |
| 19 | +## You will learn |
| 20 | + - How to add a custom preview page |
| 21 | + - How to prepare your preview page for theming |
| 22 | + |
| 23 | +--- |
| 24 | + |
| 25 | +### Access the Theme Designer |
| 26 | + |
| 27 | +The **UI theme designer** is a business service integrated in the launchpad service and can be accessed via your launchpad site. |
| 28 | + |
| 29 | +1. Access any launchpad site. |
| 30 | +2. Click on the user profile icon in the top-right corner to open the dropdown menu. Then click on **Theme Manager**. |
| 31 | + |
| 32 | + <!-- border --> |
| 33 | +  |
| 34 | + |
| 35 | +3. Click on **Launch Theme Designer** in the bottom-left corner. In the **UI theme designer** you can see an overview of all available custom themes, as well as create new ones. |
| 36 | + |
| 37 | + <!-- border --> |
| 38 | +  |
| 39 | + |
| 40 | +4. The **UI theme designer** is launched and you get an overview of your already existing custom themes. |
| 41 | + |
| 42 | + <!-- border --> |
| 43 | +  |
| 44 | + |
| 45 | +### Create a New Theme |
| 46 | + |
| 47 | +From the overview of the **UI theme designer** you can now create a new custom theme (or open an existing one). |
| 48 | + |
| 49 | +Every custom theme is bases on an SAP theme (e.g. SAP Horizon or SAP Quartz) |
| 50 | + |
| 51 | +1. Click on **Create a New Theme** in the top right. <br> |
| 52 | + |
| 53 | + <!-- border --> |
| 54 | +  |
| 55 | + |
| 56 | +2. You see a list of possible SAP themes as the base for your custom theme. Choose **SAP Horizon** and click on **Create Theme** |
| 57 | + |
| 58 | + <!-- border --> |
| 59 | +  |
| 60 | + |
| 61 | +3. Now you see a screen which is divided into three main parts. On the left you see a list of available preview pages. In the middle the selected preview page is displayed. On the right you get a list of parameters you can change—mainly colors, but also images, fonts, and other values. |
| 62 | + |
| 63 | + <!-- border --> |
| 64 | +  |
| 65 | + |
| 66 | +### Prepare your Preview Page |
| 67 | + |
| 68 | +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. |
| 69 | + |
| 70 | +The theming parameters are accessible through the open-source [theming-base-content](https://www.npmjs.com/package/@sap-theming/theming-base-content), which presents them as [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). For each theme there is a [`css_variables.css`](https://github.com/SAP/theming-base-content/blob/2a38d0156f3d53fde0301b777f8d856266e70d35/content/Base/baseLib/sap_horizon/css_variables.css) file containing all parameter definitions. For the purposes of this tutorial, we will leverage the _unpkg.com_ service and enable the direct referencing of npm packages via URL. |
| 71 | + |
| 72 | +1. Considering a minimal HTML example, you just add the following element: |
| 73 | + ```HTML |
| 74 | + <link rel="stylesheet" href="https://unpkg.com/@sap-theming/theming-base-content/content/Base/baseLib/sap_horizon/css_variables.css"> |
| 75 | + ``` |
| 76 | + As you now loaded the `css_variables.css` in your HTML example you can directly start to use the CSS variables: |
| 77 | + <!-- <body style="background-color: var(--sapBackgroundColor)"></body> --> |
| 78 | + ```CSS |
| 79 | + body { |
| 80 | + background-color: var(--sapBackgroundColor); |
| 81 | + } |
| 82 | + ``` |
| 83 | + |
| 84 | + |
| 85 | +2. 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. |
| 86 | + |
| 87 | + The Post message contains an object with the following structure: |
| 88 | + ```JSON |
| 89 | + { |
| 90 | + "type": "theming-ui:theme-changed", |
| 91 | + "cssVariables": "<ALL CSS VARIABLES WITH CURRENT VALUE AS STRING>" |
| 92 | + } |
| 93 | + ``` |
| 94 | +3. 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. |
| 95 | + |
| 96 | + In order for this to work you add an additional style tag with the id **`cssVariablesStyleTag`**: |
| 97 | + ```html |
| 98 | + <style id="cssVariablesStyleTag"></style> |
| 99 | + ``` |
| 100 | +4. The script part will for example look something like this: |
| 101 | + ```JavaScript |
| 102 | + const cssVariablesStyleTag = document.getElementById('cssVariablesStyleTag'); |
| 103 | + addEventListener('message', ({data}) => { |
| 104 | + if (data.type === 'theming-ui:theme-changed') { |
| 105 | + cssVariablesStyleTag.textContent = data.cssVariables; |
| 106 | + } |
| 107 | + }); |
| 108 | + ``` |
| 109 | +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. |
| 110 | +```JavaScript |
| 111 | +<!doctype html> |
| 112 | +<html> |
| 113 | +<head> |
| 114 | + <title>My Preview Page</title> |
| 115 | + <link rel="stylesheet" href="https://unpkg.com/@sap-theming/theming-base-content/content/Base/baseLib/sap_horizon/css_variables.css"> |
| 116 | + <style id="cssVariablesStyleTag"></style> |
| 117 | + <style>body { background-color: var(--sapBackgroundColor); }</style> |
| 118 | +</head> |
| 119 | +<body> |
| 120 | + <script> |
| 121 | + const cssVariablesStyleTag = document.getElementById('cssVariablesStyleTag'); |
| 122 | + addEventListener('message', ({data}) => { |
| 123 | + if (data.type === 'theming-ui:theme-changed') { |
| 124 | + cssVariablesStyleTag.textContent = data.cssVariables; |
| 125 | + } |
| 126 | + }); |
| 127 | + </script> |
| 128 | +</body> |
| 129 | +</html> |
| 130 | +``` |
| 131 | + |
| 132 | + |
| 133 | + |
| 134 | +### Add Your Preview Page in the UI Theme Designer |
| 135 | + |
| 136 | +In the **UI theme designer** you can select between different builds 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. |
| 137 | + |
| 138 | +1. In the left area click on the ⊕ besides the **Preview Pages**. |
| 139 | +2. Enter the URL of the application you want to use as a preview page |
| 140 | +3. Optionally you can enter a name for the preview page |
| 141 | +4. Press **Add**. |
| 142 | +5. A popup will inform you that your preview page is accessed cross origin. Click **OK**. |
| 143 | +6. Now click on the left area under **Applications** on your new preview page. |
| 144 | + |
| 145 | +Your preview page is now open and you can start customizing. Any modifications made will immediately be reflected on your preview page. |
| 146 | + |
| 147 | +>**Note:** You have to host the application on your own! **The UI theme designer** only loads the content of your application. |
0 commit comments