API Overhaul: registerWidget
- Dominant language
- JavaScript
- Stars
- 19.4k
- Forks
- 3.1k
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 9
Description
## Current Behavior
Registering a widget is currently pretty manual - you have to pass in each component separately, as well as a string for the name:
```js
import CMS from 'netlify-cms'
import { WidgetControl, WidgetPreview } from 'random-widget'
CMS.registerWidget('random', WidgetControl, WidgetPreview)
```
We're now seeing a need for widgets to provide more than just components:
- https://github.com/netlify/netlify-cms/issues/1074 - Widgets should provide a standalone configuration validation function
- https://github.com/netlify/netlify-cms/issues/1407 - Widgets should provide a standalone function that produces a dynamic default value
With the current API, we would need to add one or more parameters to `registerWidget` for these new features, causing registration of multiple widgets to become excessively verbose.
## Proposal
Require widgets to provide an object as the default export. As new widget features are added, the object can simply be appended, requiring no change for the projects using them. It would perhaps be shaped like this:
```js
const widget = {
name: 'random',
control: WidgetControl,
preview: WidgetPreview,
validateConfig: config => {...},
default: () => {...},
}
export default widget
```
Representing widgets as objects allows a single signature to provide as much control as necessary:
```js
import CMS from 'netlify-cms'
import randomWidget from 'random-widget'
// Use the defaults, should work for most cases
CMS.registerWidget(randomWidget)
// Or with an overridden property
CMS.registerWidget({ ...randomWidget, name: 'custom-name' })
// Or total control
import { RandomControl, validateConfig } from 'random-widget'
import CustomPreview from 'CustomPreview'
CMS.registerWidget({
name: 'custom-name',
control: RandomControl,
preview: CustomPreview,
validateConfig,
default: 'custom default value',
})
```
Finally, we should probably continue support the current signature, but deprecate at 2.0 and remove at 3.0.
Thoughts?
Contributor guide
Assessment
This issue has not been assessed yet.