Skip to content

Commit 2ee9b02

Browse files
kgogovkgogov
authored
feat(framework): Custom Illustrations Documentation & API Enhancement (#12260)
- Rename registerIllustration to unsafeRegisterIllustration with security warnings - Add new registerIllustration API that accepts template functions instead of raw SVG strings - Update IllustratedMessage component to execute templates via executeTemplate() - Add IllustratedMessageTemplate support for both safe (object) and unsafe (string) variants - Update build tool to use unsafeRegisterIllustration for generated illustrations - Add comprehensive documentation for both registration methods - Create playground page demonstrating safe and unsafe approaches with working examples - Export IllustrationData and UnsafeIllustrationData types for better TypeScript support The safe variant (registerIllustration) uses template functions to prevent XSS vulnerabilities, while the unsafe variant (unsafeRegisterIllustration) maintains backward compatibility for raw SVG strings with explicit security warnings. Jira: BGSOFUIPIRIN-6913
1 parent 4cf0976 commit 2ee9b02

File tree

10 files changed

+893
-19
lines changed

10 files changed

+893
-19
lines changed

‎docs/2-advanced/18-using-custom-illustrations.md‎

Lines changed: 317 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,317 @@
1+
# Using Custom Illustrations
2+
3+
*Learn how to create and register custom illustrations for the UI5 Web Components IllustratedMessage component.*
4+
5+
The [`ui5-illustrated-message`](https://ui5.github.io/webcomponents/components/fiori/IllustratedMessage/) component enhances user experience by displaying contextual illustrations in empty states, error conditions, onboarding flows, and other scenarios where visual communication improves usability.
6+
7+
While UI5 Web Components includes a comprehensive set of [built-in illustrations](https://ui5.github.io/webcomponents/components/fiori/enums/IllustrationMessageType/), you can extend this collection by registering your own custom illustrations that match your application's brand and design requirements.
8+
9+
## Overview
10+
11+
Custom illustrations in UI5 Web Components consist of four size variants that automatically adapt to different container dimensions and [design contexts](https://ui5.github.io/webcomponents/components/fiori/enums/IllustrationMessageDesign/):
12+
13+
| Variant | Size | Breakpoint | Container Width | Design Type |
14+
|------------|-------------|------------|-----------------|-------------|
15+
| **Scene** | Large | L | > 681px | Large |
16+
| **Dialog** | Medium | M | ≤ 681px | Medium |
17+
| **Spot** | Small | S | ≤ 360px | Small |
18+
| **Dot** | Extra Small | XS | ≤ 260px | ExtraSmall |
19+
20+
Each custom illustration must include all four variants to ensure optimal display across different use cases and responsive breakpoints.
21+
22+
## Prerequisites
23+
24+
Before implementing custom illustrations, ensure you have installed the required packages:
25+
26+
```bash
27+
npm install @ui5/webcomponents @ui5/webcomponents-fiori
28+
```
29+
30+
The [`@ui5/webcomponents`](https://www.npmjs.com/package/@ui5/webcomponents) package provides the base framework and asset registry functionality, while [`@ui5/webcomponents-fiori`](https://www.npmjs.com/package/@ui5/webcomponents-fiori) contains the `IllustratedMessage` component.
31+
32+
## Custom Illustrations Registration
33+
34+
UI5 Web Components allow developers to register custom illustrations using the `registerIllustration` and `unsafeRegisterIllustration` methods. These methods enable you to add your own illustrations and make them available for use in your application.
35+
36+
### registerIllustration (recommended)
37+
38+
The `registerIllustration` method is the preferred approach, as it includes built-in safety checks to prevent security vulnerabilities. You can register illustrations using JSX templates.
39+
40+
**Note:** JSX templates only work if your project is scaffolded with `npm init @ui5/webcomponents-package`. Otherwise, use `unsafeRegisterIllustration`.
41+
42+
**TypeScript/JSX:**
43+
```tsx
44+
import "@ui5/webcomponents-fiori/dist/IllustratedMessage.js";
45+
import { registerIllustration } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
46+
import type { I18nText } from "@ui5/webcomponents-base/dist/i18nBundle.js";
47+
48+
// Register the illustration with JSX templates
49+
registerIllustration("EmptyCart", {
50+
sceneTemplate: () => (
51+
<svg width="160" height="160" viewBox="0 0 160 160" xmlns="http://www.w3.org/2000/svg">
52+
<path d="M20 30h120l-8 60H28l-8-60z"
53+
stroke="var(--sapContent_Illustrative_Color1)"
54+
stroke-width="2"
55+
fill="var(--sapContent_Illustrative_Color2)" />
56+
</svg>
57+
),
58+
dialogTemplate: () => (
59+
<svg width="120" height="120" viewBox="0 0 120 120" xmlns="http://www.w3.org/2000/svg">
60+
{/* Dialog variant SVG */}
61+
</svg>
62+
),
63+
spotTemplate: () => (
64+
<svg width="80" height="80" viewBox="0 0 80 80" xmlns="http://www.w3.org/2000/svg">
65+
{/* Spot variant SVG */}
66+
</svg>
67+
),
68+
dotTemplate: () => (
69+
<svg width="48" height="48" viewBox="0 0 48 48" xmlns="http://www.w3.org/2000/svg">
70+
{/* Dot variant SVG */}
71+
</svg>
72+
),
73+
title: "Your cart is empty" as I18nText,
74+
subtitle: "Add items to get started with your order" as I18nText,
75+
set: "custom"
76+
});
77+
```
78+
79+
**Parameters:**
80+
81+
- `name`: unique identifier for the illustration
82+
- `illustrationData` (object): illustration configuration containing:
83+
- `sceneTemplate`: template function for the Scene variant (large, > 681px)
84+
- `dialogTemplate`: template function for the Dialog variant (medium, ≤ 681px)
85+
- `spotTemplate`: template function for the Spot variant (small, ≤ 360px)
86+
- `dotTemplate`: template function for the Dot variant (extra small, ≤ 260px)
87+
- `title`: the illustration's title text
88+
- `subtitle`: the illustration's subtitle text
89+
- `set`: unique illustration set identifier (e.g., "custom")
90+
91+
### unsafeRegisterIllustration
92+
93+
The `unsafeRegisterIllustration` method allows you to register raw SVG strings **without sanitization**. Use this only if you trust the SVG source and have validated it yourself, or when JSX templates are not available in your project.
94+
95+
#### Step 1: Prepare SVG Assets
96+
97+
Create four SVG files for each illustration following the naming convention:
98+
```
99+
{set}-{Variant}-{IllustrationName}.js
100+
```
101+
102+
**Example file structure:**
103+
```
104+
assets/
105+
├── custom-Scene-EmptyCart.js # Large variant (> 681px)
106+
├── custom-Dialog-EmptyCart.js # Medium variant (≤ 681px)
107+
├── custom-Spot-EmptyCart.js # Small variant (≤ 360px)
108+
└── custom-Dot-EmptyCart.js # Extra small variant (≤ 260px)
109+
```
110+
111+
Each SVG asset file should export the SVG content as a string:
112+
113+
**custom-Dialog-EmptyCart.js:**
114+
```js
115+
export default `<svg
116+
id="custom-Dialog-EmptyCart"
117+
width="160"
118+
height="120"
119+
viewBox="0 0 160 120"
120+
fill="none"
121+
xmlns="http://www.w3.org/2000/svg"
122+
>
123+
<!-- Cart outline -->
124+
<path
125+
d="M20 30h120l-8 60H28l-8-60z"
126+
stroke="var(--sapContent_Illustrative_Color1)"
127+
stroke-width="2"
128+
fill="var(--sapContent_Illustrative_Color2)"
129+
/>
130+
<!-- Cart handle -->
131+
<path
132+
d="M35 30V20a10 10 0 0 1 20 0v10"
133+
stroke="var(--sapContent_Illustrative_Color3)"
134+
stroke-width="2"
135+
/>
136+
<!-- Empty state indicator -->
137+
<circle
138+
cx="80"
139+
cy="60"
140+
r="15"
141+
fill="var(--sapContent_Illustrative_Color4)"
142+
opacity="0.3"
143+
/>
144+
</svg>`;
145+
```
146+
147+
#### Step 2: Register the Illustration
148+
149+
**JavaScript:**
150+
```js
151+
import "@ui5/webcomponents-fiori/dist/IllustratedMessage.js";
152+
import { unsafeRegisterIllustration } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
153+
154+
// Import SVG assets
155+
import sceneSvg from "./assets/custom-Scene-EmptyCart.js";
156+
import dialogSvg from "./assets/custom-Dialog-EmptyCart.js";
157+
import spotSvg from "./assets/custom-Spot-EmptyCart.js";
158+
import dotSvg from "./assets/custom-Dot-EmptyCart.js";
159+
160+
// Register the illustration
161+
unsafeRegisterIllustration("EmptyCart", {
162+
sceneSvg,
163+
dialogSvg,
164+
spotSvg,
165+
dotSvg,
166+
title: "Your cart is empty",
167+
subtitle: "Add items to get started with your order",
168+
set: "custom"
169+
});
170+
```
171+
172+
**TypeScript:**
173+
```ts
174+
import "@ui5/webcomponents-fiori/dist/IllustratedMessage.js";
175+
import { unsafeRegisterIllustration } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
176+
import type { I18nText } from "@ui5/webcomponents-base/dist/i18nBundle.js";
177+
178+
// Import SVG assets
179+
import sceneSvg from "./assets/custom-Scene-EmptyCart.js";
180+
import dialogSvg from "./assets/custom-Dialog-EmptyCart.js";
181+
import spotSvg from "./assets/custom-Spot-EmptyCart.js";
182+
import dotSvg from "./assets/custom-Dot-EmptyCart.js";
183+
184+
// Register the illustration with proper typing
185+
unsafeRegisterIllustration("EmptyCart", {
186+
sceneSvg,
187+
dialogSvg,
188+
spotSvg,
189+
dotSvg,
190+
title: "Your cart is empty" as I18nText,
191+
subtitle: "Add items to get started with your order" as I18nText,
192+
set: "custom"
193+
});
194+
```
195+
196+
**Parameters:**
197+
198+
- `name`: unique identifier for the illustration
199+
- `illustrationData` (object): illustration configuration containing:
200+
- `sceneSvg`: SVG string for the Scene variant (large, > 681px)
201+
- `dialogSvg`: SVG string for the Dialog variant (medium, ≤ 681px)
202+
- `spotSvg`: SVG string for the Spot variant (small, ≤ 360px)
203+
- `dotSvg`: SVG string for the Dot variant (extra small, ≤ 260px)
204+
- `title`: the illustration's title text
205+
- `subtitle`: the illustration's subtitle text
206+
- `set`: unique illustration set identifier (e.g., "custom")
207+
208+
> **⚠️ Security Warning:**
209+
> The `unsafeRegisterIllustration` method accepts raw SVG strings without sanitization. Only use this function with SVG content that you trust and have validated yourself. Improperly sanitized SVG strings can lead to security vulnerabilities such as XSS (Cross-Site Scripting).
210+
211+
## Design Guidelines
212+
213+
**SVG Requirements:**
214+
- Include a unique `id` attribute: `{set}-{Variant}-{IllustrationName}`
215+
- Use responsive dimensions appropriate for each variant
216+
- All four size variants must be provided for optimal display
217+
218+
**Theming Support:**
219+
- Use CSS custom properties for colors (e.g., `var(--sapContent_Illustrative_Color1)`)
220+
- Avoid hard-coded colors to ensure theme compatibility
221+
- Test illustrations across different UI5 themes
222+
223+
**Security Compliance** (for `unsafeRegisterIllustration`):
224+
225+
- ⚠️ **No inline JavaScript**: Avoid `<script>` tags or event handlers (`onclick`, `onload`, etc.)
226+
- ⚠️ **No unsafe styles**: Avoid `style` attributes that violate CSP policies
227+
- ⚠️ **Validate SVG content**: Only use SVG files from trusted sources that you have reviewed
228+
- ⚠️ **XSS Risk**: Malicious SVG content can execute arbitrary JavaScript and compromise your application
229+
- ✅ **Use CSS custom properties**: Prefer theme-aware styling
230+
- ✅ **Test with strict CSP**: Validate in CSP-enabled environments
231+
- ✅ **Static SVG only**: Use declarative SVG markup without dynamic or executable content
232+
233+
## Usage
234+
235+
Once registered, custom illustrations can be used just like any other UI5 Web Components illustration by referencing them with the format `{set}/{name}`:
236+
237+
**HTML:**
238+
```html
239+
<ui5-illustrated-message name="custom/EmptyCart">
240+
<ui5-button design="Emphasized">Start Shopping</ui5-button>
241+
</ui5-illustrated-message>
242+
```
243+
244+
**React:**
245+
```jsx
246+
import { Button, IllustratedMessage } from '@ui5/webcomponents-react';
247+
248+
function EmptyCartView() {
249+
return (
250+
<IllustratedMessage name="custom/EmptyCart">
251+
<Button design="Emphasized">Start Shopping</Button>
252+
</IllustratedMessage>
253+
);
254+
}
255+
```
256+
257+
## Configuration
258+
259+
### Design Size
260+
261+
Control illustration size and behavior using the [`design`](https://ui5.github.io/webcomponents/components/fiori/IllustratedMessage/#design) property:
262+
263+
```html
264+
<!-- Auto-responsive (default) -->
265+
<ui5-illustrated-message name="custom/EmptyCart" design="Auto">
266+
<ui5-button>Add Items</ui5-button>
267+
</ui5-illustrated-message>
268+
269+
<!-- Fixed size -->
270+
<ui5-illustrated-message name="custom/EmptyCart" design="Large">
271+
<ui5-button>Add Items</ui5-button>
272+
</ui5-illustrated-message>
273+
```
274+
275+
### Override Title and Subtitle
276+
277+
You can override the default title and subtitle texts defined during registration using the [`title-text`](https://ui5.github.io/webcomponents/components/fiori/IllustratedMessage/#title-text) and [`subtitle-text`](https://ui5.github.io/webcomponents/components/fiori/IllustratedMessage/#subtitle-text) properties:
278+
279+
```html
280+
<ui5-illustrated-message
281+
name="custom/EmptyCart"
282+
title-text="Your Shopping Cart is Empty"
283+
subtitle-text="Browse our products and add items to your cart">
284+
<ui5-button design="Emphasized">Start Shopping</ui5-button>
285+
</ui5-illustrated-message>
286+
```
287+
288+
**React:**
289+
```jsx
290+
<IllustratedMessage
291+
name="custom/EmptyCart"
292+
titleText="Your Shopping Cart is Empty"
293+
subtitleText="Browse our products and add items to your cart">
294+
<Button design="Emphasized">Start Shopping</Button>
295+
</IllustratedMessage>
296+
```
297+
298+
## Accessibility
299+
300+
For accessibility considerations, use the [`decorative`](https://ui5.github.io/webcomponents/components/fiori/IllustratedMessage/#decorative) property when appropriate:
301+
302+
```html
303+
<!-- Decorative illustrations (no accessibility labels) -->
304+
<ui5-illustrated-message name="custom/EmptyCart" decorative>
305+
<ui5-button>Add Items</ui5-button>
306+
</ui5-illustrated-message>
307+
```
308+
309+
**Note:** Use the `decorative` property when the illustration is purely visual and doesn't convey important information. This improves accessibility by preventing screen readers from announcing decorative content.
310+
311+
## Best Practices
312+
313+
- **Consistent Design Language**: Maintain visual consistency with your application's design system
314+
- **Meaningful Illustrations**: Create illustrations that clearly communicate the intended message
315+
- **Performance**: Optimize SVG file sizes while maintaining quality
316+
- **Accessibility**: Ensure illustrations support users with visual impairments through proper titles and descriptions
317+
- **Testing**: Validate illustrations across different themes, screen sizes, and browsers

0 commit comments

Comments
 (0)