botbuilder-dialogs/_ts3.4/lib/componentDialog.d.ts

A dialog stack based conversation manager for Microsoft BotBuilder.

/**
 * @module botbuilder-dialogs
 */
/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */
import { TurnContext } from 'botbuilder-core';
import { Dialog, DialogInstance, DialogReason, DialogTurnResult } from './dialog';
import { DialogContext } from './dialogContext';
import { DialogContainer } from './dialogContainer';
/**
 * Base class for a dialog that contains other child dialogs.
 *
 * @remarks
 * Component dialogs let you break your bot's logic up into components that can themselves be added
 * as a dialog to another `ComponentDialog` or `DialogSet`. Components can also be exported as part
 * of a node package and used within other bots.
 *
 * To define a new component derive a class from ComponentDialog and add your child dialogs within
 * the classes constructor:
 *
 * ```JavaScript
 * const { ComponentDialog, WaterfallDialog, TextPrompt, NumberPrompt } = require('botbuilder-dialogs');
 *
 * class FillProfileDialog extends ComponentDialog {
 *     constructor(dialogId) {
 *         super(dialogId);
 *
 *         // Add control flow dialogs
 *         this.addDialog(new WaterfallDialog('start', [
 *             async (step) => {
 *                 // Ask user their name
 *                 return await step.prompt('namePrompt', `What's your name?`);
 *             },
 *             async (step) => {
 *                 // Remember the users answer
 *                 step.values['name'] = step.result;
 *
 *                 // Ask user their age.
 *                 return await step.prompt('agePrompt', `Hi ${step.values['name']}. How old are you?`);
 *             },
 *             async (step) => {
 *                 // Remember the users answer
 *                 step.values['age'] = step.result;
 *
 *                 // End the component and return the completed profile.
 *                 return await step.endDialog(step.values);
 *             }
 *         ]));
 *
 *         // Add prompts
 *         this.addDialog(new TextPrompt('namePrompt'));
 *         this.addDialog(new NumberPrompt('agePrompt'))
 *     }
 * }
 * module.exports.FillProfileDialog = FillProfileDialog;
 * ```
 *
 * You can then add new instances of your component to another `DialogSet` or `ComponentDialog`:
 *
 * ```JavaScript
 * const dialogs = new DialogSet(dialogState);
 * dialogs.add(new FillProfileDialog('fillProfile'));
 * ```
 * @param O (Optional) options that can be passed into the `DialogContext.beginDialog()` method.
 */
export declare class ComponentDialog<O extends object = {}> extends DialogContainer<O> {
    /**
     * ID of the child dialog that should be started anytime the component is started.
     *
     * @remarks
     * This defaults to the ID of the first child dialog added using [addDialog()](#adddialog).
     */
    protected initialDialogId: string;
    /**
     * Called when the dialog is started and pushed onto the parent's dialog stack.
     * By default, this calls the
     * Dialog.BeginDialogAsync(DialogContext, object, CancellationToken) method
     * of the component dialog's initial dialog, as defined by InitialDialogId.
     * Override this method in a derived class to implement interrupt logic.
     *
     * @param outerDC The parent [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current turn of conversation.
     * @param options Optional, initial information to pass to the dialog.
     * @returns A Promise representing the asynchronous operation.
     * @remarks
     * If the task is successful, the result indicates whether the dialog is still
     * active after the turn has been processed by the dialog.
     */
    beginDialog(outerDC: DialogContext, options?: O): Promise<DialogTurnResult>;
    /**
     * Called when the dialog is _continued_, where it is the active dialog and the
     * user replies with a new [Activity](xref:botframework-schema.Activity).
     * If this method is *not* overridden, the dialog automatically ends when the user replies.
     *
     * @param outerDC The parent [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current turn of conversation.
     * @returns A Promise representing the asynchronous operation.
     * @remarks
     * If the task is successful, the result indicates whether the dialog is still
     * active after the turn has been processed by the dialog. The result may also contain a
     * return value.
     */
    continueDialog(outerDC: DialogContext): Promise<DialogTurnResult>;
    /**
     * Called when a child dialog on the parent's dialog stack completed this turn, returning
     * control to this dialog component.
     *
     * @param outerDC The [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current turn of conversation.
     * @param _reason Reason why the dialog resumed.
     * @param _result Optional, value returned from the dialog that was called. The type
     * of the value returned is dependent on the child dialog.
     * @returns A Promise representing the asynchronous operation.
     * @remarks
     * If the task is successful, the result indicates whether this dialog is still
     * active after this dialog turn has been processed.
     * Generally, the child dialog was started with a call to
     * beginDialog(DialogContext, object) in the parent's
     * context. However, if the DialogContext.replaceDialog(string, object) method
     * is called, the logical child dialog may be different than the original.
     * If this method is *not* overridden, the dialog automatically calls its
     * RepromptDialog(ITurnContext, DialogInstance) when the user replies.
     */
    resumeDialog(outerDC: DialogContext, _reason: DialogReason, _result?: any): Promise<DialogTurnResult>;
    /**
     * Called when the dialog should re-prompt the user for input.
     *
     * @param context The [TurnContext](xref:botbuilder-core.TurnContext) object for this turn.
     * @param instance State information for this dialog.
     * @returns A Promise representing the asynchronous operation.
     */
    repromptDialog(context: TurnContext, instance: DialogInstance): Promise<void>;
    /**
     * Called when the [Dialog](xref:botbuilder-dialogs.Dialog) is ending.
     *
     * @param context The [TurnContext](xref:botbuilder-core.TurnContext) object for this turn.
     * @param instance State information associated with the instance of this component
     * [Dialog](xref:botbuilder-dialogs.Dialog) on its parent's dialog stack.
     * @param reason Reason why the [Dialog](xref:botbuilder-dialogs.Dialog) ended.
     * @returns A Promise representing the asynchronous operation.
     * @remarks When this method is called from the parent dialog's context, the component [Dialog](xref:botbuilder-dialogs.Dialog)
     * cancels all of the dialogs on its inner dialog stack before ending.
     */
    endDialog(context: TurnContext, instance: DialogInstance, reason: DialogReason): Promise<void>;
    /**
     * Adds a child [Dialog](xref:botbuilder-dialogs.Dialog) or prompt to the components internal [DialogSet](xref:botbuilder-dialogs.DialogSet).
     *
     * @param dialog The child [Dialog](xref:botbuilder-dialogs.Dialog) or prompt to add.
     * @returns The [ComponentDialog](xref:botbuilder-dialogs.ComponentDialog) after the operation is complete.
     * @remarks
     * The [Dialog.id](xref:botbuilder-dialogs.Dialog.id) of the first child added to the component will be assigned to the initialDialogId property.
     */
    addDialog(dialog: Dialog): this;
    /**
     * Creates the inner dialog context
     *
     * @param outerDC the outer dialog context
     * @returns The created Dialog Context.
     */
    createChildContext(outerDC: DialogContext): DialogContext;
    /**
     * Called anytime an instance of the component has been started.
     *
     * @remarks
     * SHOULD be overridden by components that wish to perform custom interruption logic. The
     * default implementation calls `innerDC.beginDialog()` with the dialog assigned to
     * [initialDialogId](#initialdialogid).
     * @param innerDC Dialog context for the components internal `DialogSet`.
     * @param options (Optional) options that were passed to the component by its parent.
     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
     */
    protected onBeginDialog(innerDC: DialogContext, options?: O): Promise<DialogTurnResult>;
    /**
     * Called anytime a multi-turn component receives additional activities.
     *
     * @remarks
     * SHOULD be overridden by components that wish to perform custom interruption logic. The
     * default implementation calls `innerDC.continueDialog()`.
     * @param innerDC Dialog context for the components internal `DialogSet`.
     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
     */
    protected onContinueDialog(innerDC: DialogContext): Promise<DialogTurnResult>;
    /**
     * Called when the component is ending.
     *
     * @remarks
     * If the `reason` code is equal to `DialogReason.cancelCalled`, then any active child dialogs
     * will be cancelled before this method is called.
     * @param _context Context for the current turn of conversation.
     * @param _instance The components instance data within its parents dialog stack.
     * @param _reason The reason the component is ending.
     * @returns A promise representing the asynchronous operation.
     */
    protected onEndDialog(_context: TurnContext, _instance: DialogInstance, _reason: DialogReason): Promise<void>;
    /**
     * Called when the component has been requested to re-prompt the user for input.
     *
     * @remarks
     * The active child dialog will have already been asked to reprompt before this method is called.
     * @param _context Context for the current turn of conversation.
     * @param _instance The instance of the current dialog.
     * @returns A promise representing the asynchronous operation.
     */
    protected onRepromptDialog(_context: TurnContext, _instance: DialogInstance): Promise<void>;
    /**
     * Called when the components last active child dialog ends and the component is ending.
     *
     * @remarks
     * SHOULD be overridden by components that wish to perform custom logic before the component
     * ends.  The default implementation calls `outerDC.endDialog()` with the `result` returned
     * from the last active child dialog.
     * @param outerDC Dialog context for the parents `DialogSet`.
     * @param result Result returned by the last active child dialog. Can be a value of `undefined`.
     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
     */
    protected endComponent(outerDC: DialogContext, result: any): Promise<DialogTurnResult>;
    /**
     * @private
     * @param context [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current turn of conversation with the user.
     * @param instance [DialogInstance](xref:botbuilder-dialogs.DialogInstance) which contains the current state information for this dialog.
     * @returns A new [DialogContext](xref:botbuilder-dialogs.DialogContext) instance.
     * @remarks
     * You should only call this if you don't have a dc to work with (such as OnResume())
     */
    private createInnerDC;
}
//# sourceMappingURL=componentDialog.d.ts.map