Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Docs: Improve custom widgets documentation #7032

Merged
merged 2 commits into from
Jan 15, 2024
Merged

Update Docs: Improve custom widgets documentation #7032

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
15f5b05
Improve custom widgets docuementation
zoetrope69 Jan 14, 2024
9387b6b
Remove unnecessary links
zoetrope69 Jan 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 17 additions & 18 deletions website/content/docs/custom-widgets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ import CMS from 'decap-cms-app';
CMS.registerWidget(name, control, [preview], [schema]);
```

**Params:**
### Params

| Param | Type | Description |
| ----------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -36,7 +36,7 @@ CMS.registerWidget(name, control, [preview], [schema]);
| [`preview`] | `React.Component`, optional | Renders the widget preview, receives the following props: <ul><li>**value:** Current preview value</li><li>**field:** Immutable map of current field configuration</li><li>**metadata:** Immutable map of any available metadata for the current field</li><li>**getAsset:** Function for retrieving an asset url for image/file fields</li><li>**entry:** Immutable Map of all entry data</li><li>**fieldsMetaData:** Immutable map of metadata from all fields.</li></ul> |
| [`schema`] | `JSON Schema object`, optional | Enforces a schema for the widget's field configuration |

**Example:**
### Example

`admin/index.html`

Expand Down Expand Up @@ -107,13 +107,13 @@ Register a block level component for the Markdown editor:
CMS.registerEditorComponent(definition)
```

**Params**
### Params

* **definition:** The component definition; must specify: id, label, fields, patterns, fromBlock, toBlock, toPreview

> Additional properties are optional and will be passed to the underlying widget control (object widget by default). For example, adding a `collapsed: true` property will collapse the widget by default.

**Example:**
### Example

```html
<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
Expand All @@ -131,8 +131,8 @@ CMS.registerEditorComponent({
widget: 'string'
},
{
name: 'details',
label: 'Details',
name: 'contents',
label: 'Contents',
widget: 'markdown'
}
],
Expand All @@ -154,7 +154,7 @@ CMS.registerEditorComponent({
fromBlock: function(match) {
return {
summary: match[1],
detail: match[2]
contents: match[2]
};
},
// Given an object with one property for each field defined in `fields`,
Expand All @@ -167,7 +167,7 @@ CMS.registerEditorComponent({
<details>
<summary>${data.summary}</summary>

${data.detail}
${data.contents}

</details>
`;
Expand All @@ -179,7 +179,7 @@ CMS.registerEditorComponent({
<details>
<summary>${data.summary}</summary>

${data.detail}
${data.contents}

</details>
`;
Expand All @@ -188,17 +188,14 @@ CMS.registerEditorComponent({
</script>
```

**Result:**

![youtube-widget](/img/img/screen%20shot%202018-01-05%20at%204.25.07%20pm.png)

## Advanced field validation

All widget fields, including those for built-in widgets, [include basic validation](../widgets/#common-widget-options) capability using the `required` and `pattern` options.

With custom widgets, the widget control can also optionally implement an `isValid` method to perform custom validations, in addition to presence and pattern. The `isValid` method will be automatically called, and it can return either a boolean value, an object with an error message or a promise. Examples:

**Boolean**
### Boolean

No errors:

```javascript
Expand All @@ -217,7 +214,8 @@ Existing error:
};
```

**Object with `error` (useful for returning custom error messages)**
### Object with `error` (useful for returning custom error messages)

Existing error:

```javascript
Expand All @@ -227,7 +225,8 @@ Existing error:
};
```

**Promise**
### Promise

You can also return a promise from `isValid`. While the promise is pending, the widget will be marked as "in error". When the promise resolves, the error is automatically cleared.

```javascript
Expand Down Expand Up @@ -503,7 +502,7 @@ CMS.registerWidget('test', Control, Preview)
init({ config })
```

### [](https://github.com/decaporg/decap-cms-widget-starter#development)Development
### Development

To run a copy of Decap CMS with your widget for development, use the start script:

Expand All @@ -513,7 +512,7 @@ npm start

Your widget source is in the `src` directory, where there are separate files for the `Control` and `Preview` components.

### [](https://github.com/decaporg/decap-cms-widget-starter#production--publishing)Production & Publishing
### Production & Publishing

You'll want to take a few steps before publishing a production built package to npm:

Expand Down