@bloomreach/ui-extension-saas/dist/ui-extension.d.ts

Bloomreach Open UI SDK

/**
 * Defines all public API of the ui-extension library.
 * @module api
 */
/**
 * Callback function for events generated by the CMS.
 */
declare type EventHandler<Events> = (eventData: Events[keyof Events]) => any;
/**
 * Function to unsubscribe an [[EventHandler]] with.
 */
declare type UnsubscribeFn = () => void;
/**
 * Identifies which error occurred while using the ui-extension library.
 */
declare enum UiExtensionErrorCode {
    /**
     * The connection with the CMS has been destroyed.
     */
    ConnectionDestroyed = "ConnectionDestroyed",
    /**
     * A dialog was canceled.
     * @since 13.2
     */
    DialogCanceled = "DialogCanceled",
    /**
     * A dialog is already shown to the user.
     * @since 13.2
     */
    DialogExists = "DialogExists",
    /**
     * The version of the CMS in which the UI extension is loaded is not compatible with the version of the
     * ui-extension library used by the UI extension.
     */
    IncompatibleParent = "IncompatibleParent",
    /**
     * An internal error occurred.
     */
    InternalError = "InternalError",
    /**
     * The UI extension is not running in an iframe.
     */
    NotInIframe = "NotInIframe"
}
/**
 * Error returned by the ui-extension library via a rejected Promise.
 */
interface UiExtensionError {
    /**
     * Identifies the error to applications.
     */
    code: UiExtensionErrorCode;
    /**
     * Explains the error to humans.
     */
    message: string;
}
/**
 * Defines the different possible styling themes of the surrounding user interface.
 * @since 13.2
 */
declare enum UiStyling {
    Classic = "classic",
    Material = "material"
}
/**
 * Properties of the CMS that loads the UI extension.
 */
interface UiProperties {
    /**
     * The base URL of the CMS, without any query parameters.
     */
    baseUrl: string;
    /**
     * Properties of this UI extension.
     */
    extension: {
        /**
         * The configuration of this UI extension. How to interpret the string
         * (e.g. parse as JSON) is up to the implementation of the UI extension.
         */
        config: string;
    };
    /**
     * The locale of the CMS user as selected in the login page. For example: "en".
     */
    locale: string;
    /**
     * The styling of the user interface in which the extension is shown.
     * @since 13.2
     */
    styling: UiStyling;
    /**
     * The time zone of the CMS user as selected on the login page. For example: "Europe/Amsterdam".
     */
    timeZone: string;
    /**
     * Properties of the CMS user.
     */
    user: {
        /**
         * The username of the CMS user. For example: "admin".
         */
        id: string;
        /**
         * The first name of the CMS user. For example: "Suzanna".
         */
        firstName: string;
        /**
         * The last name of the CMS user. For example: "Doe".
         */
        lastName: string;
        /**
         * Concatenation of the first and last name of the CMS user, or the username if both are blank.
         * For example: "Suzanna Doe" or "admin".
         */
        displayName: string;
    };
    /**
     * The version of the CMS. For example: "13.0.0".
     */
    version: string;
}
/**
 * Dynamic properties (e.g. Channel Properties, Component Properties).
 */
interface DynamicProperties {
    [key: string]: string;
}
/**
 * API to access information about and communicate with the CMS that loads the UI extension.
 */
interface UiScope extends UiProperties {
    /**
     * API for the current channel.
     */
    channel: ChannelScope;
    /**
     * API for the current document.
     */
    document: DocumentScope;
    /**
     * API for dialogs.
     */
    dialog: DialogScope;
}
/**
 * API to access information about and communicate with the current channel shown in the Channel Manager.
 */
interface ChannelScope extends Emitter<ChannelScopeEvents> {
    /**
     * API for the current page in the current channel.
     */
    page: PageScope;
    /**
     * Refreshes the metadata of the currently shown channel (e.g. whether it has changes, the sitemap, etc.).
     * The Channel Manager UI will be updated to reflect the channel’s refreshed metadata.
     */
    refresh: () => Promise<void>;
    /**
     * @returns A Promise that resolves with [[DynamicProperties]] of the current channel.
     */
    get(): Promise<DynamicProperties>;
}
interface ChannelScopeEvents {
    /**
     * Triggered when a user publishes channel changes.
     * @since 13.1
     * @event
     */
    'changes.publish': void;
    /**
     * Triggered when a user discards channel changes
     * @since 13.1
     * @event
     */
    'changes.discard': void;
}
/**
 * API to access information about and communicate with the current page
 * in the current channel shown in the Channel Manager.
 */
interface PageScope extends Emitter<PageScopeEvents> {
    /**
     * @returns A Promise that resolves with [[PageProperties]] of the current page.
     */
    get(): Promise<PageProperties>;
    /**
     * Refreshes the page currently shown in the Channel Manager.
     */
    refresh(): Promise<void>;
}
/**
 * An emitter of events.
 */
interface Emitter<Events> {
    /**
     * Subscribes a handler for events emitted by the CMS. The type of the
     * emitted value depends on the emitted event.
     *
     * @param eventName the name of the emitted event.
     * @param handler the function to call with the emitted value.
     *
     * @returns A function to unsubscribe the handler again.
     */
    on(eventName: keyof Events, handler: EventHandler<Events>): UnsubscribeFn;
}
/**
 * A map of all events related to a page in a channel and the type of value they emit.
 */
interface PageScopeEvents {
    /**
     * Triggered when a user navigates to another page in the Channel Manager.
     * Emits the properties of the new page.
     * @event
     */
    navigate: PageProperties;
}
/**
 * Properties of a page in a channel.
 */
interface PageProperties {
    /**
     * Properties of the channel the page is part of.
     */
    channel: {
        /**
         * The context path of the site application. For example "/site" or "/".
         * @since 13.2
         */
        contextPath: string;
        /**
         * The identifier of the channel. For example: "example-preview".
         */
        id: string;
        /**
         * The mount path of the channel. For example "/subsite", "/europe/nl" or an empty string for the root mount.
         * @since 13.2
         */
        mountPath: string;
    };
    /**
     * The UUID of the `hst:component` root node of the page hierarchy.
     */
    id: string;
    /**
     * Properties of the matched sitemap item.
     */
    sitemapItem: {
        /**
         * The UUID of the sitemap item.
         */
        id: string;
    };
    /**
     * The URL of the page relative to the mount path of the channel. For example "/news/mypage.html" or an empty string
     * for the home page.
     * @since 13.2
     */
    path: string;
    /**
     * The public URL of the page.
     */
    url: string;
}
/**
 * API to access information about and communicate with the current document.
 * @since 13.2
 */
interface DocumentScope {
    /**
     * @since 13.2
     * @returns A Promise that resolves with [[DocumentProperties]] of the current document.
     */
    get(): Promise<DocumentProperties>;
    /**
     * Navigates a document path in the content perspective.
     * @since 14.2
     * @param id The document path.
     * @returns A Promise that resolves when the document is opened.
     */
    navigate(path: string): Promise<void>;
    /**
     * Opens a document by id in the content perspective.
     * @since 14.2
     * @param id The document id.
     * @returns A Promise that resolves when the document is opened.
     */
    open(id: string): Promise<void>;
    /**
     * API for the current field of the current document.
     * @since 13.2
     */
    field: FieldScope;
    /**
     * Updates the specified field value.
     * @param path The path is a string pointing to the field or a nested subfield within the current document.
     * The path should have the following format for each field: `{namespace}:{fieldName}`.
     * For example, "brxsaas:name" or "brxsaas:parentField.brxsaas:childField" if you want to set a child field value.
     * @param value The new field value
     */
    setFieldValue(path: string, value: string): Promise<void>;
    /**
     * Gets the specified field value.
     * @param path The path is a string pointing to the field or a nested subfield within the current document.
     * The path should have the following format for each field: `{namespace}:{fieldName}`.
     * For example, "brxsaas:name" or "brxsaas:parentField.brxsaas:childField" if you want to get a child field value.
     */
    getFieldValue(path: string): Promise<any>;
    /**
     * Gets an object with all field values of the current document.
     * For example, { "brxsaas:name": "name" }
     */
    getValues(): Promise<Record<string, any>>;
}
/**
 * Defines the different possible modes of a document editor.
 * @since 13.2
 */
declare enum DocumentEditorMode {
    View = "view",
    Compare = "compare",
    Edit = "edit"
}
/**
 * Properties of a document.
 * @since 13.2
 */
interface DocumentProperties {
    /**
     * The UUID of the handle node.
     * @since 13.2
     */
    id: string;
    /**
     * Display name of the document.
     * @since 13.2
     */
    displayName: string;
    /**
     * Locale of the document, e.g. "sv". Is undefined when the document does not have a locale.
     * @since 13.2
     */
    locale: string;
    /**
     * The mode of the document editor.
     * @since 13.2
     */
    mode: DocumentEditorMode;
    /**
     * The URL name of the document.
     * @since 13.2
     */
    urlName: string;
    /**
     * UUID of the currently shown variant, typically 'draft' or 'preview'.
     * @since 13.2
     */
    variant: {
        id: string;
    };
}
/**
 * API to access information about and communicate with the current document field.
 * @since 13.2
 */
interface FieldScope {
    /**
     * Gets the current field value.
     * @since 13.2
     * @return A promise that resolves with the current field value.
     */
    getValue(): Promise<string>;
    /**
     * @deprecated Use getValue from the document object instead
     * Gets the current document field value.
     * @since 14.3
     * @param path The path is a string array pointing to the field or a nested subfield within the current document.
     *  For the multiple values fields, use zero-based indices to access specific values.
     * @return A promise that resolves with the field value.
     */
    getValue(...path: string[]): Promise<any>;
    /**
     * Gets the field value to compare the current value to.
     * Only valid when the document editor mode is [[DocumentEditorMode.Compare]].
     *
     * @since 13.2
     * @return A promise that resolves with the compare value, or null when the
     * document editor mode is not [[DocumentEditorMode.Compare]].
     */
    getCompareValue(): Promise<string>;
    /**
     * Gets field values to compare the current values to.
     * Only valid when the document editor mode is [[DocumentEditorMode.Compare]].
     *
     * @since 14.3
     * @param path The path is a string array pointing to the field or a nested subfield within the current document.
     *  For the multiple values fields, use zero-based indices to access specific values.
     * @return A promise that resolves with the field compare value, or null when the
     * document editor mode is not [[DocumentEditorMode.Compare]].
     */
    getCompareValue(...path: string[]): Promise<any>;
    /**
     * Updates current field value.
     * @since 13.2
     * @param value the new field value
     */
    setValue(value: string): Promise<void>;
    /**
     * Set the height of the surrounding iframe.
     * @since 13.2
     * @param height the number of pixels or
     *  'auto' for automatic height detection or
     *  'initial' for initial height from the config
     */
    setHeight(height: 'auto' | 'initial' | number): Promise<void>;
}
/**
 * API to open, close and communicate with dialogs.
 * @since 13.2
 */
interface DialogScope {
    /**
     * Closes an open dialog, rejecting the promise returned by [[open]].
     * @since 13.2
     */
    cancel(): Promise<void>;
    /**
     * Closes an open dialog, resolving the promise returned by [[open]] with a value.
     * @param value The value selected in the dialog. The value should be compatible with [the structured clone
     * algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
     * @since 13.2
     */
    close(value: any): Promise<void>;
    /**
     * Opens a dialog.
     * @since 13.2
     */
    open(options: DialogProperties): Promise<void>;
    /**
     * @since 13.2
     * @returns A Promise that resolves with [[DialogProperties]] of the current dialog.
     */
    options(): Promise<DialogProperties>;
}
/**
 * Defines the different possible modes of a document editor.
 * @since 13.2
 */
declare enum DialogSize {
    Large = "large",
    Medium = "medium",
    Small = "small"
}
/**
 * Properties of a dialog.
 * @since 13.2
 */
interface DialogProperties {
    /**
     * A value to pass to the dialog. For example the current field value, that can be used to preselect an item in the
     * dialog. The value should be compatible with [the structured clone
     * algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
     * @since 13.2
     */
    value?: any;
    /**
     * The size of the dialog. Defaults to [[Medium]].
     * @since 13.2
     */
    size?: DialogSize;
    /**
     * Title of the dialog.
     * @since 13.2
     */
    title: string;
    /**
     * The URL to load the dialog contents from. Can be absolute or relative to the url of the UI extension.
     * @since 13.2
     */
    url: string;
}

/**
 * Main entry point of the ui-extension library.
 */
declare class UiExtension {
    /**
     * Registers a UI extension with the CMS.
     *
     * @returns A promise that resolves with a [[UiScope]] when the extension has been registered successfully.
     * The promise rejects with a [[UiExtensionError]] when registration failed.
     */
    static register(): Promise<UiScope>;
}
/**
 * Enable UiExtension.register() in ui-extension.min.js
 * @hidden don't include in the generated documentation since it duplicates UiExtension.register()
 */
declare const register: typeof UiExtension.register;

export default UiExtension;
export { ChannelScope, ChannelScopeEvents, DialogProperties, DialogScope, DialogSize, DocumentEditorMode, DocumentProperties, DocumentScope, DynamicProperties, Emitter, EventHandler, FieldScope, PageProperties, PageScope, PageScopeEvents, UiExtensionError, UiExtensionErrorCode, UiProperties, UiScope, UiStyling, register };