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

feat(19.6.1-02): field trigger and admin build

Browse Source 
- fields.yaml trigger (action disable|hide, field, condition checked|unchecked) compiled to FormField.Trigger
- boot errors for malformed triggers, controlling fields that are not a switch or checkbox, and triggers in repeater rows, settings and relation forms
- Administrators permissions overrides are disabled while Superuser is on (D-06)
- SPA: trigger.ts (triggerState, applyTriggers), FORM_TRIGGER_NOTES, the trigger note in FormField, FormView tabs/banner/payload after triggers, PreviewView hide only
- regenerated admin OpenAPI and schema.d.ts; rebuilt modules/boardwalk/dist; docs and README
This commit is contained in:
Jakub Zych
2026-10-22 11:43:58 +02:00
parent 705f94d9e5
commit 7091d09699
27 changed files with 501 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/backend/forms.md
View File

@@ -110,7 +110,7 @@ The WinterCMS widgets that are not in this list (the code editor, the color pick
### Field options
A field takes `label`, `comment`, `type`, `required`, `default`, `tab`, `span` (`left`, `right`, `full`, `auto`, `row`), `size` (`tiny`, `small`, `large`, `huge`, `giant`), `context`, `attributes` (scalar HTML attributes for the input), `options` and `emptyOption`, plus `nameFrom` and `relation` on relation fields, `preset` on text and mltext fields, `dependsOn` on dropdowns (see [Dependent dropdowns](#dependent-dropdowns)), `currency`, `currencyFrom`, `scale` and `max` on money fields (see [Money](#money)), and `mode`, `separator` and `customTags` on taglist fields (see [Taglist](#taglist)). WinterCMS keys outside this set, such as `readOnly`, `disabled` or `trigger`, are refused.
A field takes `label`, `comment`, `type`, `required`, `default`, `tab`, `span` (`left`, `right`, `full`, `auto`, `row`), `size` (`tiny`, `small`, `large`, `huge`, `giant`), `context`, `attributes` (scalar HTML attributes for the input), `options` and `emptyOption`, plus `nameFrom` and `relation` on relation fields, `preset` on text and mltext fields, `dependsOn` on dropdowns (see [Dependent dropdowns](#dependent-dropdowns)), `currency`, `currencyFrom`, `scale` and `max` on money fields (see [Money](#money)), `mode`, `separator` and `customTags` on taglist fields (see [Taglist](#taglist)), and `trigger` (see [Triggers](#triggers)). WinterCMS keys outside this set, such as `readOnly` or `disabled`, are refused.
`context: update` shows a field only on the update form, and `context: create` only on the create form; a list of contexts is also accepted, and `context: preview` shows a field only on the [preview screen](#preview-screen). The context is enforced on the server too: a field that is hidden on a form is never written by that form's save, whatever the request body holds.
@@ -131,6 +131,33 @@ Multilingual pairs follow the locale the administrator works in. An `mltext` tar
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`.
### Triggers
`trigger` disables or hides a field while a switch or checkbox of the same form is on or off, WinterCMS's field trigger. The Administrators form uses it to make the permission overrides read-only while the Superuser switch is on, because a superuser holds every permission anyway:
```yaml
permissions:
label: backend::lang.user.permission_overrides
type: permissioneditor
mode: radio
trigger:
action: disable
field: is_superuser
condition: checked
```
| Key | Values |
|-----|--------|
| `action` | `disable` shows the field read-only with a note above the control ("Not editable while “Superuser” is on."); `hide` removes it from the form, and a tab whose every field is hidden disappears. |
| `field` | Another field of the same form, of type `switch` or `checkbox` (a virtual switch counts). |
| `condition` | `checked`: the trigger acts while the field is on; `unchecked`: while it is off. |
The admin evaluates the trigger against the whole form's values on every change, so the controlling field may sit on another tab. A controlling field that is not in the form for this request (removed for this administrator, or excluded by its `context`) counts as off. The preview screen applies `hide` only.
A disabled or hidden field is left out of the save body, so the server keeps its stored value; values typed before the field was disabled stay in the form and return when it is enabled. The trigger is a display rule only: the server does not evaluate it, and every rule that must hold is enforced in the save, whatever the client sends.
The mapping must hold exactly `action`, `field` and `condition`. A missing or extra key, another action or condition (WinterCMS's `value[...]` is not supported), a `field` that names no field of the form, names the field itself or names a field that is not a switch or checkbox stops the start-up with an error naming the controller, the field and the key. Triggers are evaluated on controller forms only: repeater rows, settings forms and relation forms refuse the key.
## Dependent dropdowns
A `type: dropdown` field with `dependsOn` takes its options from the value of a sibling field, WinterCMS's dependent dropdown. A menu entry's reference dropdown, for example, lists the posts when its type dropdown says "post" and the categories when it says "category":