golem15/summercms
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(cabana): document mltextarea field type

Browse Source 
- forms.md: field-types row, ML section and example, lift paragraph,
  preset refusal
- admin-controllers.md and the cabana README name mltextarea
This commit is contained in:
Jakub Zych
2026-10-06 21:37:08 +02:00
parent a913eec50f
commit aa3a7c2e90
3 changed files with 12 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/backend/admin-controllers.md
View File

@@ -202,7 +202,7 @@ Every controller gets the same routes, relative to `<prefix>/api/v1/{vendor}/{pl
The cabana README lists the full route table, including relation, options, widget, toolbar and partial routes. Every response uses one JSON envelope (`cabana.Envelope`), and a validation failure is a 422 `validation_failed` error with messages per field.
Request parameters never reach SQL directly: search, sort and filters apply only to declared columns, and a write passes only the form's writable fields, filled through `lagoon.Fill` and validated through `lagoon.Validate` in a transaction. A `mltext` or `mlmarkdown` field arrives as a nested locale map: cabana lifts it before `cabana.ProjectWritableFields` drops nested values, writes the default locale as the host scalar, and calls a published `cabana.TranslationWriter` for the other locales inside the same permissioned save transaction. The show and save record payload then carries that nested map for every enabled locale (`hydrateMLRecord` via `TranslationWriter.TranslatedExact`; missing non-default codes stay empty). There is no separate translate-write or translate-read route; see [Markdown and multilingual fields](forms.md#markdown-and-multilingual-fields).
Request parameters never reach SQL directly: search, sort and filters apply only to declared columns, and a write passes only the form's writable fields, filled through `lagoon.Fill` and validated through `lagoon.Validate` in a transaction. An `mltext`, `mltextarea` or `mlmarkdown` field arrives as a nested locale map: cabana lifts it before `cabana.ProjectWritableFields` drops nested values, writes the default locale as the host scalar, and calls a published `cabana.TranslationWriter` for the other locales inside the same permissioned save transaction. The show and save record payload then carries that nested map for every enabled locale (`hydrateMLRecord` via `TranslationWriter.TranslatedExact`; missing non-default codes stay empty). There is no separate translate-write or translate-read route; see [Markdown and multilingual fields](forms.md#markdown-and-multilingual-fields).
## Hooks

11
docs/backend/forms.md
View File

@@ -99,6 +99,7 @@ for _, f := range form.Fields {
| `password` | A masked input with a show and hide button. It is a form-only field: the value is sent with a save and never returned; see [Form-only fields](#form-only-fields). |
| `markdown` | A source editor for a host text column, with a sanitized preview; see [Markdown and multilingual fields](#markdown-and-multilingual-fields). |
| `mltext` | A text field with one editor per locale; see [Markdown and multilingual fields](#markdown-and-multilingual-fields). |
| `mltextarea` | A multi-line text field with one editor per locale; it takes `size` as `textarea` does. See [Markdown and multilingual fields](#markdown-and-multilingual-fields). |
| `mlmarkdown` | A markdown field with one editor per locale; see [Markdown and multilingual fields](#markdown-and-multilingual-fields). |
The WinterCMS widgets that are not in this list (the rich editor, the code editor, the color picker, the media finder, the repeater, the tag list and the others) are not provided. A field with one of those types stops the start-up.
@@ -124,7 +125,7 @@ slug:
Multilingual pairs follow the locale the administrator works in. An `mltext` target follows an `mltext` source per locale: typing in one locale of the source rewrites the same locale of the target, and a hand edit of one locale of the target stops only that locale. An `mltext` source drives a `text` target from the active locale. A `text` source fills only the active locale of an `mltext` target, so locales nobody looked at stay empty.
A `preset` on another field type (`mlmarkdown` included), an unknown type, or a source that is not a text or mltext field of the same form stops the start-up, and the key is not accepted on settings forms or relation forms.
A `preset` on another field type (`mltextarea` and `mlmarkdown` included), an unknown type, or a source that is not a text or mltext field of the same form stops the start-up, and the key is not accepted on settings forms or relation forms. An `mltextarea` field is neither a preset target nor a preset source, like `textarea`.
## Date pickers
@@ -329,7 +330,7 @@ func (MembersController) AdminSetPermissionValues(_ context.Context, field strin
`type: markdown` edits markdown source on a host text column. The admin SPA shows a source editor with a Preview toggle. When Preview opens, and again shortly after the source changes while it is open, the SPA posts the field's source (the active locale's text for `mlmarkdown`) to the preview route below and renders only the server's answer; when the output is refused it shows the server's message as text. The server renders through `cabana.RenderMarkdown`, which uses the pinned goldmark engine without unsafe HTML. Output that still contains a script or iframe tag, an event handler, or a javascript, vbscript or data URL is refused, so translated raw HTML cannot become executable preview content. `POST <prefix>/api/v1/markdown/preview` renders a `{markdown}` source through `cabana.RenderMarkdown` for any signed-in administrator and answers `{html}`, or a 422 `validation_failed` on `markdown` when the output is refused.
`type: mltext` and `type: mlmarkdown` reuse the ordinary text and markdown editors with a locale selector. `mlmarkdown` composes the markdown control rather than a second parser. Each ML field shows its own selector; changing one selector changes every ML control on the form. Selector options come from `cabana.FormMeta.EnabledLocales` on the form schema (filled from `cabana.TranslationWriter.EnabledLocales` after Lookup; `FormSchema.Localize` stays cache-only). Create seeds `{[code]: ""}` for every enabled code. A GET or save of a host scalar is merged onto that seed so sibling locales are not dropped. An `mltext` field can carry a `preset`; it follows per locale as described under [Field options](#field-options).
`type: mltext`, `type: mltextarea` and `type: mlmarkdown` reuse the ordinary text, textarea and markdown editors with a locale selector. `mltextarea` takes `size` like `textarea`. `mlmarkdown` composes the markdown control rather than a second parser. Each ML field shows its own selector; changing one selector changes every ML control on the form. Selector options come from `cabana.FormMeta.EnabledLocales` on the form schema (filled from `cabana.TranslationWriter.EnabledLocales` after Lookup; `FormSchema.Localize` stays cache-only). Create seeds `{[code]: ""}` for every enabled code. A GET or save of a host scalar is merged onto that seed so sibling locales are not dropped. An `mltext` field can carry a `preset`; it follows per locale as described under [Field options](#field-options).
The save body sends every locale as a JSON object of code to string. Extra YAML keys are not accepted: the types reuse `label`, `comment`, `span`, `size`, `required`, `tab` and `context`. An unknown type such as `mlunknown` stops the start-up.
@@ -339,6 +340,10 @@ fields:
label: acme.blog::lang.posts.title
type: mltext
span: full
summary:
label: acme.blog::lang.posts.summary
type: mltextarea
size: small
excerpt:
label: acme.blog::lang.posts.excerpt
type: markdown
@@ -353,6 +358,6 @@ A save of `{ "title": { "en": "Hello", "pl": "Witaj" } }` lifts the nested map b
## What a save may write
The form's writable fields are bound to model columns at boot. A save passes only those fields that are also in the model's `Fillable` list, drops unknown keys, case variants and nested objects, and fills the model with `lagoon.Fill` (see [Models](../database/models.md)). Declared `mltext` and `mlmarkdown` locale maps are the exception: they are lifted first, as [Markdown and multilingual fields](#markdown-and-multilingual-fields). The model's validation rules (a `Rules` method returning `lagoon.Validate` rule strings) and the form's `required` flags are checked in the save's transaction, and a failure is a 422 with messages per field. A value that does not fit its column is also a 422 on that field. A controller implementing `pact.FormRules` supplies its own rule set per operation, which replaces the model's rules for admin saves.
The form's writable fields are bound to model columns at boot. A save passes only those fields that are also in the model's `Fillable` list, drops unknown keys, case variants and nested objects, and fills the model with `lagoon.Fill` (see [Models](../database/models.md)). Declared `mltext`, `mltextarea` and `mlmarkdown` locale maps are the exception: they are lifted first, as [Markdown and multilingual fields](#markdown-and-multilingual-fields). The model's validation rules (a `Rules` method returning `lagoon.Validate` rule strings) and the form's `required` flags are checked in the save's transaction, and a failure is a 422 with messages per field. A value that does not fit its column is also a 422 on that field. A controller implementing `pact.FormRules` supplies its own rule set per operation, which replaces the model's rules for admin saves.
[Form-only fields](#form-only-fields) are never written by cabana. Their submitted values are validated, when a rule names them, and handed to the controller's hooks; what is stored from them is the hook's decision.