@endora-commerce/mod-cms 0.108.0 → 0.109.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 -0
- package/dist/admin/api/cms-client.d.ts +19 -3
- package/dist/admin/api/cms-client.d.ts.map +1 -1
- package/dist/admin/api/cms-client.js +23 -2
- package/dist/admin/api/cms-client.js.map +1 -1
- package/dist/admin/components/AdminCatalogPreviewProvider.d.ts.map +1 -1
- package/dist/admin/components/AdminCatalogPreviewProvider.js +51 -0
- package/dist/admin/components/AdminCatalogPreviewProvider.js.map +1 -1
- package/dist/admin/components/BackgroundFields.d.ts +16 -0
- package/dist/admin/components/BackgroundFields.d.ts.map +1 -1
- package/dist/admin/components/BackgroundFields.js +58 -11
- package/dist/admin/components/BackgroundFields.js.map +1 -1
- package/dist/admin/components/BrandFontFields.d.ts +17 -0
- package/dist/admin/components/BrandFontFields.d.ts.map +1 -0
- package/dist/admin/components/BrandFontFields.js +39 -0
- package/dist/admin/components/BrandFontFields.js.map +1 -0
- package/dist/admin/components/BrandPreview.d.ts +29 -0
- package/dist/admin/components/BrandPreview.d.ts.map +1 -0
- package/dist/admin/components/BrandPreview.js +130 -0
- package/dist/admin/components/BrandPreview.js.map +1 -0
- package/dist/admin/components/CarouselAddSlideMenu.d.ts +5 -0
- package/dist/admin/components/CarouselAddSlideMenu.d.ts.map +1 -0
- package/dist/admin/components/CarouselAddSlideMenu.js +84 -0
- package/dist/admin/components/CarouselAddSlideMenu.js.map +1 -0
- package/dist/admin/components/CarouselFields.d.ts +6 -0
- package/dist/admin/components/CarouselFields.d.ts.map +1 -0
- package/dist/admin/components/CarouselFields.js +55 -0
- package/dist/admin/components/CarouselFields.js.map +1 -0
- package/dist/admin/components/ContentSliderActionBarExtras.d.ts.map +1 -1
- package/dist/admin/components/ContentSliderActionBarExtras.js +13 -6
- package/dist/admin/components/ContentSliderActionBarExtras.js.map +1 -1
- package/dist/admin/components/HeroFields.d.ts +47 -0
- package/dist/admin/components/HeroFields.d.ts.map +1 -0
- package/dist/admin/components/HeroFields.js +92 -0
- package/dist/admin/components/HeroFields.js.map +1 -0
- package/dist/admin/components/ListingFields.d.ts +6 -0
- package/dist/admin/components/ListingFields.d.ts.map +1 -0
- package/dist/admin/components/ListingFields.js +54 -0
- package/dist/admin/components/ListingFields.js.map +1 -0
- package/dist/admin/components/NewsletterSignupFields.d.ts +18 -0
- package/dist/admin/components/NewsletterSignupFields.d.ts.map +1 -0
- package/dist/admin/components/NewsletterSignupFields.js +38 -0
- package/dist/admin/components/NewsletterSignupFields.js.map +1 -0
- package/dist/admin/components/PageBuilderActionBar.d.ts.map +1 -1
- package/dist/admin/components/PageBuilderActionBar.js +1 -6
- package/dist/admin/components/PageBuilderActionBar.js.map +1 -1
- package/dist/admin/components/PageBuilderEditor.d.ts +43 -2
- package/dist/admin/components/PageBuilderEditor.d.ts.map +1 -1
- package/dist/admin/components/PageBuilderEditor.js +207 -121
- package/dist/admin/components/PageBuilderEditor.js.map +1 -1
- package/dist/admin/components/PageNavigationFields.d.ts +6 -0
- package/dist/admin/components/PageNavigationFields.d.ts.map +1 -0
- package/dist/admin/components/PageNavigationFields.js +29 -0
- package/dist/admin/components/PageNavigationFields.js.map +1 -0
- package/dist/admin/components/PreviewBrandTokens.d.ts +25 -0
- package/dist/admin/components/PreviewBrandTokens.d.ts.map +1 -0
- package/dist/admin/components/PreviewBrandTokens.js +68 -0
- package/dist/admin/components/PreviewBrandTokens.js.map +1 -0
- package/dist/admin/components/SectionBlockFields.d.ts +44 -0
- package/dist/admin/components/SectionBlockFields.d.ts.map +1 -0
- package/dist/admin/components/SectionBlockFields.js +114 -0
- package/dist/admin/components/SectionBlockFields.js.map +1 -0
- package/dist/admin/components/SectionPresetsPanel.d.ts +11 -0
- package/dist/admin/components/SectionPresetsPanel.d.ts.map +1 -0
- package/dist/admin/components/SectionPresetsPanel.js +82 -0
- package/dist/admin/components/SectionPresetsPanel.js.map +1 -0
- package/dist/admin/components/SliderPreviewActionBarExtras.d.ts +1 -1
- package/dist/admin/components/SliderPreviewActionBarExtras.d.ts.map +1 -1
- package/dist/admin/components/SliderPreviewActionBarExtras.js +1 -5
- package/dist/admin/components/SliderPreviewActionBarExtras.js.map +1 -1
- package/dist/admin/components/admin-catalog-preview-map.d.ts +9 -0
- package/dist/admin/components/admin-catalog-preview-map.d.ts.map +1 -1
- package/dist/admin/components/admin-catalog-preview-map.js +10 -0
- package/dist/admin/components/admin-catalog-preview-map.js.map +1 -1
- package/dist/admin/components/page-builder-i18n.d.ts +24 -2
- package/dist/admin/components/page-builder-i18n.d.ts.map +1 -1
- package/dist/admin/components/page-builder-i18n.js +102 -9
- package/dist/admin/components/page-builder-i18n.js.map +1 -1
- package/dist/admin/editors/PageEditor.d.ts.map +1 -1
- package/dist/admin/editors/PageEditor.js +270 -38
- package/dist/admin/editors/PageEditor.js.map +1 -1
- package/dist/admin/index.d.ts +1 -1
- package/dist/admin/index.d.ts.map +1 -1
- package/dist/admin/index.js +21 -1
- package/dist/admin/index.js.map +1 -1
- package/dist/admin/pages/BrandPage.d.ts +19 -0
- package/dist/admin/pages/BrandPage.d.ts.map +1 -0
- package/dist/admin/pages/BrandPage.js +316 -0
- package/dist/admin/pages/BrandPage.js.map +1 -0
- package/dist/admin/pages/PagesListPage.d.ts.map +1 -1
- package/dist/admin/pages/PagesListPage.js +4 -1
- package/dist/admin/pages/PagesListPage.js.map +1 -1
- package/dist/backend/cli/block-names.d.ts +2 -1
- package/dist/backend/cli/block-names.d.ts.map +1 -1
- package/dist/backend/cli/block-names.js.map +1 -1
- package/dist/backend/entities/cms-brand-tokens.entity.d.ts +20 -0
- package/dist/backend/entities/cms-brand-tokens.entity.d.ts.map +1 -0
- package/dist/backend/entities/cms-brand-tokens.entity.js +57 -0
- package/dist/backend/entities/cms-brand-tokens.entity.js.map +1 -0
- package/dist/backend/entities/cms-page.entity.d.ts +32 -1
- package/dist/backend/entities/cms-page.entity.d.ts.map +1 -1
- package/dist/backend/entities/cms-page.entity.js +63 -0
- package/dist/backend/entities/cms-page.entity.js.map +1 -1
- package/dist/backend/index.d.ts +5 -1
- package/dist/backend/index.d.ts.map +1 -1
- package/dist/backend/index.js +78 -8
- package/dist/backend/index.js.map +1 -1
- package/dist/backend/plugin.d.ts +16 -2
- package/dist/backend/plugin.d.ts.map +1 -1
- package/dist/backend/plugin.js +20 -1
- package/dist/backend/plugin.js.map +1 -1
- package/dist/backend/routes.admin.d.ts +2 -0
- package/dist/backend/routes.admin.d.ts.map +1 -1
- package/dist/backend/routes.admin.js +39 -4
- package/dist/backend/routes.admin.js.map +1 -1
- package/dist/backend/routes.storefront.d.ts +24 -1
- package/dist/backend/routes.storefront.d.ts.map +1 -1
- package/dist/backend/routes.storefront.js +55 -2
- package/dist/backend/routes.storefront.js.map +1 -1
- package/dist/backend/services/anchor-guard.d.ts +10 -0
- package/dist/backend/services/anchor-guard.d.ts.map +1 -0
- package/dist/backend/services/anchor-guard.js +132 -0
- package/dist/backend/services/anchor-guard.js.map +1 -0
- package/dist/backend/services/asset-references.d.ts.map +1 -1
- package/dist/backend/services/asset-references.js +46 -30
- package/dist/backend/services/asset-references.js.map +1 -1
- package/dist/backend/services/brand-tokens-service.d.ts +84 -0
- package/dist/backend/services/brand-tokens-service.d.ts.map +1 -0
- package/dist/backend/services/brand-tokens-service.js +159 -0
- package/dist/backend/services/brand-tokens-service.js.map +1 -0
- package/dist/backend/services/channel-language-prefixes.d.ts +11 -0
- package/dist/backend/services/channel-language-prefixes.d.ts.map +1 -0
- package/dist/backend/services/channel-language-prefixes.js +24 -0
- package/dist/backend/services/channel-language-prefixes.js.map +1 -0
- package/dist/backend/services/cms-block-service.d.ts.map +1 -1
- package/dist/backend/services/cms-block-service.js +3 -0
- package/dist/backend/services/cms-block-service.js.map +1 -1
- package/dist/backend/services/cms-cache.d.ts +10 -0
- package/dist/backend/services/cms-cache.d.ts.map +1 -1
- package/dist/backend/services/cms-cache.js +9 -0
- package/dist/backend/services/cms-cache.js.map +1 -1
- package/dist/backend/services/cms-content-invalidator.d.ts +13 -4
- package/dist/backend/services/cms-content-invalidator.d.ts.map +1 -1
- package/dist/backend/services/cms-content-invalidator.js +13 -6
- package/dist/backend/services/cms-content-invalidator.js.map +1 -1
- package/dist/backend/services/cms-page-read-port.d.ts +6 -1
- package/dist/backend/services/cms-page-read-port.d.ts.map +1 -1
- package/dist/backend/services/cms-page-read-port.js +27 -0
- package/dist/backend/services/cms-page-read-port.js.map +1 -1
- package/dist/backend/services/cms-page-service.d.ts +72 -1
- package/dist/backend/services/cms-page-service.d.ts.map +1 -1
- package/dist/backend/services/cms-page-service.js +317 -17
- package/dist/backend/services/cms-page-service.js.map +1 -1
- package/dist/backend/services/cms-template-service.d.ts.map +1 -1
- package/dist/backend/services/cms-template-service.js +3 -0
- package/dist/backend/services/cms-template-service.js.map +1 -1
- package/dist/backend/services/contact-form/contact-form-mail.d.ts +22 -0
- package/dist/backend/services/contact-form/contact-form-mail.d.ts.map +1 -0
- package/dist/backend/services/contact-form/contact-form-mail.js +64 -0
- package/dist/backend/services/contact-form/contact-form-mail.js.map +1 -0
- package/dist/backend/services/contact-form/contact-form.service.d.ts +35 -0
- package/dist/backend/services/contact-form/contact-form.service.d.ts.map +1 -0
- package/dist/backend/services/contact-form/contact-form.service.js +75 -0
- package/dist/backend/services/contact-form/contact-form.service.js.map +1 -0
- package/dist/backend/services/contact-form/recipients-validator.d.ts +8 -0
- package/dist/backend/services/contact-form/recipients-validator.d.ts.map +1 -0
- package/dist/backend/services/contact-form/recipients-validator.js +23 -0
- package/dist/backend/services/contact-form/recipients-validator.js.map +1 -0
- package/dist/backend/services/content-tree-walker.d.ts +12 -0
- package/dist/backend/services/content-tree-walker.d.ts.map +1 -1
- package/dist/backend/services/content-tree-walker.js +40 -0
- package/dist/backend/services/content-tree-walker.js.map +1 -1
- package/dist/backend/services/page-builder-registry.d.ts +11 -2
- package/dist/backend/services/page-builder-registry.d.ts.map +1 -1
- package/dist/backend/services/page-builder-registry.js +10 -1
- package/dist/backend/services/page-builder-registry.js.map +1 -1
- package/dist/backend/services/page-paths.d.ts +87 -0
- package/dist/backend/services/page-paths.d.ts.map +1 -0
- package/dist/backend/services/page-paths.js +177 -0
- package/dist/backend/services/page-paths.js.map +1 -0
- package/dist/backend/services/storefront-resolver.d.ts +53 -2
- package/dist/backend/services/storefront-resolver.d.ts.map +1 -1
- package/dist/backend/services/storefront-resolver.js +313 -22
- package/dist/backend/services/storefront-resolver.js.map +1 -1
- package/dist/backend/services/translation/extract.d.ts.map +1 -1
- package/dist/backend/services/translation/extract.js +9 -1
- package/dist/backend/services/translation/extract.js.map +1 -1
- package/dist/manifest.d.ts +13 -1
- package/dist/manifest.d.ts.map +1 -1
- package/dist/manifest.js +592 -73
- package/dist/manifest.js.map +1 -1
- package/dist/migrations/20261022T163218_cms_brand_tokens.d.ts +24 -0
- package/dist/migrations/20261022T163218_cms_brand_tokens.d.ts.map +1 -0
- package/dist/migrations/20261022T163218_cms_brand_tokens.js +38 -0
- package/dist/migrations/20261022T163218_cms_brand_tokens.js.map +1 -0
- package/dist/migrations/20261023T052237_cms_page_tree_and_share.d.ts +24 -0
- package/dist/migrations/20261023T052237_cms_page_tree_and_share.d.ts.map +1 -0
- package/dist/migrations/20261023T052237_cms_page_tree_and_share.js +51 -0
- package/dist/migrations/20261023T052237_cms_page_tree_and_share.js.map +1 -0
- package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.d.ts +16 -0
- package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.d.ts.map +1 -0
- package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.js +20 -0
- package/dist/migrations/20261027T165458_cms_page_parent_path_in_url.js.map +1 -0
- package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.d.ts +14 -0
- package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.d.ts.map +1 -0
- package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.js +18 -0
- package/dist/migrations/20261028T090524_cms_page_breadcrumbs_overlay.js.map +1 -0
- package/dist/migrations/20261029T131218_cms_page_translations.d.ts +15 -0
- package/dist/migrations/20261029T131218_cms_page_translations.d.ts.map +1 -0
- package/dist/migrations/20261029T131218_cms_page_translations.js +19 -0
- package/dist/migrations/20261029T131218_cms_page_translations.js.map +1 -0
- package/dist/migrations/index.d.ts +6 -1
- package/dist/migrations/index.d.ts.map +1 -1
- package/dist/migrations/index.js +11 -1
- package/dist/migrations/index.js.map +1 -1
- package/docs/cms/brand.md +310 -0
- package/docs/cms/contact-form.md +161 -0
- package/docs/cms/extending-page-builder.md +210 -15
- package/docs/cms/index.md +1232 -39
- package/docs/cms/page-navigation.md +83 -0
- package/i18n/en.json +2758 -22
- package/i18n/pl.json +2758 -22
- package/package.json +18 -16
- package/dist/admin/components/ButtonLinkFields.d.ts +0 -6
- package/dist/admin/components/ButtonLinkFields.d.ts.map +0 -1
- package/dist/admin/components/ButtonLinkFields.js +0 -127
- package/dist/admin/components/ButtonLinkFields.js.map +0 -1
|
@@ -0,0 +1,310 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Brand settings
|
|
3
|
+
sidebar_label: Brand
|
|
4
|
+
sidebar_position: 2
|
|
5
|
+
description: One set of colours, colour schemes, fonts, type scale, buttons and spacing that every Page Builder block uses, set globally and optionally per sales channel
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Brand settings
|
|
9
|
+
|
|
10
|
+
The **Brand** screen holds the design decisions every Page Builder block
|
|
11
|
+
follows on the storefront: the colour palette, the three colour schemes, the
|
|
12
|
+
heading and body fonts, the type scale, the button shape and the spacing and
|
|
13
|
+
layout widths. Change the primary colour or the body font here once, and every
|
|
14
|
+
page built with the Page Builder follows — no page is edited and nothing is
|
|
15
|
+
rebuilt or redeployed.
|
|
16
|
+
|
|
17
|
+
Until somebody saves the screen, the built-in values apply, and they reproduce
|
|
18
|
+
the look the blocks had before the screen existed.
|
|
19
|
+
|
|
20
|
+
## Opening the screen
|
|
21
|
+
|
|
22
|
+
- **Navigation**: **Brand** (`/cms/brand`), next to the other CMS screens.
|
|
23
|
+
- **Command palette**: ⌘K / CTRL+K → "Brand settings" (also found by *brand*,
|
|
24
|
+
*fonts*, *colours*, *colors*, *typography* or *theme*).
|
|
25
|
+
- **Permissions**: any role with **View CMS content** (`cms.read`) can open and
|
|
26
|
+
read the screen. Saving needs **Edit brand settings** (`cms.brand`), which
|
|
27
|
+
itself requires `cms.read`. Without it the fields are read-only and there is
|
|
28
|
+
no Save button.
|
|
29
|
+
|
|
30
|
+
## What you can set
|
|
31
|
+
|
|
32
|
+
| Section | Settings |
|
|
33
|
+
| --- | --- |
|
|
34
|
+
| Colours | Primary and secondary colours with their hover colours, the text colour on each, a neutral scale from 50 to 900, and the **accent gradient** (start, end and angle) used by gradient highlights in headings. |
|
|
35
|
+
| Colour schemes | Light, muted and dark. Each has a background, text, muted text, border and link colour. The dark scheme can also have a **decorative backdrop**, an image a dark section may paint behind its content. A section chooses its scheme in the Page Builder, and every block inside it takes the scheme's colours. |
|
|
36
|
+
| Typography | The heading font and the body font (see [Fonts](#fonts)), and the type scale: Display, Heading 1–6, Lead, Body and Small, each with a mobile and a desktop size, line height, weight, letter spacing and whether it uses the heading or the body font. Heading 1–6 also apply to the headings written inside rich text (a Rich Content block, a block's rich body). |
|
|
37
|
+
| Buttons | Corner shape (square, rounded or pill), the heights of small, medium and large buttons, the label weight and the label case. |
|
|
38
|
+
| Spacing | The named steps a section's top and bottom spacing is chosen from — none, extra small, small, medium, large, extra large, largest — each with a mobile and a desktop size. |
|
|
39
|
+
| Layout | The content width, the wide content width, and the side margin on mobile and on desktop. The content width is the page container — 1360 px, side margins included, until changed; set it wider for a wider frame on every CMS page: Contained sections, content held in the page container, and the page's breadcrumb trail all follow it. Two optional factors scale the type and the spacing steps between breakpoints: **Type and spacing scale on a tablet (768–1023 px)** multiplies the mobile sizes there (for example 1.15 for 15 % larger), and **Type and spacing scale on a small desktop (1024–1279 px)** the desktop sizes. Empty is 1: nothing changes. Sizes a block sets in pixels of its own (a **Custom (px)** size or space) are not scaled. Two further optional settings, off by default: **Grow the desktop sizes with the window after the small desktop** makes the sizes grow with the window width from the small-desktop factor at 1280 px to the full desktop sizes at **Full desktop sizes from (px, default the page container width)**; **Scale button heights with the type and spacing** applies the factors to the button heights too (an icon-only button follows, as it is sized from them). |
|
|
40
|
+
|
|
41
|
+
A **Preview** shows a sample in each of the three schemes with the values on
|
|
42
|
+
screen, before you save.
|
|
43
|
+
|
|
44
|
+
Blocks still accept a value of their own where it matters: a colour field can
|
|
45
|
+
hold a brand colour (stored as a reference such as `token:primary`, which
|
|
46
|
+
follows later brand changes) or any hex colour, and a heading can override its
|
|
47
|
+
size, font, weight or line height in its **Advanced** group.
|
|
48
|
+
|
|
49
|
+
## Global settings and channel overrides
|
|
50
|
+
|
|
51
|
+
The **Scope** card chooses what you edit:
|
|
52
|
+
|
|
53
|
+
- **All channels (global settings)** — the settings every sales channel uses
|
|
54
|
+
unless it has an override.
|
|
55
|
+
- **A sales channel** — that channel's own brand. A channel without one shows
|
|
56
|
+
**Inherits global**. **Override for this channel** starts the override as a
|
|
57
|
+
**complete copy** of the global settings; nothing is applied until you save.
|
|
58
|
+
|
|
59
|
+
An override is a full copy, not a list of differences. **A later change to the
|
|
60
|
+
global settings does not reach a channel that has an override**; the screen
|
|
61
|
+
says so on every overridden channel. **Reset to global** (after a
|
|
62
|
+
confirmation) deletes the override, and the channel follows the global
|
|
63
|
+
settings again.
|
|
64
|
+
|
|
65
|
+
The storefront uses the effective set of the request's sales channel: the
|
|
66
|
+
channel's override, else the global settings, else the built-in values. The
|
|
67
|
+
Page Builder preview uses the effective set of the page's first assigned sales
|
|
68
|
+
channel, so an editor sees the channel's brand on the canvas.
|
|
69
|
+
|
|
70
|
+
## Contrast warnings
|
|
71
|
+
|
|
72
|
+
The screen warns, in a **Low contrast** notice, when a colour pair falls below
|
|
73
|
+
the WCAG 2.2 AA contrast ratio:
|
|
74
|
+
|
|
75
|
+
- each scheme's text, muted text and link against its background — 4.5:1;
|
|
76
|
+
- the text on primary and on secondary against the button fill and its hover
|
|
77
|
+
fill — 4.5:1;
|
|
78
|
+
- each accent-gradient colour against each scheme's background — 3:1, the
|
|
79
|
+
large-text threshold, because gradient highlights are used in large
|
|
80
|
+
headings.
|
|
81
|
+
|
|
82
|
+
A warning never blocks saving: the brand owner decides. The save response
|
|
83
|
+
returns the same list.
|
|
84
|
+
|
|
85
|
+
## The decorative backdrop
|
|
86
|
+
|
|
87
|
+
The dark scheme's **Decorative backdrop** is any image from the Assets
|
|
88
|
+
Library, an SVG included. A Section with the dark scheme and **Decorative
|
|
89
|
+
backdrop** switched on paints it behind its content, covering the section from
|
|
90
|
+
its top centre.
|
|
91
|
+
|
|
92
|
+
How the backdrop is drawn is set on the section (or the section group) beside
|
|
93
|
+
the **Decorative backdrop** switch, not on this screen: **Backdrop size**
|
|
94
|
+
(Cover, the default; Contain; Natural size; or a width in px or %),
|
|
95
|
+
**Backdrop repeat** (none, the default; tile; across; down) and **Backdrop
|
|
96
|
+
position** (top, the default; centre, bottom, left or right). A tall group
|
|
97
|
+
covered by one image scales it to the group's height, which makes its details
|
|
98
|
+
large and soft; a width in px with **Repeat down** keeps the backdrop at its
|
|
99
|
+
own scale down the whole column, and keeps that size on every screen width.
|
|
100
|
+
|
|
101
|
+
The backdrop can also be given by address, in **Decorative backdrop URL**: an
|
|
102
|
+
`https://` address, or a path on your own site starting with `/` (for example
|
|
103
|
+
`/media/backdrop.svg`, which is loaded from the shop's API address, as a
|
|
104
|
+
library file is). The screen refuses any other address when you save. When
|
|
105
|
+
both are set, the file from the library is used.
|
|
106
|
+
|
|
107
|
+
- **Per section, or once for a group.** Each section paints its own copy, so
|
|
108
|
+
two dark sections next to each other each show the backdrop from their own
|
|
109
|
+
top, with an edge between them. To run one backdrop behind several sections,
|
|
110
|
+
put them in a **Section group** with the dark scheme and **Decorative
|
|
111
|
+
backdrop** switched on: the group paints it once, from its top, behind all its
|
|
112
|
+
sections (see the CMS module page, "Section groups").
|
|
113
|
+
- **Animated SVG.** An SVG can carry its own CSS animation (soft moving lights,
|
|
114
|
+
for example). The browser draws it as an image: it runs no script and loads
|
|
115
|
+
nothing from outside the file, so keep everything — shapes, gradients and the
|
|
116
|
+
`<style>` — inside the SVG.
|
|
117
|
+
- **Reduced motion.** The page cannot stop an animation inside an image, so the
|
|
118
|
+
SVG has to: put the animation inside
|
|
119
|
+
`@media (prefers-reduced-motion: no-preference)`, and a visitor who asks for
|
|
120
|
+
reduced motion sees the static drawing — **where the browser evaluates that
|
|
121
|
+
media query inside an SVG drawn as an image**. Support for it differs between
|
|
122
|
+
browsers and versions, and a browser that does not evaluate it plays the
|
|
123
|
+
animation, so check the asset in the browsers your shop supports and keep the
|
|
124
|
+
motion slow and subtle. Animate with CSS, not with SMIL (`<animate>`), which
|
|
125
|
+
the media query cannot stop.
|
|
126
|
+
|
|
127
|
+
An example that drifts a soft light slowly and stays still under reduced motion:
|
|
128
|
+
|
|
129
|
+
```xml
|
|
130
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" preserveAspectRatio="xMidYMid slice">
|
|
131
|
+
<style>
|
|
132
|
+
.glow { transform-origin: 800px 450px; }
|
|
133
|
+
@media (prefers-reduced-motion: no-preference) {
|
|
134
|
+
.glow { animation: drift 24s ease-in-out infinite alternate; }
|
|
135
|
+
}
|
|
136
|
+
@keyframes drift { to { transform: translateX(120px) scale(1.15); } }
|
|
137
|
+
</style>
|
|
138
|
+
<defs>
|
|
139
|
+
<radialGradient id="g" cx="50%" cy="40%" r="50%">
|
|
140
|
+
<stop offset="0" stop-color="#1d4ed8" stop-opacity="0.55"/>
|
|
141
|
+
<stop offset="1" stop-color="#1d4ed8" stop-opacity="0"/>
|
|
142
|
+
</radialGradient>
|
|
143
|
+
</defs>
|
|
144
|
+
<rect class="glow" x="0" y="0" width="1600" height="900" fill="url(#g)"/>
|
|
145
|
+
</svg>
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Fonts
|
|
149
|
+
|
|
150
|
+
The heading font and the body font are each one of three kinds:
|
|
151
|
+
|
|
152
|
+
| Kind | What you enter | How it loads |
|
|
153
|
+
| --- | --- | --- |
|
|
154
|
+
| **System font** | A stack: sans-serif, serif or monospace. | Nothing is downloaded. |
|
|
155
|
+
| **Font files from the asset library** | A family name (for example `Acme Sans`), a fallback (sans-serif or serif) and up to eight font files, each with a weight (100–900) and a style (normal or italic). The picker lists Assets Library files whose type is `font/*`; prefer `woff2`. | The storefront writes one `@font-face` rule per file with `font-display: swap`, and preloads the regular upright face of the body font. |
|
|
156
|
+
| **Font service stylesheet** | A family name, a fallback, and the `https://` address of the service's stylesheet, for example `https://fonts.example.com/css?family=Acme+Sans`. | The storefront links the stylesheet in the page head. |
|
|
157
|
+
|
|
158
|
+
The fallback generic family always ends the font stack, so text renders while
|
|
159
|
+
the font loads or if it fails. A family name may hold letters, digits, spaces
|
|
160
|
+
and `-`, `_`, `.`; a stylesheet address must be `https:`. Font licensing is the
|
|
161
|
+
deployment's responsibility.
|
|
162
|
+
|
|
163
|
+
### Cross-origin font loading
|
|
164
|
+
|
|
165
|
+
Browsers load a font from another origin only when that origin allows it with
|
|
166
|
+
CORS. Asset-library fonts are served by the API (`/assets/file/<id>` on the
|
|
167
|
+
public API address), which is usually a different origin from the storefront:
|
|
168
|
+
|
|
169
|
+
- **`CORS_ALLOWED_ORIGINS`** in the API's environment must include the
|
|
170
|
+
storefront's origin (for example `https://shop.example.com`). The
|
|
171
|
+
storefront's other browser calls already need it there. The Brand screen's
|
|
172
|
+
preview and the Page Builder canvas load the same files from the admin, so
|
|
173
|
+
an admin served from another origin than the API needs its origin in the
|
|
174
|
+
list too — which its own API calls already require.
|
|
175
|
+
- **Cloud storage**: when the Assets Library's storage backend answers with a
|
|
176
|
+
redirect to a bucket URL, the bucket itself must send CORS headers that allow
|
|
177
|
+
the storefront and admin origins. Configure that on the bucket.
|
|
178
|
+
- **Font services** send their own CORS headers; nothing is needed on your
|
|
179
|
+
side.
|
|
180
|
+
|
|
181
|
+
A font blocked by CORS does not break the page: the fallback family is used.
|
|
182
|
+
|
|
183
|
+
## Saving, auditing and caching
|
|
184
|
+
|
|
185
|
+
- **Concurrent edits**: each scope has a version. If someone else saved the
|
|
186
|
+
same scope since you loaded it, the save is refused, the latest version is
|
|
187
|
+
loaded, and your changes are not applied.
|
|
188
|
+
- **Validation**: a value out of range is refused and the fields are named.
|
|
189
|
+
- **Audit**: each save is one Command, `cms.brand_tokens.update`, with exactly
|
|
190
|
+
one audit entry on the object `cms_brand_tokens` (id `global` or the sales
|
|
191
|
+
channel's id) carrying the settings before and after.
|
|
192
|
+
- **Storefront**: after the save commits, the storefront cache tag
|
|
193
|
+
`cms:brand` is revalidated, so the next request uses the new settings. If
|
|
194
|
+
revalidation is not configured or fails, the storefront picks the change up
|
|
195
|
+
within five minutes. The manual cache flush in Settings revalidates the same
|
|
196
|
+
tag (namespace `cms-brand`).
|
|
197
|
+
|
|
198
|
+
## For engineers
|
|
199
|
+
|
|
200
|
+
### Where the settings live
|
|
201
|
+
|
|
202
|
+
- **Table** `cms_brand_tokens`, owned by the `cms` module: one row per scope,
|
|
203
|
+
`sales_channel_id` null for the global row (unique, nulls not distinct),
|
|
204
|
+
`tokens` (JSONB, a complete set), `version`, `updated_at`. Reset deletes the
|
|
205
|
+
scope's row.
|
|
206
|
+
- **Schema** `cmsBrandTokensSchema`, the built-in set `DEFAULT_BRAND_TOKENS`
|
|
207
|
+
and the contrast check `assessBrandContrast` in
|
|
208
|
+
`packages/contracts/src/cms-brand.ts`. The dark scheme's backdrop is
|
|
209
|
+
`schemes.dark.decorativeAssetId` (a library asset) or
|
|
210
|
+
`schemes.dark.decorativeUrl` (`brandMediaUrlSchema`: `https:` or a path
|
|
211
|
+
starting with `/`, at most 2048 characters, with no quotes, parentheses,
|
|
212
|
+
backslashes, angle brackets or whitespace); the asset wins when both are set.
|
|
213
|
+
How a section or a group draws it is that block's: `decorativeSize`,
|
|
214
|
+
`decorativeRepeat` and `decorativePosition` of its `background` value
|
|
215
|
+
(`sectionBackgroundSchema` in `packages/contracts/src/page-builder-props.ts`),
|
|
216
|
+
written inline as `background-size`, `background-repeat` and
|
|
217
|
+
`background-position` over the stylesheet's `cover`, `no-repeat` and
|
|
218
|
+
`top center`.
|
|
219
|
+
- **Service** `src/backend/services/brand-tokens-service.ts` and the screen
|
|
220
|
+
`src/admin/pages/BrandPage.tsx`, both in the `cms` module's package.
|
|
221
|
+
|
|
222
|
+
### HTTP
|
|
223
|
+
|
|
224
|
+
| Method and path | Gate | Answers |
|
|
225
|
+
| --- | --- | --- |
|
|
226
|
+
| `GET /api/v1/admin/cms/brand-tokens[?salesChannelId=]` | `cms.read` | `{global, channel?, effective, warnings}` |
|
|
227
|
+
| `PUT /api/v1/admin/cms/brand-tokens` | `cms.brand` | Body `{scope: {kind: 'all'} \| {kind: 'channel', salesChannelId}, tokens \| null, expectedVersion}`; `200 {version, warnings}`, `409 VERSION_CONFLICT`, `400 VALIDATION_FAILED`, `404 UNKNOWN_SALES_CHANNEL`. `tokens: null` removes a channel override, or resets the global set to the built-in values. |
|
|
228
|
+
| `GET /api/v1/storefront/cms/brand-tokens` | public | The effective set of the resolved sales channel (the system default channel without a header); `cache-control: public, max-age=60`. |
|
|
229
|
+
| `GET /api/v1/admin/cms/page-builder/config?salesChannelId=` | `cms.read` | The descriptor's `brandTokens`, used by the editor preview. |
|
|
230
|
+
|
|
231
|
+
### Tokens as CSS variables
|
|
232
|
+
|
|
233
|
+
`brandTokensToCss(tokens, {assetUrl, mediaUrl})` in `@endora-commerce/cms-components`
|
|
234
|
+
(`packages/cms-components/src/brand/brand-css.ts`) turns a set into CSS
|
|
235
|
+
variables plus the font links. The storefront renders the result server-side
|
|
236
|
+
in `<head>` as `<style id="cmsb">` (`storefront/lib/theme/StorefrontDocument.tsx`),
|
|
237
|
+
fetched in `getServerContext()` with `revalidate: 300` and the tag `cms:brand`.
|
|
238
|
+
The admin injects the same output into the Page Builder iframe and into the
|
|
239
|
+
Brand screen's preview. Both pass `mediaUrl`, which rebases a backdrop URL
|
|
240
|
+
starting with `/` onto the public API address, as they do a relative video URL.
|
|
241
|
+
|
|
242
|
+
| Variables | From |
|
|
243
|
+
| --- | --- |
|
|
244
|
+
| `--cmsb-color-primary`, `-primary-hover`, `-secondary`, `-secondary-hover`, `-on-primary`, `-on-secondary` | Colours |
|
|
245
|
+
| `--cmsb-n-50` … `--cmsb-n-900` | Neutral scale |
|
|
246
|
+
| `--cmsb-grad` | Accent gradient |
|
|
247
|
+
| `--cmsb-fg`, `--cmsb-bg`, `--cmsb-fg-muted`, `--cmsb-border`, `--cmsb-link`, `--cmsb-decorative` | The light scheme on `:root`, rebound by each `[data-cmsb-scheme="light\|muted\|dark"]` rule |
|
|
248
|
+
| `--cmsb-font-heading`, `--cmsb-font-body` | Fonts |
|
|
249
|
+
| `--cmsb-t-<token>-size`, `-lh`, `-w`, `-ls`, `-font` | Type scale (`display`, `h1`–`h6`, `lead`, `body`, `small`) |
|
|
250
|
+
| `--cmsb-btn-radius`, `--cmsb-btn-h-s`, `-h-m`, `-h-l`, `--cmsb-btn-weight`, `--cmsb-btn-transform` | Buttons |
|
|
251
|
+
| `--cmsb-space-<step>` | Spacing (`none` … `xxl`) |
|
|
252
|
+
| `--cmsb-container`, `--cmsb-wide`, `--cmsb-gutter` | Layout |
|
|
253
|
+
|
|
254
|
+
Sizes that differ on desktop are rebound inside one
|
|
255
|
+
`@media (min-width: 1024px)` block. With a tablet factor other than 1
|
|
256
|
+
(`tierScale.tablet`), a `@media (min-width: 768px) and (max-width: 1023.98px)`
|
|
257
|
+
block before it rebinds every `--cmsb-t-<token>-size` and `--cmsb-space-<step>`
|
|
258
|
+
to the mobile value times the factor; with a small-desktop factor
|
|
259
|
+
(`tierScale.smallDesktop`), a `@media (min-width: 1024px) and (max-width:
|
|
260
|
+
1279.98px)` block after it does the same from the desktop values. The gutter
|
|
261
|
+
and the container are not scaled. Without factors neither block is written,
|
|
262
|
+
so the output is byte for byte the same as before. Two further optional
|
|
263
|
+
settings extend these blocks (each writes nothing while unset):
|
|
264
|
+
|
|
265
|
+
- `tierScale.fluidDesktop: true`, with a small-desktop factor below 1, adds a
|
|
266
|
+
block from the small-desktop end to `tierScale.fluidUntilPx` (else
|
|
267
|
+
`layout.containerMaxPx`) where every desktop type size and spacing step is
|
|
268
|
+
`clamp(<value × factor>px, <value × 100 / end>vw, <value>px)` — the factor
|
|
269
|
+
rising with the window width to 1 at the end;
|
|
270
|
+
- `tierScale.buttons: true` writes `--cmsb-btn-h-s|m|l` into the tablet,
|
|
271
|
+
small-desktop and fluid blocks too, scaled the same way.
|
|
272
|
+
|
|
273
|
+
The small-desktop range always ends at 1279.98 px, as every block's
|
|
274
|
+
stylesheet assumes, and the gutter and the page container are the same at
|
|
275
|
+
every tier between phone and desktop. A block's own **Custom (px)** values are
|
|
276
|
+
written as literal px and are not scaled. Keys an earlier draft of this screen
|
|
277
|
+
stored (`smallDesktopUntilPx`, `blockPx`, `buttonLabels`, the per-tier
|
|
278
|
+
gutters and container, `fluidContainer`, `breadcrumbsPaddingYPx`,
|
|
279
|
+
`trackingMobileEm`) are dropped the next time the brand is saved and write
|
|
280
|
+
nothing meanwhile. For each heading level `h1`–`h6` whose
|
|
281
|
+
type style is set, the output also holds one rule giving that level's headings
|
|
282
|
+
inside rich text (`.cmsc-pb-rich-content`, `.cmsc-pb-rich`,
|
|
283
|
+
`.cmsc-pb-hero__body`, `.cmsc-pb-feature-list__body`) the level's size, line
|
|
284
|
+
height, weight and letter spacing. It is written here rather than in the
|
|
285
|
+
stylesheet because, with no brand, a rich body's headings take the host page's
|
|
286
|
+
own heading styles, which no fallback literal could restate. The storefront also sets
|
|
287
|
+
`--cmsb-header-offset`, the height of its sticky header, which anchored
|
|
288
|
+
sections use as their `scroll-margin-top`.
|
|
289
|
+
|
|
290
|
+
**Every use carries a fallback.** `packages/cms-components/styles/cms-components.css`
|
|
291
|
+
reads each variable as `var(--cmsb-…, <built-in literal>)`, and the built-in
|
|
292
|
+
literals equal `DEFAULT_BRAND_TOKENS`. A page rendered without
|
|
293
|
+
`<style id="cmsb">` — the `cms` module switched off, a failed read, or the
|
|
294
|
+
e-mail editor, which shares the stylesheet — therefore looks exactly as it did
|
|
295
|
+
before brand settings existed. The fallback-parity test
|
|
296
|
+
(`packages/cms-components/src/brand/fallback-parity.test.tsx`) holds that.
|
|
297
|
+
A block author writes the same way; see *Brand variables* in the
|
|
298
|
+
[Extending the Page Builder](./extending-page-builder.md) guide.
|
|
299
|
+
|
|
300
|
+
`brandTokensToCss` treats the set as untrusted: a non-hex colour, a family name
|
|
301
|
+
outside the allowed alphabet, a non-`https:` stylesheet address or a backdrop
|
|
302
|
+
URL the schema would refuse is dropped (the fallback then applies), asset and
|
|
303
|
+
backdrop URLs are written as escaped CSS strings, and no `<` can reach the
|
|
304
|
+
output.
|
|
305
|
+
|
|
306
|
+
### When the module is off
|
|
307
|
+
|
|
308
|
+
While `cms` is switched off, its brand routes do not answer, the storefront
|
|
309
|
+
renders without `<style id="cmsb">` and the fallbacks apply. The stored rows
|
|
310
|
+
are kept and apply again when the module is switched back on.
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Contact form
|
|
3
|
+
sidebar_label: Contact form
|
|
4
|
+
sidebar_position: 5
|
|
5
|
+
description: A Page Builder block that e-mails a visitor's message to the addresses set per sales channel, with optional newsletter sign-up, and stores nothing
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Contact form
|
|
9
|
+
|
|
10
|
+
The **Contact form** block (`cms.ContactForm`) puts a contact form on any Page Builder page.
|
|
11
|
+
A visitor fills it in, and the shop receives the message by e-mail at the addresses you set
|
|
12
|
+
for the sales channel. **Nothing is stored**: there is no list of submissions in the admin
|
|
13
|
+
and no table of messages — the e-mail in your inbox is the only copy.
|
|
14
|
+
|
|
15
|
+
The block is different from **Contact / form embed** (`cms.ContactFormEmbed`), which shows a
|
|
16
|
+
form hosted somewhere else in a frame.
|
|
17
|
+
|
|
18
|
+
## Before you start: who receives the messages
|
|
19
|
+
|
|
20
|
+
The recipients are a setting, not part of the page, so an address never appears in the
|
|
21
|
+
page's content or anywhere on the storefront.
|
|
22
|
+
|
|
23
|
+
- **Where**: **Settings** → group **Contact form** → **Contact form recipients**.
|
|
24
|
+
- **Command palette**: ⌘K / CTRL+K → "Contact form recipients" (also found by *contact*,
|
|
25
|
+
*form*, *recipients*, *kontakt* or *formularz*).
|
|
26
|
+
- **Permissions**: reading the Settings screen needs **View settings** (`settings:read`);
|
|
27
|
+
changing a value needs **Edit settings** (`settings:write`).
|
|
28
|
+
- **Per sales channel**: set one list for all channels, or override it for a single channel.
|
|
29
|
+
The form sends to the list of the channel the visitor is shopping on.
|
|
30
|
+
- **Rules**: at most 10 addresses, each a valid e-mail address. Anything else is refused
|
|
31
|
+
when you save.
|
|
32
|
+
|
|
33
|
+
While a channel has no recipients, the form on that channel answers that it is unavailable,
|
|
34
|
+
and the visitor sees the block's "Unavailable" message.
|
|
35
|
+
|
|
36
|
+
## Building a contact page
|
|
37
|
+
|
|
38
|
+
A typical contact page is made of blocks that already exist:
|
|
39
|
+
|
|
40
|
+
1. A **Section** with a **Row** of two **Columns**.
|
|
41
|
+
2. In the first column, a **Heading** and a short **Rich content** lead, then the **Contact
|
|
42
|
+
form**.
|
|
43
|
+
3. In the second column, the contact details (addresses, phone numbers, opening hours) as
|
|
44
|
+
**Rich content**, or a **Map**.
|
|
45
|
+
4. Optionally a **Tabs** block with two tabs — "Contact form" holding the **Contact form**
|
|
46
|
+
and "Newsletter" holding the **Newsletter sign-up** block (when the newsletter module is
|
|
47
|
+
installed).
|
|
48
|
+
|
|
49
|
+
Give the Section an anchor if you link to the form from elsewhere on the page; after a
|
|
50
|
+
visitor sends the form without JavaScript, the browser returns to that anchor.
|
|
51
|
+
|
|
52
|
+
## Fields
|
|
53
|
+
|
|
54
|
+
The field set is fixed — the server knows every field, so it can check what arrives:
|
|
55
|
+
|
|
56
|
+
| Field | Shown | Required |
|
|
57
|
+
| --- | --- | --- |
|
|
58
|
+
| Name | by default | optional |
|
|
59
|
+
| E-mail | always | always |
|
|
60
|
+
| Phone | on request | optional |
|
|
61
|
+
| Company | on request | optional |
|
|
62
|
+
| Subject | on request | optional |
|
|
63
|
+
| Select (a list you define, e.g. regions or departments) | on request | optional |
|
|
64
|
+
| Message | always | always |
|
|
65
|
+
| Privacy consent | always | always |
|
|
66
|
+
| Marketing consent | on request | never |
|
|
67
|
+
|
|
68
|
+
For every field you can change the **label** and the **placeholder**; for the optional ones
|
|
69
|
+
also **Show** and **Required**. The select needs at least one option — without one it is
|
|
70
|
+
not shown. Its chosen option is sent with the select's label, so the e-mail reads, for
|
|
71
|
+
example, "Region: North".
|
|
72
|
+
|
|
73
|
+
Labels you leave empty show the storefront's own wording in the page's language.
|
|
74
|
+
|
|
75
|
+
**Privacy consent**: write its label and link it to your privacy policy — the editor shows a
|
|
76
|
+
warning until you do. Until then the visitor reads a short default sentence without a link.
|
|
77
|
+
|
|
78
|
+
**Marketing consent**: switch it on to ask whether the visitor wants news and offers. See
|
|
79
|
+
[Newsletter sign-up from the form](#newsletter-sign-up-from-the-form).
|
|
80
|
+
|
|
81
|
+
## Layout and look
|
|
82
|
+
|
|
83
|
+
The block follows the colour scheme of the section it is in. The options are presets, so a
|
|
84
|
+
page looks right without measurements:
|
|
85
|
+
|
|
86
|
+
- **Columns** — one, or two from tablet width up (one on phones). With two columns, each
|
|
87
|
+
field's **Width** is half or full; the message is full width unless you change it.
|
|
88
|
+
- **Labels** — above the field, or hidden. Hidden labels are still read by screen readers,
|
|
89
|
+
and the label is shown as the placeholder when you wrote none.
|
|
90
|
+
- **Field look** — **Boxed** (a frame), **Underline** (a line under the field) or **Pill**
|
|
91
|
+
(fully rounded; the message box keeps softer corners).
|
|
92
|
+
- **Button** — the same look options as every other Page Builder button (style, fill, size,
|
|
93
|
+
icon) and its own label. **Button alignment** places it at the start, centre or end, or
|
|
94
|
+
makes it full width.
|
|
95
|
+
- **Messages** — the texts shown after sending: **Sent**, **Not accepted** (the server
|
|
96
|
+
refused what was sent) and **Unavailable** (no recipients, too many attempts, or a
|
|
97
|
+
temporary failure).
|
|
98
|
+
- **Form name** — the name screen readers announce for the form.
|
|
99
|
+
- Outer and inner spacing, border, and hiding the block per screen size work as on every
|
|
100
|
+
block.
|
|
101
|
+
|
|
102
|
+
## What happens when a visitor sends the form
|
|
103
|
+
|
|
104
|
+
1. With JavaScript, the form checks the required fields and the e-mail address first, marks
|
|
105
|
+
each field to correct and moves the focus to the first one. What the visitor typed is
|
|
106
|
+
kept until the message is sent.
|
|
107
|
+
2. The storefront passes the message to the shop's server, which checks it again —
|
|
108
|
+
whatever the block's settings, the server always requires an e-mail address, a message
|
|
109
|
+
(up to 5 000 characters) and the privacy consent.
|
|
110
|
+
3. The server sends **one e-mail per recipient** of the visitor's sales channel, through the
|
|
111
|
+
platform's mail transport. The e-mail is written in the channel's default language and
|
|
112
|
+
lists the fields that were filled in, the page the form was sent from and both consents.
|
|
113
|
+
Its **Reply-To** is the visitor's address, so answering it reaches the visitor.
|
|
114
|
+
4. The visitor sees the **Sent** message. Without JavaScript, the browser comes back to the
|
|
115
|
+
same page, in the same language, scrolled to the form.
|
|
116
|
+
|
|
117
|
+
**What is kept**: the platform's e-mail delivery record notes that a message of kind
|
|
118
|
+
`cms.contact_form` went to a recipient, with a fixed subject (the channel's name, never the
|
|
119
|
+
visitor's text) and the outcome. Nothing the visitor typed is stored anywhere.
|
|
120
|
+
|
|
121
|
+
## Newsletter sign-up from the form
|
|
122
|
+
|
|
123
|
+
When the marketing consent is ticked and the message is sent, the storefront also signs the
|
|
124
|
+
address up to the newsletter of the visitor's sales channel — if the newsletter module is
|
|
125
|
+
installed and switched on. The channel's own opt-in rules apply, so with double opt-in the
|
|
126
|
+
visitor receives a confirmation e-mail first. The subscription is recorded with the source
|
|
127
|
+
`cms-contact-form`. If the sign-up fails, the message has still been sent.
|
|
128
|
+
|
|
129
|
+
Without the newsletter module, the consent is only stated in the e-mail you receive.
|
|
130
|
+
|
|
131
|
+
## Protection against abuse
|
|
132
|
+
|
|
133
|
+
- **Rate limit** — at most 10 submissions per visitor address in 10 minutes; the eleventh
|
|
134
|
+
is refused and the visitor sees the "Unavailable" message.
|
|
135
|
+
- **Hidden trap field** — a field people never see. A bot that fills it is told the message
|
|
136
|
+
was sent, and nothing is sent.
|
|
137
|
+
- **Behind a proxy** — the reference storefront calls the server on the visitor's behalf
|
|
138
|
+
and forwards the visitor's address in `X-Forwarded-For`. The server only counts that
|
|
139
|
+
address when it trusts the storefront as a proxy: set `TRUSTED_PROXY_HOPS` or
|
|
140
|
+
`TRUSTED_PROXY_ADDRESSES` for your deployment. Without it, every visitor shares the
|
|
141
|
+
storefront's address and the limit applies to all of them together.
|
|
142
|
+
|
|
143
|
+
## For developers: the endpoint
|
|
144
|
+
|
|
145
|
+
The storefront handler is `POST /forms/contact` (a plain form post answered with `303` back
|
|
146
|
+
to the page, or JSON when the request accepts it). It calls the public endpoint:
|
|
147
|
+
|
|
148
|
+
`POST /api/v1/storefront/cms/contact-form` — body checked against
|
|
149
|
+
`contactFormSubmissionSchema` in `@endora-commerce/contracts`; unknown keys are refused.
|
|
150
|
+
|
|
151
|
+
| Outcome | Status |
|
|
152
|
+
| --- | --- |
|
|
153
|
+
| Sent (also when the trap field is filled) | `200` `{ "data": { "status": "sent" } }` |
|
|
154
|
+
| The body does not match the contract | `400` `VALIDATION_FAILED` |
|
|
155
|
+
| No recipients for the request's sales channel | `409` `CMS_CONTACT_FORM_UNAVAILABLE` |
|
|
156
|
+
| Too many submissions from one address | `429` |
|
|
157
|
+
| Every send failed | `500` `INTERNAL` |
|
|
158
|
+
| The CMS module is switched off | `503` `MODULE_DISABLED` |
|
|
159
|
+
|
|
160
|
+
The answer never contains the recipients or the submitted values. With the CMS module
|
|
161
|
+
switched off the block disappears from every page and the storefront handler answers `404`.
|