@enplug/sdk-dashboard 5.4.0 → 5.4.2-2.1-dev

package/types/dashboard.d.ts

@@ -1,196 +1,375 @@
-import { Asset, Button, DisplaySelectorCallback, FeedData, Layout, OpenConfirmOptions, ThemeAsset, EncodingStatusResult, UploaderOptions, UploadedFileResult, ApiDataConnectorOptions, DataConnectionConfig, AssetPreviewRequest, AssetPreviewData } from './external-types';
-import { BridgeBase } from './bridge/bridge-base';
-export declare class Dashboard {
-    private bridge;
-    /**
-     * The buttons most recently registered with the dashboard header.
-     * Stored locally so that we can respond to click events
-     * @type {Button[]}
-     */
-    private currentButtons;
-    /**
-     * Keeps track of whether the dashboard is loading mode so clients can check.
-     * @type {boolean}
-     */
-    private isLoadingCache;
-    constructor(bridge: BridgeBase);
-    /**
-     * Notifies the parent dashboard of a click in the child iFrame. Used to close
-     * dropdown windows etc which were opened in parent window and are unable to
-     * respond to click events in child iFrame.
-     *
-     * Event handler is automatically bound when the SDK is created.
-     */
-    click(): void;
-    /**
-     * Opens a confirm window asking the user to confirm their unsaved changes.
-     * If the user clicks the confirm button, the returned promise is resolved.
-     * Otherwise the error callback is called.
-     */
-    confirmUnsavedChanges(): Promise<any>;
-    /**
-     * Shows the error indicator.
-     * Should only be used after a call has been made to .loadingIndicator().
-     * @param {string} message
-     */
-    errorIndicator(message: string): Promise<any>;
-    /**
-     * Synchronously returns the current loading state.
-     * Updated asynchronously when this sender receives an acknowledgement
-     * of successful SDK call from the dashboard.
-     */
-    isLoading(): boolean;
-    /**
-     * Turns on the progress indicator, typically used during asynchronous actions.
-     * Note that the progress indicator will continue until a call is made to the
-     * errorIndicator or successIndicator APIs.
-     */
-    loadingIndicator(message: string): Promise<any>;
-    /**
-     * Navigates to url.
-     * @param {string} url Url to navigate to.
-     */
-    navigate(url: string): Promise<any>;
-    /**
-     * @deprecated use `navigateToZoning()`
-     * Navigate back from widget.
-     * @param {string} assetId Id of an asset to which to go back to.
-     */
-    navigateBack(assetId: string): Promise<any>;
-    /**
-     * Navigate to given relative dashboard url
-     */
-    navigateToUrl(url: string): Promise<any>;
-    /**
-     * Navigate back to zoning from widget.
-     * assetId is optional, fallback parameter for v1->v2 transition phase
-     */
-    navigateToZoning(assetId?: string): Promise<any>;
-    /**
-     * Opens a confirm window with Yes/No buttons and configurable messages.
-     * If the user clicks the Confirm button, the returned promise is resolved.
-     * Otherwise the promise is rejected.
-     * @param {OpenConfirmOpyions} options Confirm dialog options.
-     */
-    openConfirm(options: OpenConfirmOptions): Promise<any>;
-    /**
-     * Puts the page into error state.
-     */
-    pageError(): Promise<any>;
-    /**
-     * Controls the loading state for the entire page. Every application starts off in
-     * loading state, and must set pageLoading(false) to notify the dashboard that it
-     * has successfully loaded.
-     *
-     * Use .isLoading() to synchronously check current loading state.
-     * @param {boolean} bool Page loading state
-     */
-    pageLoading(bool: boolean): Promise<boolean>;
-    /**
-     * Puts the page into 404 state.
-     */
-    pageNotFound(): Promise<any>;
-    /**
-     * @deprecated use `previewAsset()`
-     * Opens app preview modal.
-     * @param {string} url
-     * @param {Asset<AssetValue>} asset
-     * @param {object} theme
-     * @param {object} layout
-     * @param {object} feedData
-     */
-    preview<AssetValue, ThemeValue, FeedType>(url: string, asset: Asset<AssetValue>, theme: ThemeAsset<ThemeValue>, layout?: Layout, feedData?: FeedData<FeedType>): Promise<any>;
-    /**
-     * Opens app asset preview modal.
-     */
-    previewAsset<TAssetValue = any, TThemeValue = any, TFeedType = any>(request: AssetPreviewRequest<TAssetValue, TThemeValue, TFeedType>): Promise<any>;
-    /**
-     * Get preview params for an app asset for custom preview handling
-     * @param appId
-     * @param asset
-     * @param origin (default: true) - custom origin url, when omitted or falsy, `window.location.origin` will be attached
-     */
-    getAssetPreviewData(appId: string, asset: Asset<any>, origin?: string | boolean): Promise<AssetPreviewData>;
-    /**
-     * Sets the current callback for the title bar breadcrumb display selector dropdown.
-     * Attaching a callback enables the dropdown, it is disabled by default.
-     * The title is reset when the dashboard changes routes.
-     *
-     * the callback is fired when a display is selected, the callback will get the ID
-     * value when a single display is fired, or null when the 'All' selection is selected
-     * @param {DisplaySelectorCallback} callback A function to be called every time a user changes current display
-     * with display selector
-     */
-    setDisplaySelectorCallback(callback: DisplaySelectorCallback): void;
-    /**
-     * Hides or shows the display dropdown selector in the page title breadcrumb bar.
-     * Send true to show the selector, false to hide it.
-     */
-    setDisplaySelectorVisibility(show: boolean): Promise<any>;
-    /**
-     * Sets the primary action buttons for a page in the titlebar.
-     *
-     * Accepts either a single button object, or an array of buttons.
-     * Each button must have a button.action callback.
-     * @param {Button[]|Button} buttons A button (single or array) to set on a header.
-     */
-    setHeaderButtons(buttons: Button[] | Button): void;
-    /**
-     * Sets the last part of the title bar breadcrumb.
-     * Set an empty title '' to clear the title.
-     * Re-setting this value wipes out the old one.
-     *
-     * The home/default page for an app should have no title set.
-     * @param {string} title A title to set.
-     */
-    setHeaderTitle(title: string): Promise<any>;
-    /**
-     * Shows the success indicator.
-     * Should only be used after a call has been made to .loadingIndicator().
-     * @param {string} message A message to show in a success toast.
-     */
-    successIndicator(message: string): Promise<any>;
-    /**
-     * Switches to account view aka "All" selection of instance selector or DisplayGroup view
-     */
-    switchToView(displayGroupId: any, displayGroupName: any): Promise<any>;
-    /**
-     * Uses upload interface and Enplug encoding service, returns uploaded object
-     * @param {UploaderOptions} options Filepicker options
-     */
-    upload(options: UploaderOptions): Promise<UploadedFileResult[]>;
-    /**
-     * Uses connect data interface, returns connection configuration object
-     * @param {ApiDataConnectorOptions} options Api Data Connector configuration options
-     */
-    connectData(options: ApiDataConnectorOptions): Promise<DataConnectionConfig>;
-    /**
-     * Creates new assets and begins encoding process
-     */
-    processAssetResource<T>(accountId: string, appId: string, assets: Array<Asset<T>>): Promise<any>;
-    /**
-     * Returns current encoding status of an asset
-     * @deprecated legacy FileStack upload flow
-     * @see resourcesEncodingStatus
-     */
-    encodeStatus(url: string): Promise<any>;
-    /**
-     * Returns current encoding statuses of resources or asset ids
-     * @param byAssetId if true, the provided ids are interpreted as asset ids, otherwise they are resource ids
-     */
-    resourcesEncodingStatus(ids: string[], byAssetId?: boolean): Promise<EncodingStatusResult[]>;
-    /**
-     * opens content interval settings dialog for ad-scheduler app
-     */
-    openContentIntervalSettingsDialog(appName: string, level: string, levelId: string): Promise<any>;
-    /**
-     * Lets dashboard know that the state of user changes in the app changed
-     * @param {boolean} hasUnsavedChanges Whether the app has unsaved changes.
-     */
-    setAppHasUnsavedChanges(hasUnsavedChanges: boolean): Promise<any>;
-    /**
-     * The last callback registered with the dashboard title bar.
-     * @type {DisplaySelectorCallback}
-     */
-    private currentDisplayCallback;
-}
+import { Asset, Button, DisplaySelectorCallback, FeedData, Layout, OpenConfirmOptions, ThemeAsset, EncodingStatusResult, UploaderOptions, UploadedFileResult, ApiDataConnectorOptions, DataConnectionConfig, AssetPreviewRequest, AssetPreviewData } from './external-types';
+import { BridgeBase } from './bridge/bridge-base';
+/**
+ * Dashboard API is a part of the Dashboard SDK. It can be used to present standardized User Interface elements.
+ * Use global `enplug.dashboard` object to access these methods.
+ *
+ * ```typescript title="Example usage of the Dashboard API"
+ * enplug.dashboard.pageLoading(false);
+ * ```
+ *
+ * **Useful commands**
+ *
+ * Header section:
+ * - {@link setHeaderTitle|`enplug.dashboard.setHeaderTitle()`} - sets header title
+ * - {@link setHeaderButtons|`enplug.dashboard.setHeaderButtons()`} - sets header buttons
+ * - {@link setDisplaySelectorCallback|`enplug.dashboard.setDisplaySelectorCallback()`} - sets Display Group selector callback
+ * - {@link setDisplaySelectorVisibility|`enplug.dashboard.setDisplaySelectorVisibility()`} - sets Display Group selector visibility
+ *
+ * Progress indicator:
+ * - {@link pageLoading|`enplug.dashboard.pageLoading()`} - sets the app's loader visibility
+ * - {@link loadingIndicator|`enplug.dashboard.loadingIndicator()`} - shows **Loading** indicator
+ * - {@link successIndicator|`enplug.dashboard.successIndicator()`} - shows **Success** indicator
+ * - {@link errorIndicator|`enplug.dashboard.errorIndicator()`} - shows **Error** indicator
+ *
+ * Dialogs:
+ * - {@link previewAsset|`enplug.dashboard.previewAsset()`} - shows asset preview
+ * - {@link upload|`enplug.dashboard.upload()`} - shows upload dialog
+ * - {@link openConfirm|`enplug.dashboard.openConfirm()`} - shows custom confirmation dialog
+ * - {@link confirmUnsavedChanges|`enplug.dashboard.confirmUnsavedChanges()`} - shows unsaved changes dialog
+ * - {@link setAppHasUnsavedChanges|`enplug.dashboard.setAppHasUnsavedChanges()`} - sets dashboard's navigation guard
+ */
+export declare class Dashboard {
+    private bridge;
+    /**
+     * The buttons most recently registered with the dashboard header.
+     * Stored locally so that we can respond to click events
+     */
+    private currentButtons;
+    /**
+     * Keeps track of whether the dashboard is loading mode so clients can check.
+     */
+    private isLoadingCache;
+    /** @internal */
+    constructor(bridge: BridgeBase);
+    /**
+     * @internal
+     * Notifies the parent dashboard of a click in the child iframe. Used to close
+     * dropdown windows, etc. which were opened in parent window and are unable to
+     * respond to click events in child iframe.
+     *
+     * Event handler is automatically bound when the SDK is created.
+     */
+    click(): void;
+    /**
+     * Opens a confirm window asking the user to confirm their unsaved changes.
+     *
+     * ```typescript title="Presenting Unsaved Changes dialog"
+     * try {
+     *   await enplug.dashboard.confirmUnsavedChanges();
+     *   // user confirmed - take action
+     * } catch {
+     *   // user cancelled
+     * }
+     * ```
+     *
+     * ![Unsaved Changes dialog](/img/dashboard-sdk/dashboard/dialog-hasunsavedchanges.png)<br />
+     * *Unsaved Changes dialog*
+     *
+     * @returns Resolves if dialog was confirmed, rejects otherwise.
+     */
+    confirmUnsavedChanges(): Promise<any>;
+    /**
+     * Shows the error indicator.
+     *
+     * ```typescript title="Presenting the error indicator"
+     * enplug.dashboard.errorIndicator('Asset could not be removed');
+     * ```
+     *
+     * ![Error indicator](/img/dashboard-sdk/dashboard/progress-error.png)
+     * *Error indicator*
+     *
+     * @param message - A message to show in the error toast.
+     *
+     * @returns Resolves after the error indicator shows up on screen.
+     */
+    errorIndicator(message: string): Promise<any>;
+    /**
+     * Synchronously returns the current loading state.
+     * Updated asynchronously when this sender receives an acknowledgement
+     * of successful SDK call from the dashboard.
+     *
+     * @see {@link pageLoading} to update the page loading state.
+     *
+     * @returns Current page loading state.
+     */
+    isLoading(): boolean;
+    /**
+     * Turns on the progress indicator, typically used during asynchronous actions.
+     *
+     * :::note
+     * Note that the progress indicator will continue until a call is made to the
+     * {@link errorIndicator} or {@link successIndicator} APIs.
+     * :::
+     *
+     * ```typescript title="Presenting the loading indicator"
+     * enplug.dashboard.loadingIndicator('Removing asset');
+     * ```
+     *
+     * ![Loading indicator](/img/dashboard-sdk/dashboard/progress-loading.png)
+     * *Loading indicator*
+     *
+     * @param message - A message to show in the loading toast.
+     *
+     * @returns Resolves after the loading indicator shows up on screen.
+     */
+    loadingIndicator(message: string): Promise<void>;
+    /**
+     * Navigate to given relative dashboard URL.
+     */
+    navigateToUrl(url: string): Promise<any>;
+    /**
+     * Navigate back to zoning from widget.
+     * @param assetId - optional, fallback parameter for v1-\>v2 transition phase
+     */
+    navigateToZoning(assetId?: string): Promise<any>;
+    /**
+     * Opens a confirm window with Yes/No buttons and configurable messages.
+     *
+     * ```typescript title="Presenting confirmation dialog"
+     * try {
+     *   await enplug.dashboard.openConfirm({
+     *     title: 'Delete asset?',
+     *     text: 'Are you sure you want to delete this asset? This action cannot be undone.',
+     *     cancelText: 'Cancel',
+     *     confirmText: 'Delete',
+     *     confirmClass: 'btn-danger'
+     *   });
+     *
+     *   // remove the asset
+     * } catch {
+     *   // user cancelled
+     * }
+     * ```
+     *
+     * ![Confirm dialog](/img/dashboard-sdk/dashboard/dialog-confirm.png)<br />
+     * *Confirm dialog*
+     *
+     * @param options - Confirm dialog options.
+     *
+     * @returns Resolves if Confirm button was clicked, rejects otherwise.
+     */
+    openConfirm(options: OpenConfirmOptions): Promise<any>;
+    /**
+     * Puts the page into error state.
+     *
+     * ![Page error](/img/dashboard-sdk/dashboard/page-error.png)<br />
+     * *Page error*
+     *
+     * @returns Resolves after the Dashboard shows the page error.
+     */
+    pageError(): Promise<void>;
+    /**
+     * Controls the loading state for the entire page. Every application starts off in
+     * loading state, and must set `pageLoading(false)` to notify the dashboard that it
+     * has successfully loaded.
+     *
+     * ```typescript title="Turning off the loading spinner after app has started"
+     * enplug.dashboard.pageLoading(false);
+     * ```
+     *
+     * ![Page Loading spinner](/img/dashboard-sdk/dashboard/pageloading-spinner.png)<br />
+     * *Page Loading spinner*
+     *
+     * @param isLoading - Page loading state:<br />
+     * `false` - hides the loader and shows the app,<br />
+     * `true` - shows the loader and hides the app.
+     *
+     * @returns Resolves after the loading state has been updated by the Dashboard.
+     */
+    pageLoading(isLoading: boolean): Promise<boolean>;
+    /**
+     * Puts the page into not found (404) state.
+     *
+     * ![Page not available](/img/dashboard-sdk/dashboard/page-404.png)<br />
+     * *Page not available*
+     *
+     * @returns Resolves when after the Dashboard shows the page not found error.
+     */
+    pageNotFound(): Promise<void>;
+    /**
+     * @deprecated use {@link previewAsset}
+     *
+     * Opens app preview modal.
+     */
+    preview<AssetValue, ThemeValue, FeedType>(url: string, asset: Asset<AssetValue>, theme: ThemeAsset<ThemeValue>, layout?: Layout, feedData?: FeedData<FeedType>): Promise<any>;
+    /**
+     * Opens asset preview modal.
+     *
+     * ![Asset preview modal](/img/dashboard-sdk/dashboard/previewAsset.png)<br />
+     * *Asset preview modal*
+     *
+     * ```typescript title="Previewing an asset"
+     * function showPreview(asset: Asset<AssetModel>) {
+     *   enplug.dashboard.previewAsset({ asset });
+     * }
+     * ```
+     *
+     * The above code opens the preview dialog with provided data.
+     * This method allows many preview customizations, see {@link AssetPreviewRequest}.
+     *
+     * :::note
+     * The app inside of the preview modal is presented in an iframe and the app is provided with basic SDK functionalities
+     * needed to display the asset only. The app's Player URL from app's definition will be used.
+     * The app is not run in a WebPlayer environment, so the behavior might be different.
+     * Most SDK calls will have no effect.
+     * :::
+     *
+     * @param TAssetValue - Model of asset's value
+     * @param TThemeValue - Model of theme's value (optional)
+     * @param TFeedType - Model of the feed (used for social apps)
+     *
+     * @returns Resolves after the preview modal gets closed.
+     */
+    previewAsset<TAssetValue = any, TThemeValue = any, TFeedType = any>(request: AssetPreviewRequest<TAssetValue, TThemeValue, TFeedType>): Promise<void>;
+    /**
+     * @internal
+     * Get preview parameters for an app asset for custom preview handling.
+     * @param origin - (default: true) - custom origin url, when omitted or falsy, `window.location.origin` will be attached
+     */
+    getAssetPreviewData(appId: string, asset: Asset<any>, origin?: string | boolean): Promise<AssetPreviewData>;
+    /**
+     * Sets the current callback for the title bar breadcrumb Display Group selector dropdown.
+     * Attaching a callback enables the dropdown and resets the title.
+     *
+     * The callback is fired when a Display Group is selected from the dropdown, the callback will get the ID
+     * value when a single display is fired, or null when the whole 'Library' selection.
+     *
+     * ```typescript title="Setting up the Display Group selector"
+     * enplug.dashboard.setDisplaySelectorCallback(async () => {
+     *   // update your asset list using enplug.account.getAssets() which will return
+     *   // the assets assigned to the selected Display Group only
+     *   yourAssetList = await enplug.account.getAssets();
+     * });
+     * ```
+     *
+     * ![Display Group selector dropdown](/img/dashboard-sdk/dashboard/display-group-selector-dropdown.png)<br />
+     * *Display Group selector dropdown*
+     *
+     * @param callback - A function to be called every time a user changes current Display Group
+     * with the dropdown selector. The callback should reload the asset list to get the filtered version.
+     *
+     * @returns Promise which resolves after the command gets executed by the Dashboard.
+     */
+    setDisplaySelectorCallback(callback: DisplaySelectorCallback): Promise<void>;
+    /**
+     * Hides or shows the Display Group dropdown selector in the page title breadcrumb bar.
+     * Send true to show the selector, false to hide it.
+     *
+     * The Display Group selector dropdown can be used to filter assets currently deployed to a specific Display Group.
+     * You can view all the saved assets by account for your app by selecting the 'Library' view from the dropdown on the upper left.
+     *
+     * ![Display Group selector dropdown](/img/dashboard-sdk/dashboard/display-group-selector-dropdown.png)
+     * *Display Group selector dropdown*
+     *
+     * @returns Promise which resolves after the command gets executed by the Dashboard.
+     */
+    setDisplaySelectorVisibility(show: boolean): Promise<void>;
+    /**
+     * Sets the action buttons for a page in the titlebar.
+     *
+     * Accepts either a single button object, or an array of buttons.
+     * Each button must have a button.action callback.
+     *
+     * ```typescript title="Updating the buttons"
+     * function updateButtons(hasUnsavedChanges: boolean) {
+     *   enplug.dashboard.setHeaderButtons([{
+     *     text: 'My Signs',
+     *     action: () => { \/* your code to navigate back to the Asset list *\/ },
+     *     class: 'btn-default'
+     *   }, {
+     *     text: 'Save',
+     *     action: () => { \/* your code saving the asset *\/ },
+     *     class: 'btn-primary',
+     *     disabled: !hasUnsavedChanges // this will disable the button if there are no unsaved changes
+     *   }]);
+     * }
+     * ```
+     *
+     * ![Header buttons](/img/dashboard-sdk/dashboard/header-buttons.png)<br />
+     * *Header buttons*
+     *
+     * @param buttons - A button (single or array) to set on a header.
+     *
+     * @returns Resolves after the buttons get updated.
+     */
+    setHeaderButtons(buttons: Button[] | Button): Promise<void>;
+    /**
+     * Sets the last part of the title bar breadcrumb.
+     * Set an empty title '' to clear the title.
+     * Re-setting this value wipes out the old one.
+     *
+     * The home/default page for an app should have no title set.
+     *
+     * ```typescript title="Updating header's title"
+     * enplug.dashboard.setHeaderTitle('Setup');
+     * ```
+     *
+     * ![Header title](/img/dashboard-sdk/dashboard/header-title.png)
+     * *Header title section*
+     *
+     * @param title - A title to set.
+     *
+     * @returns Resolves after the title has been modified.
+     */
+    setHeaderTitle(title: string): Promise<void>;
+    /**
+     * Shows the success indicator.
+     *
+     * ```typescript title="Presenting the success indicator"
+     * enplug.dashboard.successIndicator('Asset removed');
+     * ```
+     *
+     * ![Success indicator](/img/dashboard-sdk/dashboard/progress-success.png)
+     * *Success indicator*
+     *
+     * @param message - A message to show in the success toast.
+     *
+     * @returns Resolves after the success indicator shows up on screen.
+     */
+    successIndicator(message: string): Promise<void>;
+    /**
+     * Switches to account view "Library"/All selection of instance selector or Display Group view.
+     */
+    switchToView(displayGroupId: string, displayGroupName: string): Promise<any>;
+    /**
+     * Uses upload interface and Enplug encoding service, returns uploaded object
+     * @param options - Filepicker options
+     */
+    upload(options: UploaderOptions): Promise<UploadedFileResult[]>;
+    /**
+     * Uses connect data interface, returns connection configuration object.
+     * @param options - API Data Connector configuration options.
+     */
+    connectData(options: ApiDataConnectorOptions | ApiDataConnectorOptions[]): Promise<DataConnectionConfig>;
+    /**
+     * @internal
+     * Returns current encoding status of an asset.
+     * @deprecated legacy FileStack upload flow
+     * @see resourcesEncodingStatus
+     */
+    encodeStatus(url: string): Promise<any>;
+    /**
+     * Returns current encoding statuses of resources or asset IDs.
+     * @param byAssetId - If `true`, the provided IDs are interpreted as asset IDs, otherwise they are resource IDs.
+     */
+    resourcesEncodingStatus(ids: string[], byAssetId?: boolean): Promise<EncodingStatusResult[]>;
+    /**
+     * Opens content interval settings dialog for Ad Scheduler app.
+     */
+    openContentIntervalSettingsDialog(appName: string, level: string, levelId: string): Promise<any>;
+    /**
+     * Lets dashboard know that the state of user changes in the app changed.
+     *
+     * @param hasUnsavedChanges - Whether the app has unsaved changes.
+     */
+    setAppHasUnsavedChanges(hasUnsavedChanges: boolean): Promise<any>;
+    /**
+     * The last callback registered with the dashboard title bar.
+     */
+    private currentDisplayCallback;
+    /**
+     * Closes current window, used in templates after user has successfully authenticated with sharepoint user.
+     */
+    closeWindow(): Promise<any>;
+}