gcg/static-cms
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #905 from netlify/cms/custom-widgets

Browse Source 
Automatically generated. Merged on Netlify CMS.
This commit is contained in:
Shawn Erquhart 2017-12-09 03:29:29 -05:00 committed by GitHub
commit 5133bceb44
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 12 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
website/site/content/docs/custom-widgets.md
View File

@ -2,7 +2,6 @@
title: Custom Widgets
position: 35
---
# Custom Widgets
The NetlifyCMS exposes an `window.CMS` global object that you can use to register custom widgets, previews, and editor plugins. The available widget extension methods are:
@ -26,11 +25,12 @@ CMS.registerWidget(name, control, \[preview\])
**Params:**
Param | Type | Description
--- | --- | ---
`name` | string | Widget name, allows this widget to be used via the field `widget` property in config
`control` | React.Component \| string | <ul><li>React component that renders the control, receives the following props: <ul><li>**value:** Current field value</li><li>**onChange:** Callback function to update the field value</li></ul></li><li>Name of a registered widget whose control should be used (includes built in widgets).</li></ul>
[`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>
| Param | Type | Description |
| ----------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Widget name, allows this widget to be used via the field `widget` property in config |
| `control` | React.Component | string | <ul><li>React component that renders the control, receives the following props: <ul><li>**value:** Current field value</li><li>**onChange:** Callback function to update the field value</li></ul></li><li>Name of a registered widget whose control should be used (includes built in widgets).</li></ul> |
| [`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> |
* **field:** The field type that this widget will be used for.
* **control:** A React component that renders the editing interface for this field. Two props will be passed:
* **value:** The current value for this field.
@ -40,7 +40,7 @@ Param | Type | Description
**Example:**
```html
<script src="https://unpkg.com/netlify-cms@^0.7.0/dist/cms.js"></script>
<script src="https://unpkg.com/netlify-cms@^1.0.0/dist/cms.js"></script>
<script>
var CategoriesControl = createClass({
handleChange: function(e) {
@ -71,7 +71,9 @@ CMS.registerWidget('categories', CategoriesControl, CategoriesPreview);
Register a block level component for the Markdown editor:
CMS.registerEditorComponent(definition)
```
CMS.registerEditorComponent(definition)
```
**Params**
@ -80,7 +82,7 @@ Register a block level component for the Markdown editor:
**Example:**
```html
<script src="https://unpkg.com/netlify-cms@^0.7.0/dist/cms.js"></script>
<script src="https://unpkg.com/netlify-cms@^1.0.0/dist/cms.js"></script>
<script>
CMS.registerEditorComponent({
// Internal id of the component
@ -116,7 +118,6 @@ CMS.registerEditorComponent({
![youtube-widget](/img/youtube-widget.png)
## Advanced field validation
All widget fields, including those for built-in widgets, [include basic validation](https://www.netlifycms.org/docs/widgets/#common-widget-options) capability using the `required` and `pattern` options.
@ -161,4 +162,4 @@ You can also return a promise from `isValid`. While the promise is pending, the
};
```
Note: Do not create a promise inside `isValid` - `isValid` is called right before trying to persist. This means that even if a previous promise was already resolved, when the user hits 'save', `isValid` will be called again. If it returns a new promise, it will be immediately marked as "in error" until the new promise resolves.
Note: Do not create a promise inside `isValid` - `isValid` is called right before trying to persist. This means that even if a previous promise was already resolved, when the user hits 'save', `isValid` will be called again. If it returns a new promise, it will be immediately marked as "in error" until the new promise resolves.