diff --git a/package-lock.json b/package-lock.json index f45fc78435..ca9e43f8b1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "contentful-ui-extensions-sdk", - "version": "3.7.1", + "version": "3.7.2", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 8a672a4cff..64a51ba723 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "contentful-ui-extensions-sdk", "description": "SDK to develop custom UI Extension for the Contentful Web App", - "version": "3.7.1", + "version": "3.7.2", "author": "Contentful GmbH", "license": "MIT", "main": "dist/cf-extension-api.js", diff --git a/typings.d.ts b/typings.d.ts index ba66b3e7ec..6e72a5ac07 100644 --- a/typings.d.ts +++ b/typings.d.ts @@ -24,19 +24,29 @@ declare module 'contentful-ui-extensions-sdk' { /* Field API */ interface FieldAPI { - + /** The ID of a field is defined in an entry's content type. */ id: string; + /** The current locale of a field the extension is attached to. */ locale: string; + /** Holds the type of the field the extension is attached to. */ type: string; + /** A list of validations for this field that are defined in the content type. */ validations: Object[]; + /** Gets the current value of the field and locale. */ getValue: () => any; + /** Sets the value for the field and locale. */ setValue: (value: any) => Promise; + /** Removes the value for the field and locale. */ removeValue: () => Promise; + /** Communicates to the web application if the field is in a valid state or not. */ setInvalid: (value: boolean) => void; + /** Calls the callback every time the value of the field is changed by an external event or when setValue() is called. */ onValueChanged: (callback: (value: any) => void) => Function; + /** Calls the callback when the disabled status of the field changes. */ onIsDisabledChanged: (callback: Function) => Function; + /** Calls the callback immediately with the current validation errors and whenever the field is re-validated. */ onSchemaErrorsChanged: (callback: Function) => Function; } @@ -49,21 +59,33 @@ declare module 'contentful-ui-extensions-sdk' { type onIsDisabledChangedWithLocaleType = (locale: string, callback: Function) => Function; interface EntryFieldAPI { + /** The ID of a field is defined in an entry's content type. */ id: string; + /** The list of locales for the field. */ locales: string[]; + /** Holds the type of the field. */ type: string; + /** A list of validations for this field that are defined in the content type. */ validations: Object[]; + /** Gets the current value of the field and locale. */ getValue: (locale?: string) => any; + /** Sets the value for the field and locale. */ setValue: (value: any, locale?: string) => Promise; + /** Removes the value for the field and locale. */ removeValue: (locale?: string) => Promise; + /** Calls the callback every time the value of the field is changed by an external event or when setValue() is called. */ onValueChanged: onValueChangedType | onValueChangeWithLocaleType; + /** Calls the callback when the disabled status of the field changes. */ onIsDisabledChanged: onIsDisabledChangedType | onIsDisabledChangedWithLocaleType; } interface EntryAPI { + /** Returns metadata for an entry. */ getSys: () => Object; + /** Calls the callback with metadata every time that metadata changes. */ onSysChanged: (callback: (sys: Object) => void) => Function; + /** Allows to control the values of all other fields in the current entry. */ fields: { [key: string]: EntryFieldAPI } } @@ -158,22 +180,29 @@ declare module 'contentful-ui-extensions-sdk' { createUpload: (base64data: string) => void; waitUntilAssetProcessed: (assetId: string, locale: string) => void; + /** Returns all users who belong to the space. */ getUsers: () => Promise> } /* Locales API */ interface LocalesAPI { + /** The default locale code for the current space. */ default: string; + /** A list of locale codes of all locales available for editing in the current space. */ available: string[]; + /** An object with keys of locale codes and values of corresponding human-readable locale names. */ names: { [key:string]: string } } /* Window API */ interface WindowAPI { + /** Sets the iframe height to the given value in pixels or using scrollHeight if value is not passed */ updateHeight: (height?: number) => void; + /** Listens for DOM changes and updates height when the size changes. */ startAutoResizer: () => void; + /** Stops resizing the iframe automatically. */ stopAutoResizer: () => void; } @@ -203,33 +232,33 @@ declare module 'contentful-ui-extensions-sdk' { } interface DialogsAPI { - + /** Opens a simple alert window (which can only be closed). */ openAlert: (options: OpenAlertOptions) => Promise; - + /** Opens a confirmation window. A user can either confirm or cancel the dialog. */ openConfirm: (options: OpenConfirmOptions) => Promise; - + /** Opens a prompt window. A user can either provide a string input or cancel the dialog. */ openPrompt: (options: OpenConfirmOptions & { defaultValue?: string; }) => Promise; - + /** Opens an extension in a dialog. */ openExtension: (options: OpenExtensionOptions) => Promise; - + /** Opens a dialog for selecting a single entry. */ selectSingleEntry: (options?: { locale?: string; contentTypes?: string[]; }) => Promise; - + /** Opens a dialog for selecting multiple entries. */ selectMultipleEntries: (options?: { locale?: string; contentTypes?: string[]; min?: number; max?: number; }) => Promise; - + /** Opens a dialog for selecting a single asset. */ selectSingleAsset: (options?: { locale?: string; }) => Promise; - + /** Opens a dialog for selecting multiple assets. */ selectMultipleAssets: (options?: { locale?: string; min?: number; @@ -244,22 +273,29 @@ declare module 'contentful-ui-extensions-sdk' { } interface NavigatorAPI { + /** Opens an existing entry in the current Web App session. */ openEntry: (entryId: string, options?: NavigatorAPIOptions) => Promise; + /** Opens an existing asset in the current Web App session. */ openAsset: (assetId: string, options?: NavigatorAPIOptions) => Promise; + /** Opens a new entry in the current Web App session. */ openNewEntry: (contentTypeId: string, options?: NavigatorAPIOptions) => Promise; + /** Opens a new asset in the current Web App session. */ openNewAsset: (options: NavigatorAPIOptions) => Promise; } /* Notifier API */ interface NotifierAPI { + /** Displays a success notification in the notification area of the Web App. */ success: (message: string) => void; + /** Displays an error notification in the notification area of the Web App. */ error: (message: string) => void; } /* Location API */ interface LocationAPI { + /** Checks the location in which your extension is running */ is: (type: string) => boolean; } @@ -271,24 +307,44 @@ declare module 'contentful-ui-extensions-sdk' { invocation?: Object; } - export interface ExtensionSDK { - field?: FieldAPI; + export interface BaseExtensionSDK { + /** Allows to read and update the value of any field of the current entry and to get the entry's metadata */ entry: EntryAPI; + /** Information about the content type of the entry. */ contentType: ContentType; + /** Exposes methods that allow the extension to read and manipulate a wide range of objects in the space. */ space: SpaceAPI; - locales: LocalesAPI; + /** Information about the current user and roles */ user: User; + /** Information about the current locales */ + locales: LocalesAPI; + /** Methods to update the size of the iframe the extension is contained within. */ window: WindowAPI; + /** Methods for opening UI dialogs: */ dialogs: DialogsAPI; + /** Methods for navigating between entities stored in a Contentful space. */ navigator: NavigatorAPI; + /** Methods for displaying notifications. */ notifier: NotifierAPI; + /** Exposes extension configuration parameters */ parameters: ParametersAPI; location: LocationAPI; } - type InitCallback = (sdk: ExtensionSDK) => void; + export type SidebarExtensionSDK = BaseExtensionSDK; + + export type FieldExtensionSDK = BaseExtensionSDK & { + /** Gives you access to the value and metadata of the field the extension is attached to. */ + field: FieldAPI + } + + export type DialogExtensionSDK = BaseExtensionSDK & { + /** Closes the dialog and resolves openExtension promise with data */ + close: (data: any) => void + } + + export const init: (initCallback: (sdk: BaseExtensionSDK | FieldExtensionSDK | SidebarExtensionSDK | DialogExtensionSDK) => any) => void; - export const init: (initCallback: InitCallback) => void; export const locations: { LOCATION_ENTRY_FIELD: string; LOCATION_ENTRY_FIELD_SIDEBAR: string;