From 164d382395dc7d9563e7b7208103bc334a973cc5 Mon Sep 17 00:00:00 2001 From: Private Maker Date: Tue, 23 Jan 2024 01:11:57 +0100 Subject: [PATCH 1/2] Update Docs: migrate Beta Features - List Widget: Variable Types --- website/content/docs/beta-features.md | 83 +----------------------- website/content/docs/widgets/variable.md | 82 +++++++++++++++++++++++ 2 files changed, 83 insertions(+), 82 deletions(-) create mode 100644 website/content/docs/widgets/variable.md diff --git a/website/content/docs/beta-features.md b/website/content/docs/beta-features.md index fea7a8919635..4da47eaa5837 100644 --- a/website/content/docs/beta-features.md +++ b/website/content/docs/beta-features.md @@ -23,87 +23,6 @@ In order to track unpublished entries statuses the GitLab implementation uses me - -## List Widget: Variable Types - -Before this feature, the [list widget](/docs/widgets/#list) allowed a set of fields to be repeated, but every list item had the same set of fields available. With variable types, multiple named sets of fields can be defined, which opens the door to highly flexible content authoring (even page building) in Decap CMS. - -**Note: this feature does not yet support default previews and requires [registering a preview template](/docs/customization#registerpreviewtemplate) in order to show up in the preview pane.** - -To use variable types in the list widget, update your field configuration as follows: - -1. Instead of defining your list fields under `fields` or `field`, define them under `types`. Similar to `fields`, `types` must be an array of field definition objects. -2. Each field definition under `types` must use the `object` widget (this is the default value for - `widget`). - -### Additional list widget options - -* `types`: a nested list of object widgets. All widgets must be of type `object`. Every object widget may define different set of fields. -* `typeKey`: the name of the field that will be added to every item in list representing the name of the object widget that item belongs to. Ignored if `types` is not defined. Default is `type`. -* `summary`: allows customization of a collapsed list item object in a similar way to a [collection summary](/docs/configuration-options/?#summary) - -### Example Configuration - -The example configuration below imagines a scenario where the editor can add two "types" of content, -either a "carousel" or a "spotlight". Each type has a unique name and set of fields. - -```yaml -- label: 'Home Section' - name: 'sections' - widget: 'list' - types: - - label: 'Carousel' - name: 'carousel' - widget: object - summary: '{{fields.header}}' - fields: - - { label: Header, name: header, widget: string, default: 'Image Gallery' } - - { label: Template, name: template, widget: string, default: 'carousel.html' } - - label: Images - name: images - widget: list - field: { label: Image, name: image, widget: image } - - label: 'Spotlight' - name: 'spotlight' - widget: object - fields: - - { label: Header, name: header, widget: string, default: 'Spotlight' } - - { label: Template, name: template, widget: string, default: 'spotlight.html' } - - { label: Text, name: text, widget: text, default: 'Hello World' } -``` - -### Example Output - -The output for the list widget will be an array of objects, and each object will have a `type` key -with the name of the type used for the list item. The `type` key name can be customized via the -`typeKey` property in the list configuration. - -If the above example configuration were used to create a carousel, a spotlight, and another -carousel, the output could look like this: - -```yaml -title: Home -sections: - - type: carousel - header: Image Gallery - template: carousel.html - images: - - images/image01.png - - images/image02.png - - images/image03.png - - type: spotlight - header: Spotlight - template: spotlight.html - text: Hello World - - type: carousel - header: Image Gallery - template: carousel.html - images: - - images/image04.png - - images/image05.png - - images/image06.png -``` - ## Custom Mount Element Decap CMS always creates its own DOM element for mounting the application, which means it always takes over the entire page, and is generally inflexible if you're trying to do something creative, like injecting it into a shared context. @@ -377,4 +296,4 @@ CMS.registerCustomFormat('yml', 'yml', { fromFile: text => jsYaml.load(text), toFile: value => jsYaml.dump(value), }); -``` \ No newline at end of file +``` diff --git a/website/content/docs/widgets/variable.md b/website/content/docs/widgets/variable.md new file mode 100644 index 000000000000..7329659a648e --- /dev/null +++ b/website/content/docs/widgets/variable.md @@ -0,0 +1,82 @@ +--- +label: "Variables" +title: variables +--- + +Before this feature, the [list widget](/docs/widgets/#list) allowed a set of fields to be repeated, but every list item had the same set of fields available. With variable types, multiple named sets of fields can be defined, which opens the door to highly flexible content authoring (even page building) in Decap CMS. + +**Note: this feature does not yet support default previews and requires [registering a preview template](/docs/customization#registerpreviewtemplate) in order to show up in the preview pane.** + +To use variable types in the list widget, update your field configuration as follows: + +1. Instead of defining your list fields under `fields` or `field`, define them under `types`. Similar to `fields`, `types` must be an array of field definition objects. +2. Each field definition under `types` must use the `object` widget (this is the default value for + `widget`). + +### Additional list widget options + +* `types`: a nested list of object widgets. All widgets must be of type `object`. Every object widget may define different set of fields. +* `typeKey`: the name of the field that will be added to every item in list representing the name of the object widget that item belongs to. Ignored if `types` is not defined. Default is `type`. +* `summary`: allows customization of a collapsed list item object in a similar way to a [collection summary](/docs/configuration-options/?#summary) + +### Example Configuration + +The example configuration below imagines a scenario where the editor can add two "types" of content, +either a "carousel" or a "spotlight". Each type has a unique name and set of fields. + +```yaml +- label: 'Home Section' + name: 'sections' + widget: 'list' + types: + - label: 'Carousel' + name: 'carousel' + widget: object + summary: '{{fields.header}}' + fields: + - { label: Header, name: header, widget: string, default: 'Image Gallery' } + - { label: Template, name: template, widget: string, default: 'carousel.html' } + - label: Images + name: images + widget: list + field: { label: Image, name: image, widget: image } + - label: 'Spotlight' + name: 'spotlight' + widget: object + fields: + - { label: Header, name: header, widget: string, default: 'Spotlight' } + - { label: Template, name: template, widget: string, default: 'spotlight.html' } + - { label: Text, name: text, widget: text, default: 'Hello World' } +``` + +### Example Output + +The output for the list widget will be an array of objects, and each object will have a `type` key +with the name of the type used for the list item. The `type` key name can be customized via the +`typeKey` property in the list configuration. + +If the above example configuration were used to create a carousel, a spotlight, and another +carousel, the output could look like this: + +```yaml +title: Home +sections: + - type: carousel + header: Image Gallery + template: carousel.html + images: + - images/image01.png + - images/image02.png + - images/image03.png + - type: spotlight + header: Spotlight + template: spotlight.html + text: Hello World + - type: carousel + header: Image Gallery + template: carousel.html + images: + - images/image04.png + - images/image05.png + - images/image06.png +``` From 3f9e426688122599e78f4a5fa28088b5f8ecdeb1 Mon Sep 17 00:00:00 2001 From: Private Maker Date: Tue, 23 Jan 2024 11:35:02 +0100 Subject: [PATCH 2/2] Update Docs: make page Variable Type Widgets --- .../docs/{widgets/variable.md => variable-type-widgets.md} | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) rename website/content/docs/{widgets/variable.md => variable-type-widgets.md} (98%) diff --git a/website/content/docs/widgets/variable.md b/website/content/docs/variable-type-widgets.md similarity index 98% rename from website/content/docs/widgets/variable.md rename to website/content/docs/variable-type-widgets.md index 7329659a648e..7415467dfa04 100644 --- a/website/content/docs/widgets/variable.md +++ b/website/content/docs/variable-type-widgets.md @@ -1,6 +1,7 @@ --- -label: "Variables" -title: variables +label: "Variable Type Widgets" +group: Fields +weight: 30 --- Before this feature, the [list widget](/docs/widgets/#list) allowed a set of fields to be repeated, but every list item had the same set of fields available. With variable types, multiple named sets of fields can be defined, which opens the door to highly flexible content authoring (even page building) in Decap CMS.