feat(editorInterface): Add support for sidebar and entry editor extensions

* Rename entry control methods

Author: lehnerm

.gitignore

@@ -22,3 +22,4 @@ npm-debug.log
 .vscode
 contentful-migration-cli-*.tgz
 errors-*
+.idea

README.md

@@ -75,9 +75,15 @@
       - [`editField(id[, opts])` : [Field](#field)](#editfieldid-opts--fieldfield)
       - [`deleteField(id)` : void](#deletefieldid--void)
       - [`changeFieldId (currentId, newId)` : void](#changefieldid-currentid-newid--void)
-      - [`changeEditorInterface (fieldId, widgetId[, settings])` : void](#changeeditorinterface-fieldid-widgetid-settings--void)
-      - [`resetEditorInterface (fieldId)` : void](#reseteditorinterface-fieldid--void)
-      - [`copyEditorInterface (sourceFieldId, destinationFieldId)` : void](#copyeditorinterface-sourcefieldid-destinationfieldid--void)
+      - [`changeFieldControl (fieldId, widgetNamespace, widgetId[, settings])` : void](#changefieldcontrol-fieldid-widgetid-widgetnamespace-settings--void)
+      - [`resetFieldControl (fieldId)` : void](#resetfieldcontrol-fieldid--void)
+      - [`copyFieldControl (sourceFieldId, destinationFieldId)` : void](#copyfieldcontrol-sourcefieldid-destinationfieldid--void)
+      - [`addSidebarWidget (widgetNamespace, widgetId[, settings, insertBeforeWidgetId])` : void](#addsidebarwidget-widgetnamespace-widgetid-settings-insertbeforewidgetid--void)
+      - [`updateSidebarWidget (widgetNamespace, widgetId, settings)` : void](#updatesidebarwidget-widgetnamespace-widgetid-settings--void)
+      - [`removeSidebarWidget (widgetNamespace, widgetId)` : void](#removesidebarwidget-widgetnamespace-widgetid--void)
+      - [`resetSidebarToDefault ()` : void](#resetsidebartodefault---void)
+      - [`configureEntryEditor (widgetNamespace, widgetId[, settings])` : void](#configureentryeditor-widgetid-widgetnamespace-settings--void)
+      - [`resetEditorToDefault()` : void](#reseteditortodefault---void)
     - [Field](#field)
   - [Validation errors](#validation-errors)
   - [Example migrations](#example-migrations)
@@ -107,9 +113,9 @@
   - Edit a field
   - Delete a field
   - Rename a field
-  - Change editorInterface
-  - Reset editorInterface
-  - Copy editorInterface
+  - Change a field's control
+  - Reset a field's control
+  - Copy a field's control
   - Move field
 
 ## Pre-requisites && Installation
@@ -517,15 +523,19 @@ module.exports = function (migration) {
 };
 ```
 
-#### `changeEditorInterface (fieldId, widgetId[, settings])` : void
+#### `changeFieldControl (fieldId, widgetNamespace, widgetId[, settings])` : void
 
-Changes the editor interface of given field's ID.
+Changes control interface of given field's ID.
 
 **`fieldId : string`** – The ID of the field.
 
+**`widgetNamespace : string`** – The namespace of the widget, one of the following values:
+- `builtin` (Standard widget)
+- `extension` (Custom UI extension)
+
 **`widgetId : string`** – The new widget ID for the field. See the [editor interface documentation](https://www.contentful.com/developers/docs/concepts/editor-interfaces/) for a list of available widgets.
 
-**`settings : Object`** – Widget settings, with the following options:
+**`settings : Object`** – Widget settings and extension instance parameters. Key-value pairs of type (string, number | boolean | string). For builtin widgets, the the following options are available:
 
 - **`helpText : string`** – This help text will show up below the field.
 - **`trueLabel : string`** _(only for fields of type boolean)_ – Shows this text next to the radio button that sets this value to `true`. Defaults to “Yes”.
@@ -535,14 +545,66 @@ Changes the editor interface of given field's ID.
 - **`ampm : string`** _(only for fields of type datePicker)_ – Specifies which type of clock to use. Must be one of the strings “12” or “24” (default).
 - **`bulkEditing : boolean`** _(only for fields of type Array)_ – Specifies whether bulk editing of linked entries is possible.
 
-#### `resetEditorInterface (fieldId)` : void
+#### `resetFieldControl (fieldId)` : void
 
 **`fieldId : string`** – The ID of the field.
 
-#### `copyEditorInterface (sourceFieldId, destinationFieldId)` : void
+#### `copyFieldControl (sourceFieldId, destinationFieldId)` : void
+
+**`sourceFieldId : string`** – The ID of the field to copy the control setting from.
+**`destinationFieldId : string`** – The ID of the field to apply the copied control setting to.
+
+#### `addSidebarWidget (widgetNamespace, widgetId[, settings, insertBeforeWidgetId])` : void
+
+Adds a builtin or custom widget to the sidebar of the content type.
+
+**`widgetNamespace: string`** – The namespace of the widget, one of the following values:
+- `sidebar-builtin` (Standard widget, default)
+- `extension` (Custom UI extension)
+
+**`widgetId : string`** – The ID of the builtin or extension widget to add.
+
+**`settings : Object`** – Instance settings for the widget. Key-value pairs of type (string, number | boolean | string)
+
+**`insertBeforeWidgetId : Object`** – Insert widget above this widget in the sidebar. If null, the widget will be added to the end.
+
+#### `updateSidebarWidget (widgetNamespace, widgetId, settings)` : void
+
+Updates the configuration of a widget in the sidebar of the content type.
+
+**`widgetNamespace: string`** – The namespace of the widget, one of the following values:
+- `sidebar-builtin` (Standard widget, default)
+- `extension` (Custom UI extension)
+
+**`widgetId : string`** – The ID of the builtin or extension widget to add.
+
+**`settings : Object`** – Instance settings for the widget. Key-value pairs of type (string, number | boolean | string)
+
+#### `removeSidebarWidget (widgetNamespace, widgetId)` : void
+
+Removes a widget from the sidebar of the content type.
+
+**`widgetNamespace: string`** – The namespace of the widget, one of the following values:
+- `sidebar-builtin` (Standard widget, default)
+- `extension` (Custom UI extension)
+
+**`widgetId : string`** – The ID of the builtin or extension widget to remove.
+
+#### `resetSidebarToDefault ()` : void
+
+Resets the sidebar of the content type to default.
+
+#### `configureEntryEditor (widgetNamespace, widgetId[, settings])` : void
+
+Sets the entry editor to specified widget.
+
+**`widgetNamespace: string`** – The namespace of the widget.
+**`widgetId : string`** – The ID of the builtin or extension widget to add.
+**`settings : Object`** – Instance settings for the widget. Key-value pairs of type (string, number | boolean | string). Optional.
+
+#### `resetEntryEditorToDefault ()` : void
 
-**`sourceFieldId : string`** – The ID of the field to copy the editorinterface setting from.
-**`destinationFieldId : string`** – The ID of the field to apply the copied editorinterface setting to.
+Resets the entry editor of the content type to default.
 
 ### Field
 

examples/16-change-editor-interface.js examples/16-change-field-control.js

@@ -34,5 +34,5 @@ module.exports = function (migration) {
     type: 'Symbol',
     required: true
   });
-  blogPost.changeEditorInterface('slug', 'slugEditor');
+  blogPost.changeFieldControl('slug', 'slugEditor', 'builtin', { setting: 'value' });
 };

examples/17-change-editor-interface-for-existing-content-type.js examples/17-change-field-control-for-existing-content-type.js

@@ -4,5 +4,7 @@ module.exports = function (migration) {
     description: 'super angry'
   });
 
-  blogPost.changeEditorInterface('slug', 'singleLine');
+  blogPost
+    .resetFieldControl('slug')
+    .changeFieldControl('slug', 'singleLine', 'builtin');
 };

examples/18-change-editor-interface-for-existing-content-type-adding-help-text.js examples/18-change-field-control-for-existing-content-type-adding-help-text.js

@@ -4,9 +4,10 @@ module.exports = function (migration) {
     description: 'super angry'
   });
 
-  blogPost.changeEditorInterface(
+  blogPost.changeFieldControl(
     'slug',
     'slugEditor',
+    'builtin',
     { helpText: 'This is the slug for the entry, it will be used for the URL' }
   );
 };

examples/21-copy-editor-interface-for-content-type.js examples/21-copy-field-control.js

@@ -14,6 +14,6 @@ module.exports = function (migration) {
     name: 'Instruction',
     type: 'Text'
   });
-  recipe.changeEditorInterface('description', 'markdown');
-  recipe.copyEditorInterface('description', 'instruction');
+  recipe.changeFieldControl('description', 'markdown', 'builtin');
+  recipe.copyFieldControl('description', 'instruction');
 };

examples/24-add-sidebar-widget-to-existing-content-type.js

@@ -0,0 +1,26 @@
+module.exports = function (migration) {
+  const customSidebar = migration.createContentType('customSidebar', {
+    name: 'Custom sidebar',
+    description: 'How to add, remove and update widgets'
+  });
+
+  customSidebar
+    .addSidebarWidget('sidebar-builtin', 'not-needed');
+
+  customSidebar
+    .addSidebarWidget('extension', 'imageTaggingExtensionId', {
+      imageField: 'image'
+    })
+    .addSidebarWidget('sidebar-builtin', 'publication-widget', {}, 'imageTaggingExtensionId')
+    .updateSidebarWidget(
+      'extension',
+      'imageTaggingExtensionId',
+      {
+        tagField: 'tags',
+        imageField: 'image'
+      }
+    );
+
+  customSidebar
+    .removeSidebarWidget('sidebar-builtin', 'not-needed');
+};

examples/25-configure-entry-editor.js

@@ -0,0 +1,15 @@
+module.exports = function (migration) {
+  const customEntryEditor = migration.createContentType(
+    'customEntryEditor_v5',
+    {
+      name: 'Entry Editor',
+      description: 'Set entry editor'
+    }
+  );
+
+  customEntryEditor.configureEntryEditor(
+    'extension',
+    'customEntryEditor_v5',
+    {}
+  );
+};

examples/26-reset-entry-editor.js

@@ -0,0 +1,10 @@
+module.exports = function (migration) {
+  const customEntryEditor = migration.createContentType('resetEntryEditor_v5', {
+    name: 'Entry Editor',
+    description: 'Set entry editor'
+  });
+
+  customEntryEditor.configureEntryEditor('extension', 'resetEntryEditor_v5', {});
+
+  customEntryEditor.resetEntryEditor();
+};

index.d.ts

@@ -96,6 +96,8 @@ export interface IValidation {
   [validation: string]: any
 }
 
+export type WidgetSettingsValue = number | boolean | string
+
 export interface IEditorInterfaceOptions {
 
   /** This help text will show up below the field. */
@@ -112,6 +114,14 @@ export interface IEditorInterfaceOptions {
   ampm?: '12' | '24'
   /** (only for References, many) Select whether to enable Bulk Editing mode */
   bulkEditing?: boolean
+
+  /** Instance settings for the sidebar widget as key-value pairs. */
+  [setting: string]: WidgetSettingsValue
+}
+
+export interface ISidebarWidgetSettings {
+  /** Instance settings for the sidebar widget as key-value pairs. */
+  [setting: string]: WidgetSettingsValue
 }
 
 export interface ContentType {
@@ -140,29 +150,85 @@ export interface ContentType {
   changeFieldId (oldId: string, newId: string): void
 
   /**
-   * Changes the editor interface of given field's ID.
+   * Changes the control of given field's ID.
    *
+   * @param widgetNamespace The namespace of the widget. Use 'builtin' for standard widgets or 'extension' for UI extensions.
    * @param fieldId The ID of the field.
    * @param widgetId The new widget ID for the field.
    * @param settings Widget settings
    */
-  changeEditorInterface (fieldId: string, widgetId: string, settings?: IEditorInterfaceOptions): void
+  changeFieldControl (fieldId: string, widgetNamespace: 'builtin' | 'extension', widgetId: string, settings?: IEditorInterfaceOptions): void
+
+  /**
+   * @deprecated
+   * Use change field control instead
+   */
+  changeEditorInterface (fieldId: string, widgetId: string, settings?: IEditorInterfaceOptions, widgetNamespace?: 'builtin' | 'extension'): void
 
   /**
-   * Resets the editor interface of given field's ID.
+   * Resets the field control of given field's ID.
    *
    * @param fieldId The ID of the field.
    */
+  resetFieldControl (fieldId: string): void
+
+  /**
+   * @deprecated
+   * Use resetFieldControl instead
+   */
   resetEditorInterface (fieldId: string): void
 
   /**
-   * copies the editor interface setting from a field to another field in the same content type.
+   * copies the control settings from a field to another field in the same content type.
    *
-   * @param sourceFieldId The ID of the field to copy the editorinterface setting from.
-   * @param destinationFieldId The ID of the field to apply the copied editorinterface setting to.
+   * @param sourceFieldId The ID of the field to copy the control setting from.
+   * @param destinationFieldId The ID of the field to apply the copied control setting to.
+   */
+  copyFieldControl (sourceFieldId: string, destinationFieldId: string): void
+
+  /**
+   * @deprecated
+   * Use copyFieldControl instead
    */
   copyEditorInterface (sourceFieldId: string, destinationFieldId: string): void
 
+  /**
+   * Adds a builtin or custom widget to the sidebar of the content type.
+   *
+   * @param widgetNamespace The namespace of the widget. Use 'sidebar-builtin' for standard widgets or 'extension' for UI extensions.
+   * @param widgetId The ID of the builtin or extension widget to add.
+   * @param settings Instance settings for the widget
+   * @param insertBeforeWidgetId Insert widget above this widget in the sidebar. If null, the widget will be added to the end.
+   */
+  addSidebarWidget (widgetNamespace: 'sidebar-builtin' | 'extension',
+                    widgetId: string,
+                    settings: ISidebarWidgetSettings,
+                    insertBeforeWidgetId: string): void
+
+  /**
+   * Updates the configuration of a widget in the sidebar of the content type.
+   *
+   * @param widgetNamespace The namespace of the widget. Use 'sidebar-builtin' for standard widgets or 'extension' for UI extensions.
+   * @param widgetId The ID of the widget to update.
+   * @param settings Instance settings for the widget
+   */
+  updateSidebarWidget (widgetNamespace: 'sidebar-builtin' | 'extension',
+                       widgetId: string,
+                       settings: ISidebarWidgetSettings): void
+
+  /**
+   * Removes a widget from the sidebar of the content type.
+   *
+   * @param widgetNamespace The namespace of the widget. Use 'sidebar-builtin' for standard widgets or 'extension' for UI extensions.
+   * @param widgetId The ID of the widget to remove.
+   */
+  removeSidebarWidget (widgetNamespace: 'sidebar-builtin' | 'extension',
+                       widgetId: string): void
+
+  /**
+   * Resets the sidebar of the content type to default
+   */
+  resetSidebarToDefault (): void
 }
 
 export interface IContentTypeOptions {