@endora-commerce/mod-cms 0.102.0 → 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/dist/admin/components/PageBuilderEditor.d.ts.map +1 -1
- package/dist/admin/components/PageBuilderEditor.js +87 -40
- package/dist/admin/components/PageBuilderEditor.js.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/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 +511 -64
- package/docs/cms/index.md +4 -5
- package/i18n/en.json +1 -0
- package/i18n/pl.json +1 -0
- package/package.json +13 -13
|
@@ -10,17 +10,19 @@ The CMS module ships built-in components — `Row`, `Columns`, `Text`,
|
|
|
10
10
|
backend module can contribute its own components. (`InsertTemplate` remains
|
|
11
11
|
registered for legacy content trees but is no longer listed in the drawer
|
|
12
12
|
palette.) The `cms`, `catalog`, `orders`, `invoices` and `transactional_emails`
|
|
13
|
-
modules already
|
|
14
|
-
|
|
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:
|
|
15
18
|
|
|
16
19
|
1. **Manifest declaration**: declare the block's metadata — name, labels,
|
|
17
20
|
palette category, contexts and editable fields — in the module's own
|
|
18
21
|
`manifest.ts`. The CMS module builds its Page Builder registry from the
|
|
19
22
|
manifests of the composed modules, so there is no registration call to
|
|
20
23
|
write.
|
|
21
|
-
2. **
|
|
22
|
-
|
|
23
|
-
or a per-module package re-exporting from it).
|
|
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.
|
|
24
26
|
|
|
25
27
|
## 1. Declare the block in the manifest
|
|
26
28
|
|
|
@@ -64,7 +66,8 @@ export const manifest = defineModuleManifest({
|
|
|
64
66
|
```
|
|
65
67
|
|
|
66
68
|
The schema is `BlockDefinitionSchema` and `BlockCategorySchema` in
|
|
67
|
-
`packages/contracts/src/cms.ts
|
|
69
|
+
`packages/contracts/src/cms.ts` (both exported from
|
|
70
|
+
`@endora-commerce/contracts`). `defineModuleManifest` refuses a manifest
|
|
68
71
|
that breaks either of two rules:
|
|
69
72
|
|
|
70
73
|
- A block `name` is `<module id>.<PascalCaseName>`, and the part before the
|
|
@@ -89,71 +92,515 @@ declarations by module presence when it answers
|
|
|
89
92
|
`GET /api/v1/admin/cms/page-builder/config`, so a module that is switched off
|
|
90
93
|
takes its blocks out of the palette with it.
|
|
91
94
|
|
|
92
|
-
## 2. Ship the
|
|
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';
|
|
93
255
|
|
|
94
|
-
|
|
95
|
-
(or in your module's own admin/storefront package) and export it from the
|
|
96
|
-
package's entry point:
|
|
256
|
+
import { Badge } from './Badge.js';
|
|
97
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
|
+
```
|
|
267
|
+
|
|
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:
|
|
271
|
+
|
|
272
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/storefront/Badge.tsx -->
|
|
98
273
|
```tsx
|
|
99
|
-
|
|
100
|
-
|
|
274
|
+
'use client';
|
|
275
|
+
|
|
276
|
+
import { useBlockRenderEnvironment } from '@endora-commerce/page-builder-core/contributions';
|
|
277
|
+
import type { ReactNode } from 'react';
|
|
278
|
+
|
|
279
|
+
export interface BadgeProps {
|
|
280
|
+
readonly text?: string;
|
|
281
|
+
readonly explode?: string | boolean;
|
|
282
|
+
}
|
|
283
|
+
|
|
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';
|
|
101
370
|
|
|
102
|
-
interface
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
tone: 'info' | 'urgent';
|
|
371
|
+
interface BadgeProps {
|
|
372
|
+
readonly text?: string;
|
|
373
|
+
readonly explode?: string | boolean;
|
|
106
374
|
}
|
|
107
375
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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
|
+
},
|
|
116
398
|
},
|
|
117
|
-
defaultProps: { headline: 'Spring sale', tone: 'info' },
|
|
118
|
-
contexts: ['cms'],
|
|
119
|
-
render: ({ headline, codeInput, tone }) => (
|
|
120
|
-
<div className={`promo-banner promo-${tone}`}>
|
|
121
|
-
<strong>{headline}</strong>
|
|
122
|
-
{codeInput ? <code>{codeInput}</code> : null}
|
|
123
|
-
</div>
|
|
124
|
-
),
|
|
125
399
|
};
|
|
126
400
|
```
|
|
127
401
|
|
|
128
|
-
|
|
129
|
-
|
|
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`:
|
|
130
414
|
|
|
415
|
+
<!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/manifest.ts -->
|
|
131
416
|
```ts
|
|
132
|
-
//
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
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
|
+
],
|
|
143
476
|
};
|
|
144
477
|
```
|
|
145
478
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
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:
|
|
481
|
+
|
|
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';
|
|
485
|
+
|
|
486
|
+
import { Badge } from '../storefront/Badge.js';
|
|
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 -->
|
|
497
|
+
```ts
|
|
498
|
+
import { emailBlocks } from '../email/index.js';
|
|
499
|
+
|
|
500
|
+
export default emailBlocks['acceptance_blocks.Badge'];
|
|
501
|
+
```
|
|
502
|
+
|
|
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
|
|
150
598
|
|
|
151
|
-
A
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
`?cms_admin=1` query parameter (preview mode).
|
|
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.
|
|
157
604
|
|
|
158
605
|
## Component name namespacing
|
|
159
606
|
|
|
@@ -183,10 +630,10 @@ name at least one surface:
|
|
|
183
630
|
contexts: ['cms'], // CMS-only
|
|
184
631
|
```
|
|
185
632
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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.
|
|
190
637
|
|
|
191
638
|
## Responsive props and visibility (CMS only)
|
|
192
639
|
|
|
@@ -254,7 +701,7 @@ Use `createSpacingField`, `createBorderField`, and `createColorField` from
|
|
|
254
701
|
|
|
255
702
|
| Priority | Idea | Why |
|
|
256
703
|
| -------- | ---- | --- |
|
|
257
|
-
| Medium | Newsletter ↔ module
|
|
704
|
+
| Medium | Newsletter signup ↔ the `newsletter` module | Auto-wire channel subscribe endpoint |
|
|
258
705
|
| Low | Contact ↔ forms module | Pick an existing form instead of iframe URL |
|
|
259
706
|
|
|
260
707
|
`Accordion` / `Tabs` already cover FAQ-style sections; prefer those before a
|
|
@@ -262,7 +709,7 @@ dedicated FAQ component.
|
|
|
262
709
|
|
|
263
710
|
## Testing
|
|
264
711
|
|
|
265
|
-
|
|
266
|
-
`
|
|
267
|
-
|
|
268
|
-
|
|
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.
|
package/docs/cms/index.md
CHANGED
|
@@ -216,11 +216,10 @@ mirrors; the asset-ref scan covers `body` for backward compatibility.
|
|
|
216
216
|
|
|
217
217
|
## Extending the Page Builder
|
|
218
218
|
|
|
219
|
-
Other
|
|
220
|
-
|
|
221
|
-
[Extending the Page Builder](./extending-page-builder) guide
|
|
222
|
-
|
|
223
|
-
composition wiring.
|
|
219
|
+
Other modules declare their blocks in their own manifest and ship the renderers
|
|
220
|
+
in their own package. See the
|
|
221
|
+
[Extending the Page Builder](./extending-page-builder) guide: the manifest
|
|
222
|
+
declaration, the three renderer layers and the block stylesheet.
|
|
224
223
|
|
|
225
224
|
## Error codes
|
|
226
225
|
|
package/i18n/en.json
CHANGED
|
@@ -39,6 +39,7 @@
|
|
|
39
39
|
"status.draft": "Draft",
|
|
40
40
|
"status.published": "Published",
|
|
41
41
|
"pageBuilder.extensions": "Extensions",
|
|
42
|
+
"pageBuilder.blockPreview.unavailable": "This block has no preview in the editor. Its fields can be edited in the side panel.",
|
|
42
43
|
"pageBuilder.loadingConfig": "Loading Page Builder config...",
|
|
43
44
|
"pageBuilder.drawer.searchPlaceholder": "Search components…",
|
|
44
45
|
"pageBuilder.drawer.searchEmpty": "No components match your search.",
|
package/i18n/pl.json
CHANGED
|
@@ -39,6 +39,7 @@
|
|
|
39
39
|
"status.draft": "Szkic",
|
|
40
40
|
"status.published": "Opublikowana",
|
|
41
41
|
"pageBuilder.extensions": "Rozszerzenia",
|
|
42
|
+
"pageBuilder.blockPreview.unavailable": "Ten blok nie ma podglądu w edytorze. Jego pola można edytować w panelu bocznym.",
|
|
42
43
|
"pageBuilder.loadingConfig": "Ładowanie konfiguracji Page Builder...",
|
|
43
44
|
"pageBuilder.drawer.searchPlaceholder": "Szukaj komponentów…",
|
|
44
45
|
"pageBuilder.drawer.searchEmpty": "Brak komponentów pasujących do wyszukiwania.",
|