botbuilder-dialogs
Version:
A dialog stack based conversation manager for Microsoft BotBuilder.
198 lines (197 loc) • 8.92 kB
TypeScript
import { TurnContext } from 'botbuilder-core';
import { DialogInstance } from './dialog';
import { Dialog, DialogReason, DialogTurnResult } from './dialog';
import { DialogContext } from './dialogContext';
import { WaterfallStepContext } from './waterfallStepContext';
/**
* Function signature of an individual waterfall step.
*
* ```TypeScript
* type WaterfallStep<O extends object = {}> = (step: WaterfallStepContext<O>) => Promise<DialogTurnResult>;
* ```
*
* @param O (Optional) type of dialog options passed into the step.
* @param WaterfallStep.step Contextual information for the current step being executed.
*/
export declare type WaterfallStep<O extends object = {}> = (step: WaterfallStepContext<O>) => Promise<DialogTurnResult>;
/**
* A waterfall is a dialog that's optimized for prompting a user with a series of questions.
*
* @remarks
* Waterfalls accept a stack of functions which will be executed in sequence. Each waterfall step
* can ask a question of the user and the user's response will be passed to the next step in the
* waterfall via `step.result`. A special `step.value` object can be used to persist values between
* steps:
*
* ```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;
* ```
*/
export declare class WaterfallDialog<O extends object = {}> extends Dialog<O> {
private readonly steps;
/**
* Creates a new waterfall dialog containing the given array of steps.
*
* @remarks
* See the [addStep()](#addstep) function for details on creating a valid step function.
* @param dialogId Unique ID of the dialog within the component or set its being added to.
* @param steps (Optional) array of asynchronous waterfall step functions.
*/
constructor(dialogId: string, steps?: WaterfallStep<O>[]);
/**
* Gets the dialog version, composed of the ID and number of steps.
*
* @returns Dialog version, composed of the ID and number of steps.
*/
getVersion(): string;
/**
* Adds a new step to the waterfall.
*
* @remarks
* All step functions should be asynchronous and return a `DialogTurnResult`. The
* `WaterfallStepContext` passed into your function derives from `DialogContext` and contains
* numerous stack manipulation methods which return a `DialogTurnResult` so you can typically
* just return the result from the DialogContext method you call.
*
* The step function itself can be either an asynchronous closure:
*
* ```JavaScript
* const helloDialog = new WaterfallDialog('hello');
*
* helloDialog.addStep(async (step) => {
* await step.context.sendActivity(`Hello World!`);
* return await step.endDialog();
* });
* ```
*
* A named async function:
*
* ```JavaScript
* async function helloWorldStep(step) {
* await step.context.sendActivity(`Hello World!`);
* return await step.endDialog();
* }
*
* helloDialog.addStep(helloWorldStep);
* ```
*
* Or a class method that's been bound to its `this` pointer:
*
* ```JavaScript
* helloDialog.addStep(this.helloWorldStep.bind(this));
* ```
* @param step Asynchronous step function to call.
* @returns Waterfall dialog for fluent calls to `addStep()`.
*/
addStep(step: WaterfallStep<O>): this;
/**
* Called when the [WaterfallDialog](xref:botbuilder-dialogs.WaterfallDialog) is started and pushed onto the dialog stack.
*
* @param dc The [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current turn of conversation.
* @param options Optional, initial information to pass to the [Dialog](xref:botbuilder-dialogs.Dialog).
* @returns A Promise representing the asynchronous operation.
* @remarks
* If the task is successful, the result indicates whether the [Dialog](xref:botbuilder-dialogs.Dialog) is still
* active after the turn has been processed by the dialog.
*/
beginDialog(dc: DialogContext, options?: O): Promise<DialogTurnResult>;
/**
* Called when the [WaterfallDialog](xref:botbuilder-dialogs.WaterfallDialog) is _continued_, where it is the active dialog and the
* user replies with a new [Activity](xref:botframework-schema.Activity).
*
* @param dc The [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(dc: DialogContext): Promise<DialogTurnResult>;
/**
* Called when a child [WaterfallDialog](xref:botbuilder-dialogs.WaterfallDialog) completed its turn, returning control to this dialog.
*
* @param dc The [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current turn of the conversation.
* @param reason [Reason](xref:botbuilder-dialogs.DialogReason) 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.
*/
resumeDialog(dc: DialogContext, reason: DialogReason, result?: any): Promise<DialogTurnResult>;
/**
* Called when an individual waterfall step is being executed.
*
* @remarks
* SHOULD be overridden by derived class that want to add custom logging semantics.
*
* ```JavaScript
* class LoggedWaterfallDialog extends WaterfallDialog {
* async onStep(step) {
* console.log(`Executing step ${step.index} of the "${this.id}" waterfall.`);
* return await super.onStep(step);
* }
* }
* ```
* @param step Context object for the waterfall step to execute.
* @returns A promise with the DialogTurnResult.
*/
protected onStep(step: WaterfallStepContext<O>): Promise<DialogTurnResult>;
/**
* Executes a step of the [WaterfallDialog](xref:botbuilder-dialogs.WaterfallDialog).
*
* @param dc The [DialogContext](xref:botbuilder-dialogs.DialogContext) for the current turn of conversation.
* @param index The index of the current waterfall step to execute.
* @param reason The [Reason](xref:botbuilder-dialogs.DialogReason) the waterfall step is being executed.
* @param result Optional, result returned by a dialog called in the previous waterfall step.
* @returns A Promise that represents the work queued to execute.
*/
protected runStep(dc: DialogContext, index: number, reason: DialogReason, result?: any): Promise<DialogTurnResult>;
/**
* Called when the dialog is ending.
*
* @param context Context for the current turn of conversation.
* @param instance The instance of the current dialog.
* @param reason The reason the dialog is ending.
*/
endDialog(context: TurnContext, instance: DialogInstance, reason: DialogReason): Promise<void>;
/**
* Identifies the step name by its position index.
*
* @param index Step position
* @returns A string that identifies the step name.
*/
private waterfallStepName;
}
//# sourceMappingURL=waterfallDialog.d.ts.map