@endora-commerce/mod-cms 0.101.1 → 0.103.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/admin/components/AdminCmsAssetProvider.d.ts +1 -1
- package/dist/admin/components/AdminCmsAssetProvider.d.ts.map +1 -1
- package/dist/admin/components/BackgroundFields.d.ts +1 -1
- package/dist/admin/components/BackgroundFields.d.ts.map +1 -1
- package/dist/admin/components/BackgroundFields.js +1 -1
- package/dist/admin/components/BackgroundFields.js.map +1 -1
- package/dist/admin/components/ButtonLinkFields.d.ts +1 -1
- package/dist/admin/components/ButtonLinkFields.d.ts.map +1 -1
- package/dist/admin/components/CarouselPreviewNav.js +1 -1
- package/dist/admin/components/CarouselPreviewNav.js.map +1 -1
- package/dist/admin/components/ComponentDragHandle.js +1 -1
- package/dist/admin/components/ComponentDragHandle.js.map +1 -1
- package/dist/admin/components/ContentSliderActionBarExtras.js +1 -1
- package/dist/admin/components/ContentSliderActionBarExtras.js.map +1 -1
- package/dist/admin/components/PageBuilderActionBar.js +1 -1
- package/dist/admin/components/PageBuilderActionBar.js.map +1 -1
- package/dist/admin/components/PageBuilderEditor.d.ts +2 -2
- package/dist/admin/components/PageBuilderEditor.d.ts.map +1 -1
- package/dist/admin/components/PageBuilderEditor.js +91 -44
- package/dist/admin/components/PageBuilderEditor.js.map +1 -1
- package/dist/admin/components/PuckActionGuard.d.ts +1 -1
- package/dist/admin/components/PuckActionGuard.d.ts.map +1 -1
- package/dist/admin/components/block-contributions.d.ts +74 -0
- package/dist/admin/components/block-contributions.d.ts.map +1 -0
- package/dist/admin/components/block-contributions.js +94 -0
- package/dist/admin/components/block-contributions.js.map +1 -0
- package/dist/admin/components/cms-template-layout.d.ts +1 -1
- package/dist/admin/components/cms-template-layout.d.ts.map +1 -1
- package/dist/admin/components/page-builder-i18n.d.ts +1 -1
- package/dist/admin/components/page-builder-i18n.d.ts.map +1 -1
- package/dist/admin/components/puck-safe.d.ts +1 -1
- package/dist/admin/components/puck-safe.d.ts.map +1 -1
- package/dist/admin-ui/index.d.ts +1 -1
- package/dist/admin-ui/index.js +1 -1
- package/dist/backend/index.d.ts +3 -0
- package/dist/backend/index.d.ts.map +1 -1
- package/dist/backend/index.js +2 -1
- package/dist/backend/index.js.map +1 -1
- package/dist/backend/plugin.d.ts +7 -0
- package/dist/backend/plugin.d.ts.map +1 -1
- package/dist/backend/plugin.js +1 -1
- package/dist/backend/plugin.js.map +1 -1
- package/dist/backend/services/cms-page-service.d.ts +36 -1
- package/dist/backend/services/cms-page-service.d.ts.map +1 -1
- package/dist/backend/services/cms-page-service.js +231 -114
- package/dist/backend/services/cms-page-service.js.map +1 -1
- package/dist/manifest.d.ts +2 -2
- package/docs/cms/extending-page-builder.md +579 -120
- package/docs/cms/index.md +6 -7
- package/i18n/en.json +1 -0
- package/i18n/pl.json +1 -0
- package/package.json +16 -16
|
@@ -7,151 +7,609 @@ sidebar_position: 2
|
|
|
7
7
|
|
|
8
8
|
The CMS module ships built-in components — `Row`, `Columns`, `Text`,
|
|
9
9
|
`Heading`, `Button`, `InsertBlock`, and others — but every other
|
|
10
|
-
backend module can contribute its own components
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
10
|
+
backend module can contribute its own components. (`InsertTemplate` remains
|
|
11
|
+
registered for legacy content trees but is no longer listed in the drawer
|
|
12
|
+
palette.) The `cms`, `catalog`, `orders`, `invoices` and `transactional_emails`
|
|
13
|
+
modules already declare their blocks this way. Their renderers are still the
|
|
14
|
+
built-in ones in `@endora-commerce/cms-components` and
|
|
15
|
+
`@endora-commerce/email-components`; a module package outside the platform
|
|
16
|
+
ships its own, as section 2 describes. A contributing module participates in
|
|
17
|
+
two places:
|
|
18
|
+
|
|
19
|
+
1. **Manifest declaration**: declare the block's metadata — name, labels,
|
|
20
|
+
palette category, contexts and editable fields — in the module's own
|
|
21
|
+
`manifest.ts`. The CMS module builds its Page Builder registry from the
|
|
22
|
+
manifests of the composed modules, so there is no registration call to
|
|
23
|
+
write.
|
|
24
|
+
2. **Renderers**: ship, in the module's own package, the code that draws the
|
|
25
|
+
block on the storefront, in e-mail and in the admin editors.
|
|
26
|
+
|
|
27
|
+
## 1. Declare the block in the manifest
|
|
28
|
+
|
|
29
|
+
Add `blocks` and `blockCategories` to your module manifest:
|
|
28
30
|
|
|
29
31
|
```ts
|
|
30
|
-
// the promotions module: src/
|
|
31
|
-
import
|
|
32
|
-
|
|
33
|
-
export
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
32
|
+
// the promotions module: src/manifest.ts
|
|
33
|
+
import { defineModuleManifest } from '@endora-commerce/contracts';
|
|
34
|
+
|
|
35
|
+
export const manifest = defineModuleManifest({
|
|
36
|
+
id: 'promotions',
|
|
37
|
+
// ...name, version, dependencies...
|
|
38
|
+
blocks: [
|
|
39
|
+
{
|
|
40
|
+
name: 'promotions.PromoBanner',
|
|
41
|
+
labelKey: 'blocks.promoBanner.label',
|
|
42
|
+
descriptionKey: 'blocks.promoBanner.description',
|
|
43
|
+
category: 'promotions',
|
|
44
|
+
/** Omit email/invoice — this component is storefront-only. */
|
|
45
|
+
contexts: ['cms'],
|
|
46
|
+
fields: {
|
|
47
|
+
headline: { type: 'text', label: 'Headline', required: true },
|
|
48
|
+
codeInput: { type: 'text', label: 'Promo code' },
|
|
49
|
+
tone: {
|
|
50
|
+
type: 'select',
|
|
51
|
+
label: 'Tone',
|
|
52
|
+
options: [
|
|
53
|
+
{ label: 'Info', value: 'info' },
|
|
54
|
+
{ label: 'Urgent', value: 'urgent' },
|
|
55
|
+
],
|
|
50
56
|
},
|
|
51
|
-
previewIcon: 'ticket',
|
|
52
|
-
/** Omit email/invoice — this component is storefront-only. */
|
|
53
|
-
contexts: ['cms'],
|
|
54
57
|
},
|
|
58
|
+
previewIcon: 'ticket',
|
|
59
|
+
weight: 10,
|
|
55
60
|
},
|
|
56
|
-
|
|
57
|
-
|
|
61
|
+
],
|
|
62
|
+
blockCategories: [
|
|
63
|
+
{ key: 'promotions', titleKey: 'blocks.category.promotions', contexts: ['cms'] },
|
|
64
|
+
],
|
|
65
|
+
});
|
|
58
66
|
```
|
|
59
67
|
|
|
68
|
+
The schema is `BlockDefinitionSchema` and `BlockCategorySchema` in
|
|
69
|
+
`packages/contracts/src/cms.ts` (both exported from
|
|
70
|
+
`@endora-commerce/contracts`). `defineModuleManifest` refuses a manifest
|
|
71
|
+
that breaks either of two rules:
|
|
72
|
+
|
|
73
|
+
- A block `name` is `<module id>.<PascalCaseName>`, and the part before the
|
|
74
|
+
dot must be the declaring module's own `id`. The name is written into the
|
|
75
|
+
stored page content and never rewritten, so choose it once.
|
|
76
|
+
- A block's `category` must be declared in the same manifest's
|
|
77
|
+
`blockCategories` for every context the block lists. Several modules may
|
|
78
|
+
declare the same category key; the palette merges them.
|
|
79
|
+
|
|
80
|
+
`labelKey`, `descriptionKey` and `titleKey` are relative to the declaring
|
|
81
|
+
module's own i18n bundle (`blocks.promoBanner.label`, not
|
|
82
|
+
`promotions.blocks.promoBanner.label`). Nothing can check that when the
|
|
83
|
+
manifest is defined, so get it right by hand.
|
|
84
|
+
|
|
60
85
|
Field types are taken from the closed enum declared in
|
|
61
86
|
`packages/contracts/src/cms.ts`: `text | textarea | number | select |
|
|
62
87
|
radio | array | object | external | uuid | richtext`. This metadata is
|
|
63
88
|
React-free; the backend never imports a renderer.
|
|
64
89
|
|
|
65
|
-
|
|
90
|
+
A block is offered only while its module is present: the registry filters
|
|
91
|
+
declarations by module presence when it answers
|
|
92
|
+
`GET /api/v1/admin/cms/page-builder/config`, so a module that is switched off
|
|
93
|
+
takes its blocks out of the palette with it.
|
|
94
|
+
|
|
95
|
+
## 2. Ship the renderers
|
|
96
|
+
|
|
97
|
+
A module package draws its own blocks. It does so through up to three
|
|
98
|
+
**layers**, one per process that renders a block, plus an optional stylesheet.
|
|
99
|
+
Each is a subpath of the package's `exports` map, and each is optional: a
|
|
100
|
+
module whose blocks are e-mail-only ships the e-mail layer and nothing else.
|
|
101
|
+
|
|
102
|
+
| Subpath | What it exports | Who renders with it |
|
|
103
|
+
| --- | --- | --- |
|
|
104
|
+
| `./storefront` | `contributions` — React renderers for the module's `cms` blocks | the storefront, in the server-rendered HTML |
|
|
105
|
+
| `./email` | `emailBlocks` — pure functions that render the module's `email` blocks to HTML and text | the backend when it sends, and the admin's e-mail editor |
|
|
106
|
+
| `./admin` | `contributions.blocks` — editor renderers, beside the module's routes and zones | the admin's CMS and e-mail editors |
|
|
107
|
+
| `./blocks.css` | one finished stylesheet | the storefront and the admin editor |
|
|
108
|
+
|
|
109
|
+
This is for a module **package** — one a storefront and an instance install
|
|
110
|
+
from a registry. The platform's own modules do not ship these layers yet: their
|
|
111
|
+
`package.json` is generated, and the generator does not render the three
|
|
112
|
+
subpaths. An overlay module has no package; its blocks are covered under
|
|
113
|
+
[A block no package renders](#a-block-no-package-renders).
|
|
114
|
+
|
|
115
|
+
The examples below quote the platform's own acceptance fixture: a module
|
|
116
|
+
outside every platform package that ships all three layers and a stylesheet
|
|
117
|
+
for one block, `acceptance_blocks.Badge`.
|
|
118
|
+
|
|
119
|
+
### The package
|
|
120
|
+
|
|
121
|
+
A surface finds the package by its own `package.json`:
|
|
122
|
+
|
|
123
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/package.json -->
|
|
124
|
+
```json
|
|
125
|
+
"files": [
|
|
126
|
+
"dist",
|
|
127
|
+
"i18n",
|
|
128
|
+
"blocks.css",
|
|
129
|
+
"tailwind.css"
|
|
130
|
+
],
|
|
131
|
+
"endora": {
|
|
132
|
+
"type": "module",
|
|
133
|
+
"id": "acceptance_blocks"
|
|
134
|
+
},
|
|
135
|
+
"exports": {
|
|
136
|
+
".": {
|
|
137
|
+
"types": "./dist/manifest.d.ts",
|
|
138
|
+
"default": "./dist/manifest.js"
|
|
139
|
+
},
|
|
140
|
+
"./backend": {
|
|
141
|
+
"types": "./dist/backend/index.d.ts",
|
|
142
|
+
"default": "./dist/backend/index.js"
|
|
143
|
+
},
|
|
144
|
+
"./admin": {
|
|
145
|
+
"types": "./dist/admin/index.d.ts",
|
|
146
|
+
"default": "./dist/admin/index.js"
|
|
147
|
+
},
|
|
148
|
+
"./storefront": {
|
|
149
|
+
"types": "./dist/storefront/index.d.ts",
|
|
150
|
+
"default": "./dist/storefront/index.js"
|
|
151
|
+
},
|
|
152
|
+
"./email": {
|
|
153
|
+
"types": "./dist/email/index.d.ts",
|
|
154
|
+
"default": "./dist/email/index.js"
|
|
155
|
+
},
|
|
156
|
+
"./blocks.css": "./blocks.css",
|
|
157
|
+
"./tailwind.css": "./tailwind.css",
|
|
158
|
+
"./i18n/*": "./i18n/*",
|
|
159
|
+
"./package.json": "./package.json"
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
- **`endora.type` must be `module`, and `endora.id` the module id** that
|
|
163
|
+
prefixes its block names. A package without that block is not a module
|
|
164
|
+
package: `blocks:generate` says so in a note and registers nothing from it,
|
|
165
|
+
and its blocks render as placeholders.
|
|
166
|
+
- **`files` lists everything an `exports` entry points at** — `blocks.css` and
|
|
167
|
+
`tailwind.css` beside `dist`. An entry whose file is not in the tarball is
|
|
168
|
+
refused by the generator that would import it.
|
|
169
|
+
- **Each layer publishes type declarations** beside its JavaScript (the `types`
|
|
170
|
+
condition above). A storefront written in TypeScript imports `./storefront`
|
|
171
|
+
from its generated registry, and `blocks:generate` refuses a storefront layer
|
|
172
|
+
that ships none as `untyped-layer`.
|
|
173
|
+
- **A package with `./admin` also publishes `./tailwind.css`**, which tells the
|
|
174
|
+
admin's Tailwind build where the layer is. `endora generate` refuses an admin
|
|
175
|
+
layer without it. The fixture's is one line, quoted below the list.
|
|
176
|
+
- **The layers' imports are peer dependencies**: `@endora-commerce/contracts`,
|
|
177
|
+
`@endora-commerce/page-builder-core`, `@endora-commerce/email-components`,
|
|
178
|
+
`@puckeditor/core` and `react`, with `@endora-commerce/platform` for the
|
|
179
|
+
backend.
|
|
180
|
+
- **The build is plain `tsc`**, which keeps a leading `'use client'` and emits
|
|
181
|
+
the declarations. Relative imports are written with the `.js` extension.
|
|
182
|
+
|
|
183
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/tailwind.css -->
|
|
184
|
+
```css
|
|
185
|
+
@source "./dist/admin";
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Where the names in the examples come from:
|
|
189
|
+
|
|
190
|
+
| Name | Import it from |
|
|
191
|
+
| --- | --- |
|
|
192
|
+
| `StorefrontContributions`, `PageBuilderBlockEditorConfig`, `useBlockRenderEnvironment` | `@endora-commerce/page-builder-core/contributions` |
|
|
193
|
+
| `sanitizeRichHtml` | `@endora-commerce/cms-components` |
|
|
194
|
+
| `EmailBlockRenderers` | `@endora-commerce/email-components/render/block-renderers` |
|
|
195
|
+
| `escapeHtml`, `escapeAttr` | `@endora-commerce/email-components/render/escape-html` |
|
|
196
|
+
| `AdminContributions`, `EmailBlockRendererRegistryPort` | `@endora-commerce/contracts` |
|
|
197
|
+
| `ModuleContext`, `lazyPort` | `@endora-commerce/platform/kernel` |
|
|
198
|
+
|
|
199
|
+
### The declaration the layers draw
|
|
200
|
+
|
|
201
|
+
The block is declared in the module's manifest, for both contexts it is drawn
|
|
202
|
+
in, in a palette section the same manifest declares for both:
|
|
203
|
+
|
|
204
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/manifest.ts -->
|
|
205
|
+
```ts
|
|
206
|
+
blockCategories: [
|
|
207
|
+
{ key: 'acceptance', titleKey: 'blocks.section', contexts: ['cms', 'email'], weight: 900 },
|
|
208
|
+
],
|
|
209
|
+
blocks: [
|
|
210
|
+
{
|
|
211
|
+
// The persisted name — `<endora.id>.<Name>`, and permanent. Written as a
|
|
212
|
+
// literal: `endora check` reads a block's name and contexts off the
|
|
213
|
+
// manifest's text, and a name it cannot read is one it cannot hold a
|
|
214
|
+
// renderer to.
|
|
215
|
+
name: 'acceptance_blocks.Badge',
|
|
216
|
+
labelKey: 'blocks.badge.label',
|
|
217
|
+
descriptionKey: 'blocks.badge.description',
|
|
218
|
+
category: 'acceptance',
|
|
219
|
+
contexts: ['cms', 'email'],
|
|
220
|
+
fields: {
|
|
221
|
+
text: { type: 'text', label: 'Text' },
|
|
222
|
+
// Forces every renderer of this block to throw. It exists for the
|
|
223
|
+
// failure-isolation assertion and for nothing an operator would use.
|
|
224
|
+
explode: {
|
|
225
|
+
type: 'radio',
|
|
226
|
+
label: 'Fail on render',
|
|
227
|
+
options: [
|
|
228
|
+
{ label: 'No', value: 'no' },
|
|
229
|
+
{ label: 'Yes', value: 'yes' },
|
|
230
|
+
],
|
|
231
|
+
},
|
|
232
|
+
},
|
|
233
|
+
defaultProps: { text: 'New badge', explode: 'no' },
|
|
234
|
+
weight: 10,
|
|
235
|
+
},
|
|
236
|
+
],
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
Every renderer is keyed by the block's full name, and a package renders only
|
|
240
|
+
the blocks **its own manifest declares**, for a context that block declares:
|
|
241
|
+
`cms` for the storefront and the CMS editor, `email` for e-mail. Write the name
|
|
242
|
+
and the contexts as literals, in the manifest and in each layer:
|
|
243
|
+
`check:block-renderers` reads them off the source text, and a name it cannot
|
|
244
|
+
read is one it cannot hold a renderer to. A computed renderer key escapes the
|
|
245
|
+
check and is refused when the surface composes it.
|
|
246
|
+
|
|
247
|
+
### The storefront layer
|
|
248
|
+
|
|
249
|
+
`src/storefront/index.ts` exports `contributions`, a map from block name to a
|
|
250
|
+
Puck component config:
|
|
251
|
+
|
|
252
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/storefront/index.ts -->
|
|
253
|
+
```ts
|
|
254
|
+
import type { StorefrontContributions } from '@endora-commerce/page-builder-core/contributions';
|
|
255
|
+
|
|
256
|
+
import { Badge } from './Badge.js';
|
|
257
|
+
|
|
258
|
+
export const contributions: StorefrontContributions = {
|
|
259
|
+
blocks: {
|
|
260
|
+
'acceptance_blocks.Badge': {
|
|
261
|
+
defaultProps: { text: 'New badge', explode: 'no' },
|
|
262
|
+
render: Badge,
|
|
263
|
+
},
|
|
264
|
+
},
|
|
265
|
+
};
|
|
266
|
+
```
|
|
66
267
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
268
|
+
The renderer is an ordinary React component. Its props are the block's stored
|
|
269
|
+
props, with the `defaultProps` above filled in underneath them — so a prop the
|
|
270
|
+
module added after a page was saved still has a value:
|
|
70
271
|
|
|
272
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/storefront/Badge.tsx -->
|
|
71
273
|
```tsx
|
|
72
|
-
|
|
73
|
-
|
|
274
|
+
'use client';
|
|
275
|
+
|
|
276
|
+
import { useBlockRenderEnvironment } from '@endora-commerce/page-builder-core/contributions';
|
|
277
|
+
import type { ReactNode } from 'react';
|
|
74
278
|
|
|
75
|
-
interface
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
tone: 'info' | 'urgent';
|
|
279
|
+
export interface BadgeProps {
|
|
280
|
+
readonly text?: string;
|
|
281
|
+
readonly explode?: string | boolean;
|
|
79
282
|
}
|
|
80
283
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
284
|
+
/**
|
|
285
|
+
* The renderer's one built-in string — a label that is not operator content —
|
|
286
|
+
* shipped in both languages inside the layer and chosen by the request's
|
|
287
|
+
* content language, with English as the fallback. The storefront's own
|
|
288
|
+
* catalogue belongs to the storefront's owner.
|
|
289
|
+
*/
|
|
290
|
+
const LABEL: Readonly<Record<string, string>> = { en: 'Badge', pl: 'Odznaka' };
|
|
291
|
+
|
|
292
|
+
/**
|
|
293
|
+
* Synchronous, reads no browser global, and draws the same output on the
|
|
294
|
+
* server and on hydration for the same props: it is part of the
|
|
295
|
+
* server-rendered HTML.
|
|
296
|
+
*/
|
|
297
|
+
export function Badge({ text, explode }: BadgeProps): ReactNode {
|
|
298
|
+
const { language } = useBlockRenderEnvironment();
|
|
299
|
+
if (explode === true || explode === 'yes') {
|
|
300
|
+
throw new Error('acceptance_blocks.Badge was asked to fail on render');
|
|
301
|
+
}
|
|
302
|
+
const label = LABEL[language.slice(0, 2).toLowerCase()] ?? LABEL['en'];
|
|
303
|
+
return (
|
|
304
|
+
<span className="acceptance_blocks-badge" title={label}>
|
|
305
|
+
{`acceptance-badge:${String(text ?? '')}`}
|
|
306
|
+
</span>
|
|
307
|
+
);
|
|
308
|
+
}
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
A storefront renderer runs once on the server and once in the browser, so:
|
|
312
|
+
|
|
313
|
+
- it is **synchronous** — no `async` component — and reads no browser global
|
|
314
|
+
(`window`, `document`, `localStorage`) while rendering, only in an effect;
|
|
315
|
+
- it draws the same output on the server and in the browser for the same
|
|
316
|
+
props: no `Date.now()`, no `Math.random()`, no locale-dependent formatting
|
|
317
|
+
without the language from `useBlockRenderEnvironment()`;
|
|
318
|
+
- every file of the layer starts with `'use client'`. `check:block-renderers`
|
|
319
|
+
does not hold this one; a layer without it fails the storefront's build;
|
|
320
|
+
- it imports only `react`, `react-dom`, `@puckeditor/core`,
|
|
321
|
+
`@endora-commerce/page-builder-core`, `@endora-commerce/cms-components`,
|
|
322
|
+
`@endora-commerce/contracts` and its own files. Nothing server-only, no
|
|
323
|
+
admin kit, no platform, no other module. Data it needs comes from its props,
|
|
324
|
+
from the CMS render context, or from a fetch in an effect;
|
|
325
|
+
- block props are **untrusted input**: HTML is injected only as
|
|
326
|
+
`dangerouslySetInnerHTML={{ __html: sanitizeRichHtml(value) }}`;
|
|
327
|
+
- a label the renderer prints itself — one that is not the operator's content —
|
|
328
|
+
ships in English and Polish inside the layer and is chosen by
|
|
329
|
+
`useBlockRenderEnvironment().language`, with English as the fallback.
|
|
330
|
+
|
|
331
|
+
**Installing it in a storefront.** A storefront owner adds the package to
|
|
332
|
+
their storefront (`pnpm add`) and builds. `blocks:generate`, which the
|
|
333
|
+
storefront's `dev` and `build` scripts run, finds every installed module
|
|
334
|
+
package that declares `./storefront` or `./blocks.css` and writes the registry
|
|
335
|
+
and the stylesheet import — there is no line to add to any file.
|
|
336
|
+
|
|
337
|
+
When `endora install` writes an instance and a storefront in one run, it adds
|
|
338
|
+
the instance's modules that publish a storefront layer to the storefront's
|
|
339
|
+
dependencies, once. No platform module publishes one yet, so a default install
|
|
340
|
+
adds nothing; a package added to the instance afterwards is added to the
|
|
341
|
+
storefront by its owner.
|
|
342
|
+
|
|
343
|
+
What `blocks:generate` refuses, writing nothing and exiting 1:
|
|
344
|
+
|
|
345
|
+
| Refusal | Meaning |
|
|
346
|
+
| --- | --- |
|
|
347
|
+
| `untyped-layer` | the package publishes `./storefront` with no type declarations |
|
|
348
|
+
| `missing-layer-file` | an `exports` entry points at a file the package does not hold |
|
|
349
|
+
| `layer-without-subpath` | the package ships `src/storefront/index.ts` and declares no `./storefront` |
|
|
350
|
+
| `duplicate-module` | two installed packages declare the same module id |
|
|
351
|
+
|
|
352
|
+
#### A block no package renders
|
|
353
|
+
|
|
354
|
+
A storefront can also render a block itself — typically one an overlay module
|
|
355
|
+
of its own instance declares — by adding it to
|
|
356
|
+
`lib/page-builder/local-blocks.tsx`, the one file of the block registry that is
|
|
357
|
+
the storefront owner's. A local block never replaces a block a package or the
|
|
358
|
+
platform already renders.
|
|
359
|
+
|
|
360
|
+
### The e-mail layer
|
|
361
|
+
|
|
362
|
+
`src/email/index.ts` exports `emailBlocks`. Each renderer is a pure function —
|
|
363
|
+
no React, no I/O — that returns rows of the e-mail's table layout and escapes
|
|
364
|
+
every prop:
|
|
365
|
+
|
|
366
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/email/index.ts -->
|
|
367
|
+
```ts
|
|
368
|
+
import type { EmailBlockRenderers } from '@endora-commerce/email-components/render/block-renderers';
|
|
369
|
+
import { escapeHtml } from '@endora-commerce/email-components/render/escape-html';
|
|
370
|
+
|
|
371
|
+
interface BadgeProps {
|
|
372
|
+
readonly text?: string;
|
|
373
|
+
readonly explode?: string | boolean;
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
function assertRenderable(props: BadgeProps): void {
|
|
377
|
+
if (props.explode === true || props.explode === 'yes') {
|
|
378
|
+
throw new Error('acceptance_blocks.Badge was asked to fail on render');
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
export const emailBlocks: EmailBlockRenderers = {
|
|
383
|
+
'acceptance_blocks.Badge': {
|
|
384
|
+
defaultProps: { text: 'New badge' },
|
|
385
|
+
html: (props: BadgeProps, ctx) => {
|
|
386
|
+
assertRenderable(props);
|
|
387
|
+
return (
|
|
388
|
+
'<tr><td style="padding:8px 24px;font-family:Arial,Helvetica,sans-serif;">' +
|
|
389
|
+
`<span style="display:inline-block;padding:4px 10px;border-radius:6px;background-color:${ctx.accentColor};color:#ffffff;font-size:14px;font-weight:bold;">` +
|
|
390
|
+
`acceptance-badge:${escapeHtml(String(props.text ?? ''))}` +
|
|
391
|
+
'</span></td></tr>'
|
|
392
|
+
);
|
|
393
|
+
},
|
|
394
|
+
text: (props: BadgeProps) => {
|
|
395
|
+
assertRenderable(props);
|
|
396
|
+
return `acceptance-badge:${String(props.text ?? '')}\n`;
|
|
397
|
+
},
|
|
89
398
|
},
|
|
90
|
-
defaultProps: { headline: 'Spring sale', tone: 'info' },
|
|
91
|
-
contexts: ['cms'],
|
|
92
|
-
render: ({ headline, codeInput, tone }) => (
|
|
93
|
-
<div className={`promo-banner promo-${tone}`}>
|
|
94
|
-
<strong>{headline}</strong>
|
|
95
|
-
{codeInput ? <code>{codeInput}</code> : null}
|
|
96
|
-
</div>
|
|
97
|
-
),
|
|
98
399
|
};
|
|
99
400
|
```
|
|
100
401
|
|
|
101
|
-
|
|
102
|
-
|
|
402
|
+
`text` is optional; without it the plain-text part is derived from the HTML.
|
|
403
|
+
The second argument carries `accentColor`, the message's `language` — a label
|
|
404
|
+
the renderer prints itself follows it, as on the storefront — and
|
|
405
|
+
`renderSlot(nodes)`, which renders nested content with the platform's own
|
|
406
|
+
renderer. `{{var …}}` directives in the output are resolved afterwards,
|
|
407
|
+
exactly as in a built-in block. The layer imports only
|
|
408
|
+
`@endora-commerce/email-components/render/*`, `@endora-commerce/contracts` and
|
|
409
|
+
its own files, because the same function runs in the backend and in the
|
|
410
|
+
admin's browser.
|
|
411
|
+
|
|
412
|
+
The module's backend registers the renderers when the platform boots, and its
|
|
413
|
+
manifest names `email` in `dependencies`:
|
|
103
414
|
|
|
415
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/manifest.ts -->
|
|
104
416
|
```ts
|
|
105
|
-
//
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
417
|
+
// `email` owns the registry this module registers its e-mail renderer into.
|
|
418
|
+
// It is non-deactivatable, so the edge never fails closed.
|
|
419
|
+
dependencies: ['email'],
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/backend/index.ts -->
|
|
423
|
+
```ts
|
|
424
|
+
import type { EmailBlockRendererRegistryPort } from '@endora-commerce/contracts';
|
|
425
|
+
import { lazyPort, type ModuleContext } from '@endora-commerce/platform/kernel';
|
|
426
|
+
|
|
427
|
+
import { emailBlocks } from '../email/index.js';
|
|
428
|
+
|
|
429
|
+
/** This module persists nothing. */
|
|
430
|
+
export const entities = [] as const;
|
|
431
|
+
|
|
432
|
+
export function registerModule(ctx: ModuleContext): void {
|
|
433
|
+
// From a boot hook, unprobed: the registry is ungated and decides presence
|
|
434
|
+
// itself, per render, on the contributor recorded here — so switching this
|
|
435
|
+
// module off, or back on, needs no restart and no re-registration.
|
|
436
|
+
ctx.onBoot(() => {
|
|
437
|
+
lazyPort<EmailBlockRendererRegistryPort>(ctx, 'emailBlockRendererRegistry').register(
|
|
438
|
+
'acceptance_blocks',
|
|
439
|
+
emailBlocks,
|
|
440
|
+
);
|
|
441
|
+
});
|
|
442
|
+
}
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
`register` never throws. A name the module does not own, or an entry without an
|
|
446
|
+
`html` function, is refused with a warning in the backend log and listed in the
|
|
447
|
+
`refused` array the call returns — assert on that array in a test.
|
|
448
|
+
|
|
449
|
+
Transactional e-mail and newsletter campaigns both render through that
|
|
450
|
+
registry, and content holding the block can be saved in either. A built-in
|
|
451
|
+
e-mail block cannot be overridden: a contributed renderer is consulted only for
|
|
452
|
+
a name the platform does not draw itself.
|
|
453
|
+
|
|
454
|
+
### The admin layer
|
|
455
|
+
|
|
456
|
+
The module's `./admin` layer — the one that already declares its routes and
|
|
457
|
+
zone contributions — lists an editor renderer per block and editor:
|
|
458
|
+
|
|
459
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/admin/index.ts -->
|
|
460
|
+
```ts
|
|
461
|
+
import type { AdminContributions } from '@endora-commerce/contracts';
|
|
462
|
+
|
|
463
|
+
export const contributions: AdminContributions = {
|
|
464
|
+
blocks: [
|
|
465
|
+
{
|
|
466
|
+
name: 'acceptance_blocks.Badge',
|
|
467
|
+
context: 'cms',
|
|
468
|
+
component: () => import('./badge-editor.js'),
|
|
469
|
+
},
|
|
470
|
+
{
|
|
471
|
+
name: 'acceptance_blocks.Badge',
|
|
472
|
+
context: 'email',
|
|
473
|
+
component: () => import('./badge-email.js'),
|
|
474
|
+
},
|
|
475
|
+
],
|
|
122
476
|
};
|
|
123
477
|
```
|
|
124
478
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
substitutes a `MissingComponentPlaceholder` for any component the
|
|
128
|
-
descriptor names but the bundle does not export. The placeholder renders
|
|
129
|
-
nothing on the storefront unless the page is loaded with the
|
|
130
|
-
`?cms_admin=1` query parameter (preview mode).
|
|
479
|
+
For the CMS editor the default export is the block's renderer — usually the
|
|
480
|
+
storefront's own component, so the canvas shows what the storefront draws:
|
|
131
481
|
|
|
132
|
-
|
|
482
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/admin/badge-editor.tsx -->
|
|
483
|
+
```tsx
|
|
484
|
+
import type { PageBuilderBlockEditorConfig } from '@endora-commerce/page-builder-core/contributions';
|
|
133
485
|
|
|
134
|
-
|
|
135
|
-
is instantiated:
|
|
486
|
+
import { Badge } from '../storefront/Badge.js';
|
|
136
487
|
|
|
488
|
+
const editor: PageBuilderBlockEditorConfig = { render: Badge };
|
|
489
|
+
|
|
490
|
+
export default editor;
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
For the e-mail editor it is the e-mail layer's renderer, the function the send
|
|
494
|
+
path runs, so the canvas and the preview cannot differ from the message:
|
|
495
|
+
|
|
496
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/admin/badge-email.ts -->
|
|
137
497
|
```ts
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
498
|
+
import { emailBlocks } from '../email/index.js';
|
|
499
|
+
|
|
500
|
+
export default emailBlocks['acceptance_blocks.Badge'];
|
|
141
501
|
```
|
|
142
502
|
|
|
143
|
-
The
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
503
|
+
The block's label, palette section, default props and field set come from the
|
|
504
|
+
manifest declaration, not from the contribution. A CMS editor config may carry
|
|
505
|
+
`fields` to replace the editor of a field the manifest declares — a picker in
|
|
506
|
+
place of a text input — and cannot add a field the manifest does not declare.
|
|
507
|
+
|
|
508
|
+
A declared block with **no** editor renderer is still insertable and editable:
|
|
509
|
+
the editor builds its fields from the manifest declaration and shows a neutral
|
|
510
|
+
preview that names the block. That is what an overlay module's block gets,
|
|
511
|
+
since an overlay module has no admin layer. In the e-mail editor such a block
|
|
512
|
+
is also absent from the HTML preview, although the backend renders it in the
|
|
513
|
+
message that is sent.
|
|
514
|
+
|
|
515
|
+
**Installing it in an instance.** The instance's owner adds the package to the
|
|
516
|
+
instance's dependencies and installs. Then:
|
|
517
|
+
|
|
518
|
+
1. `pnpm run build:admin` — it runs `endora generate`, which names the
|
|
519
|
+
package's `./admin` in the admin's contribution registry and its
|
|
520
|
+
`./blocks.css` in the admin's stylesheet, and then builds the admin.
|
|
521
|
+
2. `pnpm run module:install <module id>` — the module's lifecycle install,
|
|
522
|
+
which creates the Setting an operator switches it on and off with.
|
|
523
|
+
3. Restart the backend. Its e-mail renderers are registered at boot.
|
|
524
|
+
|
|
525
|
+
There is no line to add to any file of the instance.
|
|
526
|
+
|
|
527
|
+
### The block stylesheet
|
|
528
|
+
|
|
529
|
+
`./blocks.css` is one finished stylesheet. Every selector is under a class
|
|
530
|
+
prefixed with the module id, and colours and fonts come from the storefront's
|
|
531
|
+
theme custom properties with literal fallbacks, so the block follows the
|
|
532
|
+
channel's theme and still renders on the admin canvas:
|
|
533
|
+
|
|
534
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/blocks.css -->
|
|
535
|
+
```css
|
|
536
|
+
.acceptance_blocks-badge {
|
|
537
|
+
display: inline-block;
|
|
538
|
+
padding: 0.25rem 0.625rem;
|
|
539
|
+
border-radius: var(--r-md, 6px);
|
|
540
|
+
background: var(--brand-600, #2563eb);
|
|
541
|
+
color: #ffffff;
|
|
542
|
+
font-family: var(--font-sans, system-ui, sans-serif);
|
|
543
|
+
font-size: 0.875rem;
|
|
544
|
+
font-weight: 600;
|
|
545
|
+
line-height: 1.4;
|
|
546
|
+
}
|
|
547
|
+
```
|
|
548
|
+
|
|
549
|
+
No `@import`, no `@tailwind`, no `@source`, no element selectors. The
|
|
550
|
+
storefront imports it through `blocks:generate` and the admin through
|
|
551
|
+
`endora generate`.
|
|
552
|
+
|
|
553
|
+
### When the module is switched off
|
|
554
|
+
|
|
555
|
+
A block whose module an operator switched off is absent on every surface, and
|
|
556
|
+
nothing is written to the stored content:
|
|
557
|
+
|
|
558
|
+
| Surface | What happens |
|
|
559
|
+
| --- | --- |
|
|
560
|
+
| Storefront | the block renders nothing to a customer; with `?cms_admin=1` it renders a note naming the block |
|
|
561
|
+
| E-mail | the block contributes nothing to the HTML or the text; the message is still sent, and content holding the block can still be saved |
|
|
562
|
+
| Admin editors | a stored block is a visible placeholder that keeps its props; the block is not offered in the palette |
|
|
563
|
+
|
|
564
|
+
Switching the module back on restores all three, with no document changed in
|
|
565
|
+
between. The storefront decides from the modules the backend **reports** as not
|
|
566
|
+
present, so a block whose owner the backend does not know — an overlay
|
|
567
|
+
module's — still renders. The same holds for a package the storefront has
|
|
568
|
+
installed and the backend does not compose, and when the backend cannot be
|
|
569
|
+
reached nobody is reported absent.
|
|
570
|
+
|
|
571
|
+
### When a renderer fails
|
|
572
|
+
|
|
573
|
+
A renderer that throws costs the page that one block. On the storefront and in
|
|
574
|
+
the editors it becomes the same placeholder a missing renderer gets, and the
|
|
575
|
+
blocks around it are untouched; in an e-mail it contributes nothing, the
|
|
576
|
+
message is still sent, and the failure is logged with the block and its
|
|
577
|
+
module.
|
|
578
|
+
|
|
579
|
+
### Check the package
|
|
580
|
+
|
|
581
|
+
Run the check in the module package:
|
|
582
|
+
|
|
583
|
+
```bash
|
|
584
|
+
pnpm exec endora check --rule check:block-renderers
|
|
585
|
+
```
|
|
586
|
+
|
|
587
|
+
| Finding | Meaning |
|
|
588
|
+
| --- | --- |
|
|
589
|
+
| `foreign-block-name` | a renderer keyed by a block another module owns |
|
|
590
|
+
| `undeclared-block` | a renderer for a block the manifest does not declare, or not for that surface's context |
|
|
591
|
+
| `storefront-import` | the storefront layer imports outside its allowed set |
|
|
592
|
+
| `raw-html` | `dangerouslySetInnerHTML` whose value is not `sanitizeRichHtml(…)` |
|
|
593
|
+
| `email-layer-import` | the e-mail layer imports React, a Node built-in or anything outside the e-mail renderer |
|
|
594
|
+
| `unscoped-stylesheet` | `./blocks.css` has a selector outside the module's prefix, or pulls in another stylesheet |
|
|
595
|
+
| `layer-without-subpath` | a layer's sources exist and the `exports` map does not publish them |
|
|
596
|
+
|
|
597
|
+
### Keep old content rendering
|
|
598
|
+
|
|
599
|
+
A block's name is permanent, and its stored props outlive the version of the
|
|
600
|
+
module that wrote them. A renderer must draw every shape of props the module
|
|
601
|
+
ever published: ignore a prop it does not know, and fall back to a default for
|
|
602
|
+
one that is missing. A change that cannot be made that way is a new block
|
|
603
|
+
under a new name, with the old renderer kept.
|
|
147
604
|
|
|
148
605
|
## Component name namespacing
|
|
149
606
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
607
|
+
Block names are unique platform-wide, and the module-id prefix is what makes
|
|
608
|
+
them so: `cms.Text`, `catalog.ProductCard`, `promotions.PromoBanner`. Two
|
|
609
|
+
modules cannot declare the same name — the owner segment must be the
|
|
610
|
+
declaring module's id — and if a collision reaches the registry anyway it
|
|
611
|
+
throws `DuplicateBlockNameError` rather than letting one module's block
|
|
612
|
+
replace another's.
|
|
155
613
|
|
|
156
614
|
## Context availability (`contexts`)
|
|
157
615
|
|
|
@@ -165,16 +623,17 @@ Every component declares which Page Builder surfaces may expose it via
|
|
|
165
623
|
| `newsletter` | Newsletter campaigns (alias of email-safe set) |
|
|
166
624
|
| `invoice` | Invoice PDF template editor |
|
|
167
625
|
|
|
168
|
-
|
|
626
|
+
Declare them on the block in the manifest. `contexts` is required and must
|
|
627
|
+
name at least one surface:
|
|
169
628
|
|
|
170
629
|
```ts
|
|
171
|
-
contexts: ['cms'], //
|
|
630
|
+
contexts: ['cms'], // CMS-only
|
|
172
631
|
```
|
|
173
632
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
633
|
+
A block without `email` / `invoice` in `contexts` never appears in those
|
|
634
|
+
editors (e.g. a product carousel). A module ships renderers for the `cms` and
|
|
635
|
+
`email` contexts; `newsletter` shows the `email` blocks, and invoice blocks are
|
|
636
|
+
drawn by the invoices module.
|
|
178
637
|
|
|
179
638
|
## Responsive props and visibility (CMS only)
|
|
180
639
|
|
|
@@ -242,7 +701,7 @@ Use `createSpacingField`, `createBorderField`, and `createColorField` from
|
|
|
242
701
|
|
|
243
702
|
| Priority | Idea | Why |
|
|
244
703
|
| -------- | ---- | --- |
|
|
245
|
-
| Medium | Newsletter ↔ module
|
|
704
|
+
| Medium | Newsletter signup ↔ the `newsletter` module | Auto-wire channel subscribe endpoint |
|
|
246
705
|
| Low | Contact ↔ forms module | Pick an existing form instead of iframe URL |
|
|
247
706
|
|
|
248
707
|
`Accordion` / `Tabs` already cover FAQ-style sections; prefer those before a
|
|
@@ -250,7 +709,7 @@ dedicated FAQ component.
|
|
|
250
709
|
|
|
251
710
|
## Testing
|
|
252
711
|
|
|
253
|
-
|
|
254
|
-
`
|
|
255
|
-
|
|
256
|
-
|
|
712
|
+
Use `backend/acceptance/block-renderers-fixture/` as the template for a package
|
|
713
|
+
that ships renderers, and `endora check` as its first test.
|
|
714
|
+
`backend/test/integration/cms/page-builder-extension.test.ts` covers the
|
|
715
|
+
declaration half: a manifest's blocks reaching the descriptor.
|