diff --git a/core/src/interface.ts b/core/src/interface.ts index 6c391b40..25071da8 100644 --- a/core/src/interface.ts +++ b/core/src/interface.ts @@ -586,14 +586,13 @@ export interface ListField extends BaseField { allow_add?: boolean; collapsed?: boolean; summary?: string; - minimize_collapsed?: boolean; label_singular?: string; fields?: Field[]; max?: number; min?: number; add_to_top?: boolean; types?: ObjectField[]; - typeKey?: string; + type_key?: string; } export interface MapField extends BaseField { diff --git a/core/src/lib/widgets/validations.ts b/core/src/lib/widgets/validations.ts index ccfc6e98..9583cfb0 100644 --- a/core/src/lib/widgets/validations.ts +++ b/core/src/lib/widgets/validations.ts @@ -32,4 +32,6 @@ export function validateMinMax( } else if (isNumber(max) && length > max) { return minMaxError('rangeMax'); } + + return false; } diff --git a/core/src/widgets/list/schema.ts b/core/src/widgets/list/schema.ts index 9e0db2fa..12c135c0 100644 --- a/core/src/widgets/list/schema.ts +++ b/core/src/widgets/list/schema.ts @@ -3,7 +3,6 @@ export default { allow_add: { type: 'boolean' }, collapsed: { type: 'boolean' }, summary: { type: 'string' }, - minimize_collapsed: { type: 'boolean' }, label_singular: { type: 'string' }, i18n: { type: 'boolean' }, min: { type: 'number' }, diff --git a/core/src/widgets/list/typedListHelpers.ts b/core/src/widgets/list/typedListHelpers.ts index 2e780662..e89c063d 100644 --- a/core/src/widgets/list/typedListHelpers.ts +++ b/core/src/widgets/list/typedListHelpers.ts @@ -1,7 +1,7 @@ import type { ListField, ObjectField, ObjectValue } from '../../interface'; export const TYPES_KEY = 'types'; -export const TYPE_KEY = 'typeKey'; +export const TYPE_KEY = 'type_key'; export const DEFAULT_TYPE_KEY = 'type'; export function getTypedFieldForValue( diff --git a/website/content/docs/widget-boolean.mdx b/website/content/docs/widget-boolean.mdx index 1ad4d795..b4bf90ca 100644 --- a/website/content/docs/widget-boolean.mdx +++ b/website/content/docs/widget-boolean.mdx @@ -4,15 +4,21 @@ title: Boolean weight: 10 --- -The boolean widget translates a toggle switch input to a true/false value. +## Overview + +- **Name**: `boolean` +- **UI**: Toggle switch +- **Data type**: `boolean` + +The boolean widget translates a toggle switch input to a `true` or `false` value. ## Widget options For common options, see [Common widget options](/docs/widgets#common-widget-options). -|Name|Type|Default|Description| -|----|----|-------|-----------| -|default|boolean|`false`|_Optional_. The default value for the field| +| Name | Type | Default | Description | +| ------- | ------- | ------- | ------------------------------------------- | +| default | boolean | `false` | _Optional_. The default value for the field | ## Example diff --git a/website/content/docs/widget-code.mdx b/website/content/docs/widget-code.mdx index a8cdee56..b7a881cc 100644 --- a/website/content/docs/widget-code.mdx +++ b/website/content/docs/widget-code.mdx @@ -3,6 +3,11 @@ group: Widgets title: Code weight: 11 --- +## Overview + +- **Name**: `code` +- **UI**: Codemirror editor +- **Data type**: `string` or `{ code: 'My code here', lang: 'javascript' }` The code widget provides a code editor (powered by [Codemirror](https://codemirror.net)) with optional syntax awareness. Can output the raw code value or an object with the selected language and the raw code value. diff --git a/website/content/docs/widget-color.mdx b/website/content/docs/widget-color.mdx index 9cbefc46..10994305 100644 --- a/website/content/docs/widget-color.mdx +++ b/website/content/docs/widget-color.mdx @@ -3,6 +3,11 @@ group: Widgets title: Color weight: 12 --- +## Overview + +- **Name**: `color` +- **UI**: Color picker +- **Data type**: `string` The color widget translates a color picker to a color string. diff --git a/website/content/docs/widget-datetime.mdx b/website/content/docs/widget-datetime.mdx index 5e164302..f2e155e1 100644 --- a/website/content/docs/widget-datetime.mdx +++ b/website/content/docs/widget-datetime.mdx @@ -3,6 +3,11 @@ group: Widgets title: DateTime weight: 13 --- +## Overview + +- **Name**: `datetime` +- **UI**: Datetime picker +- **Data type**: [date-fns](https://date-fns.org/) formatted datetime string The datetime widget translates a datetime picker to a datetime string. diff --git a/website/content/docs/widget-file.mdx b/website/content/docs/widget-file.mdx index d9c8067b..7f43fc10 100644 --- a/website/content/docs/widget-file.mdx +++ b/website/content/docs/widget-file.mdx @@ -3,30 +3,42 @@ group: Widgets title: File weight: 14 --- +## Overview + +- **Name:** `file` +- **UI:** File picker button opens media gallery +- **Data type:** File path string + The file widget allows editors to upload a file or select an existing one from the media library. The path to the file will be saved to the field as a string. -* **Name:** `file` -* **UI:** file picker button opens media gallery -* **Data type:** file path string -* **Options:** +## Widget options - * `default`: accepts a file path string; defaults to null - * `media_library`: media library settings to apply when a media library is opened by the - current widget +For common options, see [Common widget options](/docs/widgets#common-widget-options). - * `allow_multiple`: *(default: `true`)* when set to `false`, prevents multiple selection for any media library extension, but must be supported by the extension in use - * `config`: a configuration object that will be passed directly to the media library being - used - available options are determined by the library - * `media_folder` (Beta): file path where uploaded files will be saved specific to this control. Paths can be relative to a collection folder (e.g. `files` will add the file to a sub-folder in the collection folder) or absolute with reference to the base of the repo which needs to begin with `/` (e.g `/static/files` will save uploaded files to the `static` folder in a sub folder named `files`) - * `choose_url`: *(default: `true`)* when set to `false`, the "Insert from URL" button will be hidden -* **Example:** +| Name | Type | Default | Description | +| ------------- | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| default | string | `null` | _Optional_. The default value for the field. Accepts a datetime string, or an empty string to accept blank input; otherwise defaults to current datetime | +| media_library | Media Library Options | `{}` | _Optional_. Media library settings to apply when a media library is opened by the current widget. See [Media Library Options](#media-library-options) | +| media_folder | string | | _Optional_. Specifies the folder path where uploaded files should be saved, relative to the base of the repo | +| public_folder | string | | _Optional_. Specifies the folder path where the files uploaded by the media library will be accessed, relative to the base of the built site | - ```yaml - - label: "Manual PDF" - title: "manual_pdf" - widget: "file" - default: "/uploads/general-manual.pdf" - media_library: - config: - multiple: true - ``` +### Media Library Options + +| Name | Type | Default | Description | +| -------------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| allow_multiple | boolean | `true` | _Optional_. When set to `false`, prevents multiple selection for any media library extension, but must be supported by the extension in use | +| config | string | `{}` | _Optional_. A configuration object that will be passed directly to the media library being used - available options are determined by the library | +| choose_url | string
\| boolean | `true` | _Optional_. When set to `false`, the "Insert from URL" button will be hidden | + +## Example + +```yaml +name: manual_pdf +label: Manual PDF +widget: file +default: /uploads/general-manual.pdf +media_library: + choose_url: true + config: + multiple: true +``` diff --git a/website/content/docs/widget-hidden.mdx b/website/content/docs/widget-hidden.mdx index 04031681..62a5e59d 100644 --- a/website/content/docs/widget-hidden.mdx +++ b/website/content/docs/widget-hidden.mdx @@ -3,15 +3,27 @@ group: Widgets title: Hidden weight: 15 --- +## Overview + +- **Name:** `hidden` +- **UI:** None +- **Data type:** Any valid data type Hidden widgets do not display in the UI. In folder collections that allow users to create new items, you will often want to set a default for hidden fields, so they will be set without requiring an input. -- **Name:** `hidden` -- **UI:** none -- **Data type:** any valid data type -- **Options:** - - `default`: accepts any valid data type; recommended for collections that allow adding new items -- **Example:** - ```yaml - - {label: "Layout", title: "layout", widget: "hidden", default: "blog"} - ``` +## Widget options + +For common options, see [Common widget options](/docs/widgets#common-widget-options). + +| Name | Type | Default | Description | +| ------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| default | string | `null` | _Optional_. The default value for the field. Accepts any valid data type. Recommended for collections that allow adding new items. | + +## Example + +```yaml +name: layout +label: Layout +widget: hidden +default: blog +``` diff --git a/website/content/docs/widget-image.mdx b/website/content/docs/widget-image.mdx index bae87596..1b57a88d 100644 --- a/website/content/docs/widget-image.mdx +++ b/website/content/docs/widget-image.mdx @@ -3,29 +3,42 @@ group: Widgets title: Image weight: 16 --- -The image widget allows editors to upload an image or select an existing one from the media library. The path to the image file will be saved to the field as a string. +## Overview -* **Name:** `image` -* **UI:** file picker button opens media gallery allowing image files (jpg, jpeg, webp, gif, png, bmp, tiff, svg) only; displays selected image thumbnail -* **Data type:** file path string -* **Options:** +- **Name:** `image` +- **UI:** File picker button opens media gallery allowing image files (jpg, jpeg, webp, gif, png, bmp, tiff, svg) only; displays selected image thumbnail +- **Data type:** File path string - * `default`: accepts a file path string; defaults to null - * `media_library`: settings to apply when a media library is opened by the - current widget - * `allow_multiple`: *(default: `true`)* when set to `false`, multiple selection will be disabled even if the media library extension supports it - * `config`: a configuration object passed directly to the media library; check the documentation of your media library extension for available `config` options - * `media_folder` (Beta): file path where uploaded images will be saved specific to this control. Paths can be relative to a collection folder (e.g. `images` will add the image to a sub-folder in the collection folder) or absolute with reference to the base of the repo which needs to begin with `/` (e.g `/static/images` will save uploaded images to the `static` folder in a sub folder named `images`) - * `choose_url`: *(default: `true`)* when set to `false`, the "Insert from URL" button will be hidden -* **Example:** +The file widget allows editors to upload a file or select an existing one from the media library. The path to the file will be saved to the field as a string. + +## Widget options + +For common options, see [Common widget options](/docs/widgets#common-widget-options). + +| Name | Type | Default | Description | +| ------------- | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| default | string | `null` | _Optional_. The default value for the field. Accepts a datetime string, or an empty string to accept blank input; otherwise defaults to current datetime | +| media_library | Media Library Options | `{}` | _Optional_. Media library settings to apply when a media library is opened by the current widget. See [Media Library Options](#media-library-options) | +| media_folder | string | | _Optional_. Specifies the folder path where uploaded files should be saved, relative to the base of the repo | +| public_folder | string | | _Optional_. Specifies the folder path where the files uploaded by the media library will be accessed, relative to the base of the built site | + +### Media Library Options + +| Name | Type | Default | Description | +| -------------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| allow_multiple | boolean | `true` | _Optional_. When set to `false`, prevents multiple selection for any media library extension, but must be supported by the extension in use | +| config | string | `{}` | _Optional_. A configuration object that will be passed directly to the media library being used - available options are determined by the library | +| choose_url | string
\| boolean | `true` | _Optional_. When set to `false`, the "Insert from URL" button will be hidden | + +## Example ```yaml - - label: "Featured Image" - title: "thumbnail" - widget: "image" - choose_url: true - default: "/uploads/chocolate-dogecoin.jpg" - media_library: - config: - multiple: true +name: thumbnail +label: Featured Image +widget: image +default: /uploads/chocolate-dogecoin.jpg +media_library: + choose_url: true + config: + multiple: true ``` diff --git a/website/content/docs/widget-list.mdx b/website/content/docs/widget-list.mdx index 09dacca2..34db22d4 100644 --- a/website/content/docs/widget-list.mdx +++ b/website/content/docs/widget-list.mdx @@ -3,127 +3,231 @@ group: Widgets title: List weight: 17 --- -The list widget allows you to create a repeatable item in the UI which saves as a list of widget values. map a user-provided string with a comma delimiter into a list. You can choose any widget as a child of a list widget—even other lists. -* **Name:** `list` -* **UI:** without any `fields` specified, the list widget defaults to a text input for entering comma-separated values; with `fields` specified, the list widget contains a repeatable child widget, with controls for adding, deleting, and re-ordering the repeated widgets. -* **Data type:** list of widget values -* **Options:** +## Overview - * `default`: you may specify a list of strings to populate the basic text - field, or an array of list items for lists using the `fields` option. If no - default is declared when using `field` or `fields`, will default to a single - list item using the defaults on the child widgets - * `allow_add`: `false` hides the button to add additional items - * `collapsed`: when `true`, the entries collapse by default - * `summary`: specify the label displayed on collapsed entries - * `minimize_collapsed`: when `true`, collapsing the list widget will hide all of it's entries instead of showing summaries - * `label_singular`: the text to show on the add button - * `field`: a single widget field to be repeated - * `fields`: a nested list of multiple widget fields to be included in each repeatable iteration - * `max`: maximum number of items in the list - * `min`: minimum number of items in the list - * `add_to_top`: when `true`, new entries will be added to the top of the list -* **Example** (`field`/`fields` not specified): +- **Name:** `list` +- **UI:** The list widget contains a repeatable child widget, with controls for adding, deleting, and re-ordering the repeated widgets. +- **Data type:** List of widget values + +The list widget allows you to create a repeatable item in the UI which saves as a list of widget values. You can choose any widget as a child of a list widget—even other lists. + +## Widget options + +For common options, see [Common widget options](/docs/widgets#common-widget-options). + +| Name | Type | Default | Description | +| -------------- | ---------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| default | string | `Single item`
`(with child defaults)` | _Optional_. The default value for the field. Accepts an array of list items | +| allow_add | boolean | `true` | _Optional_. `false` - Hides the button to add additional items | +| collapsed | boolean | `true` | _Optional_. `true` - The entries collapse by default | +| summary | string | | _Optional_. The label displayed on collapsed entries | +| label_singular | string | `label` | _Optional_. The text to show on the add button | +| fields | list of widgets | [] | _Optional_. A nested list of multiple widget fields to be included in each repeatable iteration | +| max | number | | _Optional_. Maximum number of items in the list | +| min | number | | _Optional_. Minimum number of items in the list | +| add_to_top | boolean | `false` | _Optional_. | +| types | list of object widgets | | _Optional_. A nested list of object widgets representing the available types for items in the list. Takes priority over `fields`. | +| type_key | string | `'type'` | _Optional_. 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 | + +## Examples + +### Basic ```yaml -- label: "Tags" - title: "tags" - widget: "list" - default: ["news"] +name: testimonials +label: Testimonials +widget: list +summary: '{{fields.quote}} - {{fields.author.name}}' +fields: + - name: quote + label: Quote + widget: string + default: Everything is awesome! + - name: author + label: Author + widget: object + fields: + - name: name + label: Name + widget: string + default: Emmet + - name: avatar + label: Avatar + widget: image + default: /img/emmet.jpg ``` -* **Example** (`allow_add` marked `false`): +### Allow Additions ```yaml -- label: "Tags" - title: "tags" - widget: "list" - allow_add: false - default: ["news"] +name: testimonials +label: Testimonials +widget: list +summary: '{{fields.quote}} - {{fields.author.name}}' +allow_add: false +fields: + - name: quote + label: Quote + widget: string + default: Everything is awesome! + - name: author + label: Author + widget: object + fields: + - name: name + label: Name + widget: string + default: Emmet + - name: avatar + label: Avatar + widget: image + default: /img/emmet.jpg ``` -* **Example** (with `field`): +### Default Value ```yaml -- label: "Gallery" - title: "galleryImages" - widget: "list" - summary: '{{fields.image}}' - field: {label: Image, title: image, widget: image} -``` - -* **Example** (with `fields`): - -```yaml -- label: "Testimonials" - title: "testimonials" - widget: "list" - summary: '{{fields.quote}} - {{fields.author.name}}' +- name: galleryImages + label: Gallery + widget: list fields: - - {label: Quote, title: quote, widget: string, default: "Everything is awesome!"} - - label: Author - title: author - widget: object - fields: - - {label: Name, title: name, widget: string, default: "Emmet"} - - {label: Avatar, title: avatar, widget: image, default: "/img/emmet.jpg"} -``` - -* **Example** (with `default`): - -```yaml -- label: "Gallery" - title: "galleryImages" - widget: "list" - fields: - - { label: "Source", title: "src", widget: "string" } - - { label: "Alt Text", title: "alt", widget: "string" } + - name: src + label: Source + widget: string + - name: alt + label: Alt Text + widget: string default: - - { src: "/img/tennis.jpg", alt: "Tennis" } - - { src: "/img/footbar.jpg", alt: "Football" } + - src: /img/tennis.jpg + alt: Tennis + - src: /img/footbar.jpg + alt: Football ``` -* **Example** (`collapsed` marked `false`): +### Start Collapsed ```yaml -- label: "Testimonials" - title: "testimonials" - collapsed: false - widget: "list" - fields: - - {label: Quote, title: quote, widget: string, default: "Everything is awesome!"} - - {label: Author, title: author, widget: string } +name: testimonials +label: Testimonials +widget: list +summary: '{{fields.quote}} - {{fields.author.name}}' +collapsed: false +fields: + - name: quote + label: Quote + widget: string + default: Everything is awesome! + - name: author + label: Author + widget: object + fields: + - name: name + label: Name + widget: string + default: Emmet + - name: avatar + label: Avatar + widget: image + default: /img/emmet.jpg ``` -* **Example** (`minimize_collapsed` marked `true`): +### Min and Max ```yaml -- label: "Testimonials" - title: "testimonials" - minimize_collapsed: true - widget: "list" - fields: - - {label: Quote, title: quote, widget: string, default: "Everything is awesome!"} - - {label: Author, title: author, widget: string } +name: testimonials +label: Testimonials +widget: list +summary: '{{fields.quote}} - {{fields.author.name}}' +min: 1 +max: 3 +fields: + - name: quote + label: Quote + widget: string + default: Everything is awesome! + - name: author + label: Author + widget: object + fields: + - name: name + label: Name + widget: string + default: Emmet + - name: avatar + label: Avatar + widget: image + default: /img/emmet.jpg ``` -* **Example** (with `max` & `min`): +### Add To Top ```yaml -- label: "Tags" - title: "tags" - widget: "list" - max: 3 - min: 1 - default: ["news"] +name: testimonials +label: Testimonials +widget: list +summary: '{{fields.quote}} - {{fields.author.name}}' +add_to_top: true +fields: + - name: quote + label: Quote + widget: string + default: Everything is awesome! + - name: author + label: Author + widget: object + fields: + - name: name + label: Name + widget: string + default: Emmet + - name: avatar + label: Avatar + widget: image + default: /img/emmet.jpg ``` -* **Example** (`add_to_top` marked `true`): +### Typed List ```yaml -- label: "Tags" - title: "tags" - widget: "list" - add_to_top: true -``` \ No newline at end of file +name: sections +label: Home Section +widget: list +types: + - name: carousel + label: Carousel + widget: object + summary: '{{fields.header}}' + fields: + - name: header + label: Header + widget: string + default: Image Gallery + - name: template + label: Template + widget: string + default: carousel.html + - name: images + label: Images + widget: list + fields: + - name: image + label: Image + widget: image + - name: spotlight + label: Spotlight + widget: object + fields: + - name: header + label: Header + widget: string + default: Spotlight + - name: template + label: Template + widget: string + default: spotlight.html + - name: text + label: Text + widget: text + default: Hello World +``` diff --git a/website/content/docs/widget-map.mdx b/website/content/docs/widget-map.mdx index 2763d306..617452bb 100644 --- a/website/content/docs/widget-map.mdx +++ b/website/content/docs/widget-map.mdx @@ -3,18 +3,29 @@ group: Widgets title: Map weight: 18 --- + +## Overview + +- **Name:** `map` +- **UI:** Interactive map +- **Data type:** `GeoJSON string`` + The map widget allows you to edit spatial data using an interactive map. Spatial data for a single piece of geometry saves as a GeoJSON string in WGS84 projection. -* **Name:** `map` -* **UI:** interactive map -* **Data type:** GeoJSON string -* **Options:** +## Widget options - * `decimals`: accepts a number to specify precision of saved coordinates; defaults to 7 decimals - * `default`: accepts a GeoJSON string containing a single geometry; defaults to an empty string - * `type`: accepts one string value of `Point`, `LineString` or `Polygon`; defaults to `Point` -* **Example:** +For common options, see [Common widget options](/docs/widgets#common-widget-options). - ```yaml - - {label: "Location", title: "location", widget: "map" } - ``` \ No newline at end of file +| Name | Type | Default | Description | +| -------- | ---------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------- | +| default | string | `''` | _Optional_. The default value for the field. Accepts a GeoJSON string containing a single geometry | +| decimals | number | `7` | _Optional_. Precision of saved coordinates | +| default | 'Point'
\| 'LineString'
\| 'Polygon' | `'Point'` | _Optional_. Data type | + +## Example + +```yaml +name: location +label: Location +widget: map +``` diff --git a/website/content/docs/widget-markdown.mdx b/website/content/docs/widget-markdown.mdx index 8f815ce2..f7269190 100644 --- a/website/content/docs/widget-markdown.mdx +++ b/website/content/docs/widget-markdown.mdx @@ -3,24 +3,35 @@ group: Widgets title: Markdown weight: 19 --- -The markdown widget provides a full fledged text editor allowing users to format text with features such as headings and blockquotes. Users can change their editing view with a handy toggle button. -*Please note:* If you want to use your markdown editor to fill a markdown file contents after its frontmatter, you'll have to name the field `body` so the CMS recognizes it and saves the file accordingly. +## Overview -* **Name:** `markdown` -* **UI:** full text editor -* **Data type:** markdown -* **Options:** +- **Name:** `markdown` +- **UI:** [Toast UI Editor](https://ui.toast.com/tui-editor) +- **Data type:** `markdown string` - * `default`: accepts markdown content -* **Example:** +The markdown widget provides a full fledged text editor allowing users to format text with features such as headings and blockquotes. Users can change their editing view with a handy toggle button. - ```yaml - - { label: 'Blog post content', title: 'body', widget: 'markdown' } - ``` +_Please note:_ If you want to use your markdown editor to fill a markdown file contents after its frontmatter, you'll have to name the field `body` so the CMS recognizes it and saves the file accordingly. + +## Widget options + +For common options, see [Common widget options](/docs/widgets#common-widget-options). + +| Name | Type | Default | Description | +| ------- | ------ | ------- | --------------------------------------------------------------------- | +| default | string | `''` | _Optional_. The default value for the field. Accepts markdown content | + +## Example + +```yaml +name: body +label: Blog post content +widget: markdown +``` This would render as: ![Markdown widget example](/img/widgets-markdown.webp) -*Please note:* The markdown widget outputs a raw markdown string. Your static site generator may or may not render the markdown to HTML automatically. Consult with your static site generator's documentation for more information about rendering markdown. +_Please note:_ The markdown widget outputs a raw markdown string. Your static site generator may or may not render the markdown to HTML automatically. Consult with your static site generator's documentation for more information about rendering markdown. diff --git a/website/content/docs/widget-number.mdx b/website/content/docs/widget-number.mdx index 855f07ea..a0058c3e 100644 --- a/website/content/docs/widget-number.mdx +++ b/website/content/docs/widget-number.mdx @@ -4,25 +4,35 @@ title: Number weight: 20 --- -The number widget uses an HTML number input, saving the value as a string, integer, or floating point number. +## Overview - **Name:** `number` - **UI:** HTML [number input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number) -- **Data type:** string by default; configured by `value_type` option -- **Options:** - - `default`: accepts string or number value; defaults to empty string - - `value_type`: accepts `int` or `float`; any other value results in saving as a string - - `min`: accepts a number for minimum value accepted; unset by default - - `max`: accepts a number for maximum value accepted; unset by default - - `step`: accepts a number for stepping up/down values in the input; 1 by default -- **Example:** - ```yaml - - label: "Puppy Count" - title: "puppies" - widget: "number" - default: 2 - value_type: "int" - min: 1 - max: 101 - step: 2 - ``` +- **Data type:** `string` or `number`. Configured by `value_type` option + +The number widget uses an HTML number input, saving the value as a string, integer, or floating point number. + +## Widget options + +For common options, see [Common widget options](/docs/widgets#common-widget-options). + +| Name | Type | Default | Description | +| ---------- | ------------------------------------ | ---------- | ----------------------------------------------------------------------------------- | +| default | string
\| number | `''` | _Optional_. The default value for the field. Accepts a string or number | +| value_type | 'int'
\| 'float'
\| string | `'string'` | _Optional_. Accepts `int` or `float`; any other value results in saving as a string | +| min | number | | _Optional_. Minimum value accepted | +| max | number | | _Optional_. Maximum value accepted | +| step | number | `1` | _Optional_. Size of steps when stepping up or down in input | + +## Example + +```yaml +name: 'puppies' +label: 'Puppy Count' +widget: 'number' +default: 2 +value_type: 'int' +min: 1 +max: 101 +step: 2 +``` diff --git a/website/content/docs/widget-object.mdx b/website/content/docs/widget-object.mdx index 6534783f..81b7c402 100644 --- a/website/content/docs/widget-object.mdx +++ b/website/content/docs/widget-object.mdx @@ -3,38 +3,59 @@ group: Widgets title: Object weight: 21 --- -The object widget allows you to group multiple widgets together, nested under a single field. You can choose any widget as a child of an object widget—even other objects. -* **Name:** `object` -* **UI:** a field containing one or more child widgets -* **Data type:** list of child widget values -* **Options:** +## Overview - * `default`: you can set defaults within each sub-field's configuration - * `collapsed`: if added and labeled `true`, collapse the widget's content by default - * `summary`: specify the label displayed when the object is collapsed - * `fields`: (**required**) a nested list of widget fields to include in your widget -* **Example:** +- **Name:** `object` +- **UI:** a field containing one or more child widgets +- **Data type:** Object of child widget values - ```yaml - - label: "Profile" - title: "profile" - widget: "object" - summary: '{{fields.name}}: {{fields.birthdate}}' +The object widget allows you to group multiple widgets together, nested under a single field. You can choose any widget as a child of an object widget, even other object widgets. + +## Widget options + +For common options, see [Common widget options](/docs/widgets#common-widget-options). + +| Name | Type | Default | Description | +| --------- | ------- | ------- | ------------------------------------------------------------ | +| fields | boolean | `false` | A nested list of widget fields to include in your widget | +| collapsed | boolean | `false` | _Optional_. Collapse the widget's content by default | +| summary | string | `value` | _Optional_. The label displayed when the object is collapsed | + +_Please note:_ A default value cannot be set directly on an object widget. Instead you can set defaults within each sub-field's configuration + +## Example + +```yaml +name: 'profile' +label: 'Profile' +widget: 'object' +summary: '{{fields.name}}: {{fields.birthdate}}' +fields: + - name: public + label: Public + widget: boolean + default: true + - name: name + label: Name + widget: string + - name: 'birthdate' + label: 'Birthdate' + widget: 'date' + default: '' + format: 'MM/DD/YYYY' + - name: 'address' + label: 'Address' + widget: 'object' + collapsed: true fields: - - {label: "Public", title: "public", widget: "boolean", default: true} - - {label: "Name", title: "name", widget: "string"} - - label: "Birthdate" - title: "birthdate" - widget: "date" - default: "" - format: "MM/DD/YYYY" - - label: "Address" - title: "address" - widget: "object" - collapsed: true - fields: - - {label: "Street Address", title: "street", widget: "string"} - - {label: "City", title: "city", widget: "string"} - - {label: "Postal Code", title: "post-code", widget: "string"} - ``` + - name: street + label: Street Address + widget: string + - name: city + label: City + widget: string + - name: post-code + label: Postal Code + widget: string +``` diff --git a/website/content/docs/widget-relation.mdx b/website/content/docs/widget-relation.mdx index bec44347..5b7d7e13 100644 --- a/website/content/docs/widget-relation.mdx +++ b/website/content/docs/widget-relation.mdx @@ -3,62 +3,79 @@ group: Widgets title: Relation weight: 22 --- + +## Overview + +- **Name:** `relation` +- **UI:** Text input with search result dropdown +- **Data type:** Data type of the value pulled from the related collection item + The relation widget allows you to reference items from another collection. It provides a search input with a list of entries from the collection you're referencing, and the list automatically updates with matched entries based on what you've typed. -* **Name:** `relation` -* **UI:** text input with search result dropdown -* **Data type:** data type of the value pulled from the related collection item -* **Options:** +## Widget options - * `collection`: (**required**) name of the referenced collection (string) - * `value_field`: (**required**) name of the field from the referenced collection whose value will be stored for the relation. For nested fields, separate each subfield with a `.` (e.g. `name.first`). For list fields use a wildcard `*` to target all list items (e.g. `categories.*`). - * `search_fields`: (**required**) list of one or more names of fields in the referenced collection to search for the typed value. Syntax to reference nested fields is similar to that of *value_field*. - * `file`: allows referencing a specific file when the referenced collection is a files collection (string) - * `display_fields`: list of one or more names of fields in the referenced collection that will render in the autocomplete menu of the control. Defaults to `value_field`. Syntax to reference nested fields is similar to that of *value_field*. - * `default`: accepts any widget data type; defaults to an empty string - * `multiple` : accepts a boolean, defaults to `false` - * `min`: minimum number of items; ignored if **multiple** is `false` - * `max`: maximum number of items; ignored if **multiple** is `false` - * `options_length`: accepts integer to override number of options presented to user. Defaults to `20`. -* **Referencing a folder collection example** (assuming a separate "authors" collection with "name" and "twitterHandle" fields with subfields "first" and "last" for the "name" field): +For common options, see [Common widget options](/docs/widgets#common-widget-options). + +| Name | Type | Default | Description | +| -------------- | -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| collection | string | | Name of the referenced collection | +| value_field | string | | Name of the field from the referenced collection whose value will be stored for the relation. For nested fields, separate each subfield with a `.` (e.g. `name.first`). For list fields use a wildcard `*` to target all list items (e.g. `categories.*`) | +| search_fields | list of strings | | List of one or more names of fields in the referenced collection to search for the typed value. Syntax to reference nested fields is similar to that of _value_field_ | +| default | Any widget data type | `''` | _Optional_. The default value for the field. Accepts any widget data type | +| file | string | | _Optional_. Allows referencing a specific file when the referenced collection is a files collection | +| display_fields | list of strings | | _Optional_. list of one or more names of fields in the referenced collection that will render in the autocomplete menu of the control. Defaults to `value_field`. Syntax to reference nested fields is similar to that of _value_field_ | +| multiple | boolean | `false` | _Optional_. Allow multiple values to be selected | +| min | number | | _Optional_. Minimum number of items. Ignored if **multiple** is `false` | +| max | number | | _Optional_. Maximum number of items. Ignored if **multiple** is `false` | +| options_length | number | `20` | _Optional_. Number of options presented to user | + +## Examples + +### Referencing A Folder Collection + +_Assuming a separate "authors" collection with "name" and "twitterHandle" fields with subfields "first" and "last" for the "name" field._ ```yaml -- label: "Post Author" - title: "author" - widget: "relation" - collection: "authors" - search_fields: ["name.first", "twitterHandle"] - value_field: "name.first" - display_fields: ["twitterHandle", "followerCount"] +name: author +label: Post Author +widget: relation +collection: authors +search_fields: ['name.first', 'twitterHandle'] +value_field: name.first +display_fields: ['twitterHandle', 'followerCount'] ``` The generated UI input will search the authors collection by name and twitterHandle, and display each author's handle and follower count. On selection, the author's name is saved for the field. -* **String templates example** (assuming a separate "authors" collection with "name" and "twitterHandle" fields with subfields "first" and "last" for the "name" field): +### String Template + +_Assuming a separate "authors" collection with "name" and "twitterHandle" fields with subfields "first" and "last" for the "name" field._ ```yaml -- label: "Post Author" - title: "author" - widget: "relation" - collection: "authors" - search_fields: ['name.first'] - value_field: "{{slug}}" - display_fields: ["{{twitterHandle}} - {{followerCount}}"] +name: author +label: Post Author +widget: relation +collection: authors +search_fields: ['name.first'] +value_field: '{{slug}}' +display_fields: ['{{twitterHandle}} - {{followerCount}}'] ``` The generated UI input will search the authors collection by name, and display each author's handle and follower count. On selection, the author entry slug is saved for the field. -* **Referencing a file collection list field example** (assuming a separate "relation_files" collection with a file named "cities" with a list field "cities" with subfields "name" and "id"): +### Referencing A File Collection List Field + +_Assuming a separate "relation_files" collection with a file named "cities" with a list field "cities" with subfields "name" and "id"._ ```yaml -- label: "City" - title: "city" - widget: "relation" - collection: "relation_files" - file: "cities" - search_fields: ["cities.*.name"] - display_fields: ["cities.*.name"] - value_field: "cities.*.id" +name: city +label: City +widget: relation +collection: relation_files +file: cities +search_fields: ['cities.*.name'] +display_fields: ['cities.*.name'] +value_field: 'cities.*.id' ``` -The generated UI input will search the cities file by city name, and display each city's name. On selection, the city id is saved for the field. \ No newline at end of file +The generated UI input will search the cities file by city name, and display each city's name. On selection, the city id is saved for the field. diff --git a/website/content/docs/widget-select.mdx b/website/content/docs/widget-select.mdx index 671233b8..c5ccf9a6 100644 --- a/website/content/docs/widget-select.mdx +++ b/website/content/docs/widget-select.mdx @@ -3,78 +3,100 @@ group: Widgets title: Select weight: 23 --- + +## Overview + +- **Name:** `select` +- **UI:** Select input +- **Data type:** `string`, `number`, `list of strings` or `list of numbers` + The select widget allows you to pick a string value from a dropdown menu. -* **Name:** `select` -* **UI:** select input -* **Data type:** string or array -* **Options:** +## Widget options - * `default`: `options` must contain any default values +For common options, see [Common widget options](/docs/widgets#common-widget-options). - * string values: accepts a string; defaults to an empty string. Accepts an array of strings and defaults to an empty array with `multiple: true` enabled. - * object with `label` and `value` fields: accepts an object with `label` and `value` field or an array of such objects when `multiple: true` is enable. Defaults to no value - * `options`: (**required**) there are two ways to list of options for the dropdown menu: +| Name | Type | Default | Description | +| -------- | ------------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| options | list of strings
\| list of numbers
\| object with `label` and `value` | | | +| default | string
\| number
\| list of string
\| list of number | `''`
`[]` if multiple is `true` | _Optional_. The default value for the field. Accepts a string | +| multiple | boolean | `false` | _Optional_. Allow multiple values/options to be selected | +| min | number | | _Optional_. Minimum number of items. Ignored if **multiple** is `false` | +| max | number | | _Optional_. Maximum number of items; ignored if **multiple** is `false` | - * string values: the dropdown displays the value directly - * object with `label` and `value` fields: the label displays in the dropdown; the value saves in the file - * `multiple`: accepts a boolean; defaults to `false` - * `min`: minimum number of items; ignored if **multiple** is `false` - * `max`: maximum number of items; ignored if **multiple** is `false` +## Examples -* **Example** (options as strings): +### Options As Strings ```yaml -- label: "Align Content" - title: "align" - widget: "select" - options: ["left", "center", "right"] +name: align +label: Align Content +widget: select +options: ['left', 'center', 'right'] ``` Selecting the `center` option, will save the value as: ```yaml -align: "center" +align: center ``` -* **Example** (options as objects): +### Options As Numbers ```yaml -- label: "City" - title: "airport-code" - widget: "select" - options: - - { label: "Chicago", value: "ORD" } - - { label: "Paris", value: "CDG" } - - { label: "Tokyo", value: "HND" } +name: align +label: Align Content +widget: select +options: [1, 2, 3] +``` + +Selecting the `2` option, will save the value as: + +```yaml +align: 2 +``` + +### Options As Objects + +```yaml +title: airport-code +label: City +widget: select +options: + - label: Chicago + value: ORD + - label: Paris + value: CDG + - label: Tokyo + value: HND ``` Selecting the `Chicago` option, will save the value as: ```yaml -airport-code: "ORD" +airport-code: ORD ``` -* **Example** (multiple): +### Multiple ```yaml -- label: "Tags" - title: "tags" - widget: "select" - multiple: true - options: ["Design", "UX", "Dev"] - default: ["Design"] +name: 'tags' +label: 'Tags' +widget: 'select' +multiple: true +options: ['Design', 'UX', 'Dev'] +default: ['Design'] ``` -* **Example** (min/max): +### Min and Max ```yaml -- label: "Tags" - title: "tags" - widget: "select" - multiple: true - min: 1 - max: 3 - options: ["Design", "UX", "Dev"] - default: ["Design"] +name: 'tags' +label: 'Tags' +widget: 'select' +multiple: true +min: 1 +max: 3 +options: ['Design', 'UX', 'Dev'] +default: ['Design'] ``` diff --git a/website/content/docs/widget-string.mdx b/website/content/docs/widget-string.mdx index db9ad268..2fe7348d 100644 --- a/website/content/docs/widget-string.mdx +++ b/website/content/docs/widget-string.mdx @@ -4,14 +4,26 @@ title: String weight: 24 --- -The string widget translates a basic text input to a string value. For larger textarea inputs, use the text widget. +## Overview - **Name:** `string` -- **UI:** text input -- **Data type:** string -- **Options:** - - `default`: accepts a string; defaults to an empty string -- **Example:** - ```yaml - - {label: "Title", title: "title", widget: "string"} - ``` +- **UI:** Text input +- **Data type:** `string` + +The string widget translates a basic text input to a string value. For larger textarea inputs, use the text widget. + +## Widget options + +For common options, see [Common widget options](/docs/widgets#common-widget-options). + +| Name | Type | Default | Description | +| ------- | ------ | ------- | ------------------------------------------------------------- | +| default | string | `''` | _Optional_. The default value for the field. Accepts a string | + +## Example + +```yaml +name: title +label: Title +widget: string +``` diff --git a/website/content/docs/widget-text.mdx b/website/content/docs/widget-text.mdx index 22b0ee6c..f5f49906 100644 --- a/website/content/docs/widget-text.mdx +++ b/website/content/docs/widget-text.mdx @@ -4,14 +4,26 @@ title: Text weight: 25 --- -The text widget takes a multiline text field and saves it as a string. For shorter text inputs, use the string widget. +## Overview - **Name:** `text` -- **UI:** HTML textarea -- **Data type:** string -- **Options:** - - `default`: accepts a string; defaults to an empty string -- **Example:** - ```yaml - - {label: "Description", title: "description", widget: "text"} - ``` +- **UI:** Textarea +- **Data type:** `string` + +The text widget takes a multiline text field and saves it as a string. For shorter text inputs, use the string widget. + +## Widget options + +For common options, see [Common widget options](/docs/widgets#common-widget-options). + +| Name | Type | Default | Description | +| ------- | ------ | ------- | ------------------------------------------------------------- | +| default | string | `''` | _Optional_. The default value for the field. Accepts a string | + +## Example + +```yaml +name: description +label: Description +widget: text +``` diff --git a/website/content/docs/widgets.mdx b/website/content/docs/widgets.mdx index 82521c3b..4f9bb695 100644 --- a/website/content/docs/widgets.mdx +++ b/website/content/docs/widgets.mdx @@ -23,8 +23,6 @@ The following options are available on all fields: | hint | string | | _Optional_. Adds helper text directly below a widget. Useful for including instructions. Accepts markdown for bold, italic, strikethrough, and links. | | pattern | string | | _Optional_. Adds field validation by specifying a list with a [regex pattern](https://regexr.com/) and an error message; more extensive validation can be achieved with [custom widgets](/docs/custom-widgets/#advanced-field-validation) | | i18n | boolean
\|'translate'
\|'duplicate'
\|'none' | | _Optional_. Beta Feature | -| media_folder | string | | _Optional_. Specifies the folder path where uploaded files should be saved, relative to the base of the repo | -| public_folder | string | | _Optional_. Specifies the folder path where the files uploaded by the media library will be accessed, relative to the base of the built site | | comment | string | | _Optional_. Adds comment before the field (only supported for yaml) | ### Example diff --git a/website/src/components/docs/DocsContent.tsx b/website/src/components/docs/DocsContent.tsx index a94b02af..ee2ec9ac 100644 --- a/website/src/components/docs/DocsContent.tsx +++ b/website/src/components/docs/DocsContent.tsx @@ -32,7 +32,7 @@ const DocsContent = styled('div')( & div, & p:not(:first-of-type) { - margin-top: 16px; + margin-top: 8px; } & :not(h1,h2,h3,h4,h5,h6) a { @@ -155,6 +155,10 @@ const DocsContent = styled('div')( } } + & h1 + h2 { + margin-top: 0; + } + & table thead tr th, & table thead tr td { white-space: nowrap; @@ -252,6 +256,10 @@ const DocsContent = styled('div')( margin: 0; } + & ul + p { + margin-top: 16px; + } + & abbr[title] { text-decoration: underline double; } diff --git a/website/src/pages/docs/[doc].tsx b/website/src/pages/docs/[doc].tsx index fe461235..0254e4da 100644 --- a/website/src/pages/docs/[doc].tsx +++ b/website/src/pages/docs/[doc].tsx @@ -145,6 +145,8 @@ export const getStaticProps: GetStaticProps = async ({ params }): Promise<{ prop }, }); + console.log(docsGroups.flatMap(group => group.links.flatMap(link => link.title))); + return { props: { docsGroups,