@microsoft/teams-js/dist/esm/packages/teams-js/dts/public/pages/config.d.ts

Microsoft Client SDK for building app for Microsoft hosts

/**
 * Provides APIs to interact with the configuration-specific part of the SDK.
 * This object is usable only on the configuration frame.
 * @module
 */
import { handlerFunctionType, InstanceConfig, removeEventType, saveEventType } from './pages';
/**
 * @hidden
 * Hide from docs because this function is only used during initialization
 *
 * Adds register handlers for settings.save and settings.remove upon initialization. Function is called in {@link app.initializeHelper}
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function initialize(): void;
/**
 * Sets the validity state for the configuration.
 * The initial value is false, so the user cannot save the configuration until this is called with true.
 * @param validityState - Indicates whether the save or remove button is enabled for the user.
 */
export declare function setValidityState(validityState: boolean): void;
/**
 * Sets the configuration for the current instance.
 * This is an asynchronous operation; calls to getConfig are not guaranteed to reflect the changed state.
 * @param instanceConfig - The desired configuration for this instance.
 * @returns Promise that resolves when the operation has completed.
 */
export declare function setConfig(instanceConfig: InstanceConfig): Promise<void>;
/**
 * Registers a handler for when the user attempts to save the configuration. This handler should be used
 * to create or update the underlying resource powering the content.
 * The object passed to the handler must be used to notify whether to proceed with the save.
 * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
 * @param handler - The handler to invoke when the user selects the Save button.
 */
export declare function registerOnSaveHandler(handler: saveEventType): void;
/**
 * @hidden
 * Undocumented helper function with shared code between deprecated version and current version of the registerOnSaveHandler API.
 *
 * @internal
 * Limited to Microsoft-internal use
 *
 * @param apiVersionTag - The API version tag, which is used for telemetry, composed by API version number and source API name.
 * @param handler - The handler to invoke when the user selects the Save button.
 * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
 */
export declare function registerOnSaveHandlerHelper(apiVersionTag: string, handler: (evt: SaveEvent) => void, versionSpecificHelper?: () => void): void;
/**
 * Registers a handler for user attempts to remove content. This handler should be used
 * to remove the underlying resource powering the content.
 * The object passed to the handler must be used to indicate whether to proceed with the removal.
 * Only one handler may be registered at a time. Subsequent registrations will override the first.
 * @param handler - The handler to invoke when the user selects the Remove button.
 */
export declare function registerOnRemoveHandler(handler: removeEventType): void;
/**
 * @hidden
 * Undocumented helper function with shared code between deprecated version and current version of the registerOnRemoveHandler API.
 *
 * @internal
 * Limited to Microsoft-internal use
 *
 * @param apiVersionTag - The API version tag, which is used for telemetry, composed by API version number and source API name.
 * @param handler - The handler to invoke when the user selects the Remove button.
 * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
 */
export declare function registerOnRemoveHandlerHelper(apiVersionTag: string, handler: (evt: RemoveEvent) => void, versionSpecificHelper?: () => void): void;
/**
 * Registers a handler for when the tab configuration is changed by the user
 * @param handler - The handler to invoke when the user clicks on Settings.
 */
export declare function registerChangeConfigHandler(handler: handlerFunctionType): void;
/**
 * Describes the results of the settings.save event. Includes result, notifySuccess, and notifyFailure
 * to indicate the return object (result) and the status of whether the settings.save call succeeded or not and why.
 */
export interface SaveEvent {
    /**
     * Object containing properties passed as arguments to the settings.save event.
     */
    result: SaveParameters;
    /**
     * Indicates that the underlying resource has been created and the config can be saved.
     */
    notifySuccess(): void;
    /**
     * Indicates that creation of the underlying resource failed and that the config cannot be saved.
     * @param reason - Specifies a reason for the failure. If provided, this string is displayed to the user; otherwise a generic error is displayed.
     */
    notifyFailure(reason?: string): void;
}
/**
 * Describes the results of the settings.remove event. Includes notifySuccess, and notifyFailure
 * to indicate the status of whether the settings.save call succeeded or not and why.
 */
export interface RemoveEvent {
    /**
     * Indicates that the underlying resource has been removed and the content can be removed.
     */
    notifySuccess(): void;
    /**
     * Indicates that removal of the underlying resource failed and that the content cannot be removed.
     * @param reason - Specifies a reason for the failure. If provided, this string is displayed to the user; otherwise a generic error is displayed.
     */
    notifyFailure(reason?: string): void;
}
/**
 * Parameters used in the settings.save event
 */
export interface SaveParameters {
    /**
     * Connector's webhook Url returned as arguments to settings.save event as part of user clicking on Save
     */
    webhookUrl?: string;
}
/**
 * Checks if the pages.config capability is supported by the host
 * @returns boolean to represent whether the pages.config capability is supported
 *
 * @throws Error if {@linkcode app.initialize} has not successfully completed
 */
export declare function isSupported(): boolean;