decaporg / decaporg/decap-cms

API Overhaul: registerWidget

Open
#1,409 6 comments 8 reactions 0 assignees View on GitHub
area: extensions/widgets pinned
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.