netlify-cms-widget-async-select
Version:
An async select widget for netlify-cms which can populate entries from a valid endpoint. Allows for sending custom headers, data/value fields and transformations.
153 lines (99 loc) • 3.08 kB
Markdown
# netlify-cms-widget-select-async
[Check out a demo!](https://netlify-cms-widget-select-async.netlify.com/demo)
A simple async select widget for netlify-cms which can populate entries from a valid endpoint. Allows for sending custom headers, data/value fields and transformations.
## Install
As an npm package:
```shell
npm install --save netlify-cms-widget-async-select
```
```js
import { Control as asyncSelectControl } from 'netlify-cms-widget-async-select'
CMS.registerWidget('async-select', asyncSelectControl)
```
Via `script` tag:
```html
<script src="https://unpkg.com/netlify-cms-widget-async-select@^1.0.0"></script>
<script>
CMS.registerWidget('async-select', window.asyncSelectControl, window.asyncSelectPreview)
</script>
```
## How to use
Add to your Netlify CMS configuration:
```yaml
fields:
- {
name: 'test_widget',
label: 'Test Widget',
widget: 'async-select',
url: 'https://jsonplaceholder.typicode.com/users',
valueField: 'id',
displayField: 'name',
},
```
## Configuration
Async-select widgets may have the following properties in addition to the defaults used by netlity.
`url` - string - **required**
The URI of the endpoint which to request data to populate the select options.
`valueField` - string - **required**
Field in the data response which will be mapped to the value of the netlify widget once populated.
`displayField` - string - **optional**
default: `valueField`
Field in the data response which will be mapped to the display text of the netlify widget once populated.
`dataKey` - string - **optional**
default: `valueField`
Field in the data response which will be used for the source of the data.
For example, given the below data structure, you may set `dataKey: 'data'` to populate the select dropdown as expected.
Example:
```javascript
{
meta: {
page: 1,
total: 10
...
}
data: [{
id: 1,
name: 'user 1',
email: 'foo@bar.com'
},{
...
}]
}
```
`headers` - object - **optional**
default: `{}`
Key-value object of HTTP headers to pass to the endpoint.
Example:
```javascript
{
'Content-Type': 'application/json',
...
}
```
`method` - string - **optional**
default: `GET`
HTTP request method to use when making call to endpoint.
`body` - **optional**
default: `undefined`
Body to send in request to endpoint.
`filter` - function - **optional**
default: `undefined`
Function which receives parameter `entry` (Immutable.js Map) which is run on each item returned from endpoint. Similar to `Array.prototype.filter` this will reject anything which does not return truthy.
Example:
```javascript
filter: (entry) => {
return entry.get('id') % 2;
}
```
Better documentation coming soon.
## Support
For help with this widget, open an [issue](https://github.com/chrisboustead/netlify-cms-widget-async-select) or ask the Netlify CMS community in [Gitter](https://gitter.im/netlify/netlifycms).