From e54b8021c335ba4bb18ff9b09fa007254bb6279e Mon Sep 17 00:00:00 2001 From: Steven Ickman Date: Sat, 21 Apr 2018 13:25:17 -0700 Subject: [PATCH 1/5] Reference docs for botbuilder-choices --- doc/botbuilder-choices/README.md | 108 +++++++++++++++--- .../botbuilder_choices.choicefactory.md | 106 +++++++++++++---- .../interfaces/botbuilder_choices.choice.md | 33 +++++- ...botbuilder_choices.choicefactoryoptions.md | 13 ++- .../botbuilder_choices.findchoicesoptions.md | 21 ++-- .../botbuilder_choices.findvaluesoptions.md | 13 ++- .../botbuilder_choices.foundchoice.md | 13 ++- .../botbuilder_choices.foundvalue.md | 11 +- .../botbuilder_choices.modelresult.md | 30 ++++- .../botbuilder_choices.sortedvalue.md | 8 +- .../interfaces/botbuilder_choices.token.md | 24 +++- .../botbuilder-choices/lib/choiceFactory.d.ts | 105 ++++++++++++++++- .../botbuilder-choices/lib/choiceFactory.js | 99 +++++++++++++++- .../lib/choiceFactory.js.map | 2 +- .../botbuilder-choices/lib/findChoices.d.ts | 90 ++++++++++++++- .../botbuilder-choices/lib/findChoices.js | 31 +++++ .../botbuilder-choices/lib/findChoices.js.map | 2 +- .../botbuilder-choices/lib/findValues.d.ts | 30 ++++- .../botbuilder-choices/lib/findValues.js | 10 +- .../botbuilder-choices/lib/findValues.js.map | 2 +- .../botbuilder-choices/lib/modelResult.d.ts | 12 ++ .../lib/recognizeChoices.d.ts | 33 ++++++ .../lib/recognizeChoices.js | 33 ++++++ .../lib/recognizeChoices.js.map | 2 +- .../botbuilder-choices/lib/tokenizer.d.ts | 42 ++++++- libraries/botbuilder-choices/lib/tokenizer.js | 24 +++- .../botbuilder-choices/lib/tokenizer.js.map | 2 +- .../botbuilder-choices/src/choiceFactory.ts | 108 +++++++++++++++++- .../botbuilder-choices/src/findChoices.ts | 90 ++++++++++++++- .../botbuilder-choices/src/findValues.ts | 30 ++++- .../botbuilder-choices/src/modelResult.ts | 13 ++- .../src/recognizeChoices.ts | 33 ++++++ libraries/botbuilder-choices/src/tokenizer.ts | 47 +++++++- 33 files changed, 1101 insertions(+), 119 deletions(-) diff --git a/doc/botbuilder-choices/README.md b/doc/botbuilder-choices/README.md index 07696f2943..ca75675199 100644 --- a/doc/botbuilder-choices/README.md +++ b/doc/botbuilder-choices/README.md @@ -46,9 +46,14 @@ **Τ TokenizerFunction**: *`function`* -*Defined in [libraries/botbuilder-choices/lib/tokenizer.d.ts:14](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/tokenizer.d.ts#L14)* +*Defined in [libraries/botbuilder-choices/lib/tokenizer.d.ts:32](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/tokenizer.d.ts#L32)* + +:package: **botbuilder-choices** + +Signature for an alternate word breaker that can be passed to `recognizeChoices()`, `findChoices()`, or `findValues()`. The `defaultTokenizer()` is fairly simple and only breaks on spaces and punctuation. + #### Type declaration ►(text: *`string`*, locale?: *`string`*): [Token](interfaces/botbuilder_choices.token.md)[] @@ -58,8 +63,8 @@ | Param | Type | Description | | ------ | ------ | ------ | -| text | `string` | - | -| locale | `string` | - | +| text | `string` | The text to be tokenized. | +| locale | `string` | (Optional) locale of the text if known. | @@ -84,11 +89,30 @@ ___ -*Defined in [libraries/botbuilder-choices/lib/tokenizer.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/tokenizer.d.ts#L19)* +*Defined in [libraries/botbuilder-choices/lib/tokenizer.d.ts:59](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/tokenizer.d.ts#L59)* + +:package: **botbuilder-choices** -Simple tokenizer that breaks on spaces and punctuation. The only normalization done is to lowercase +Simple tokenizer that breaks on spaces and punctuation. The only normalization done is to lowercase the tokens. Developers can wrap this tokenizer with their own function to perform additional normalization like [stemming](https://github.com/words/stemmer). + +**Usage Example** + + const { recognizeChoices, defaultTokenizer } = require('botbuilder-choices'); + const stemmer = require('stemmer'); + + function customTokenizer(text, locale) { + const tokens = defaultTokenizer(text, locale); + tokens.forEach((t) => { + t.normalized = stemmer(t.normalized); + }); + return tokens; + } + + const choices = ['red', 'green', 'blue']; + const utterance = context.activity.text; + const results = recognizeChoices(utterance, choices, { tokenizer: customTokenizer }); **Parameters:** @@ -118,17 +142,38 @@ ___ -*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:42](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findChoices.d.ts#L42)* +*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:122](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findChoices.d.ts#L122)* + + +:package: **botbuilder-choices** + +Mid-level search function for recognizing a choice in an utterance. This function is layered above `findValues()` and simply determines all of the synonyms that should be searched for before calling `findValues()` to perform the actual search. The `recognizeChoices()` function is layered above this function and adds the ability to select a choice by index or ordinal position in the list. Calling this particular function is useful when you don't want the index and ordinal position recognition done by `recognizeChoices()`. + +**Usage Example** + + const { findChoices } = require('botbuilder-choices'); + + const choices = ['red', 'green', 'blue']; + const utterance = context.activity.text; + const results = findChoices(utterance, choices); + if (results.length == 1) { + await context.sendActivity(`I like ${results[0].resolution.value} too!`); + } else if (results.length > 1) { + const ambiguous = results.map((r) => r.resolution.value); + await context.sendActivity(ChoiceFactory.forChannel(context, ambiguous, `Which one?`)); + } else { + await context.sendActivity(ChoiceFactory.forChannel(context, choices, `I didn't get that... Which color?`)); + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| utterance | `string` | - | -| choices | (`string`⎮[Choice](interfaces/botbuilder_choices.choice.md))[] | - | -| options | [FindChoicesOptions](interfaces/botbuilder_choices.findchoicesoptions.md) | - | +| utterance | `string` | The text or user utterance to search over. For an incoming 'message' activity you can simply use `context.activity.text`. | +| choices | (`string`⎮[Choice](interfaces/botbuilder_choices.choice.md))[] | List of choices to search over. | +| options | [FindChoicesOptions](interfaces/botbuilder_choices.findchoicesoptions.md) | (Optional) options used to tweak the search that's performed. | @@ -150,20 +195,22 @@ ___ -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:57](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L57)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:83](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L83)* + +:package: **botbuilder-choices** -Looks for a set of values within an utterance. +INTERNAL: Low-level function that searches for a set of values within an utterance. Higher level functions like `findChoices()` and `recognizeChoices()` are layered above this function. In most cases its easier to just call one of the higher level functions instead but this function contains the fuzzy search algorithm that drives choice recognition. **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| utterance | `string` | - | -| values | [SortedValue](interfaces/botbuilder_choices.sortedvalue.md)[] | - | -| options | [FindValuesOptions](interfaces/botbuilder_choices.findvaluesoptions.md) | - | +| utterance | `string` | The text or user utterance to search over. | +| values | [SortedValue](interfaces/botbuilder_choices.sortedvalue.md)[] | List of values to search over. | +| options | [FindValuesOptions](interfaces/botbuilder_choices.findvaluesoptions.md) | (Optional) options used to tweak the search that's performed. | @@ -185,17 +232,42 @@ ___ -*Defined in [libraries/botbuilder-choices/lib/recognizeChoices.d.ts:10](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/recognizeChoices.d.ts#L10)* +*Defined in [libraries/botbuilder-choices/lib/recognizeChoices.d.ts:43](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/recognizeChoices.d.ts#L43)* + + + +:package: **botbuilder-choices** + +High level function for recognizing a choice in a users utterance. This is layered above the `findChoices()` function and adds logic to let the user specify their choice by index (they can say "one" to pick `choice[0]`) or ordinal position (they can say "the second one" to pick `choice[1]`.) The users utterance is recognized in the following order: + +* By name using `findChoices()`. +* By 1's based ordinal position. +* By 1's based index position. + +**Usage Example** + + const { recognizeChoices } = require('botbuilder-choices'); + const choices = ['red', 'green', 'blue']; + const utterance = context.activity.text; + const results = recognizeChoices(utterance, choices); + if (results.length == 1) { + await context.sendActivity(`I like ${results[0].resolution.value} too!`); + } else if (results.length > 1) { + const ambiguous = results.map((r) => r.resolution.value); + await context.sendActivity(ChoiceFactory.forChannel(context, ambiguous, `Which one?`)); + } else { + await context.sendActivity(ChoiceFactory.forChannel(context, choices, `I didn't get that... Which color?`)); + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| utterance | `string` | - | -| choices | (`string`⎮[Choice](interfaces/botbuilder_choices.choice.md))[] | - | -| options | [FindChoicesOptions](interfaces/botbuilder_choices.findchoicesoptions.md) | - | +| utterance | `string` | The text or user utterance to search over. For an incoming 'message' activity you can simply use `context.activity.text`. | +| choices | (`string`⎮[Choice](interfaces/botbuilder_choices.choice.md))[] | List of choices to search over. | +| options | [FindChoicesOptions](interfaces/botbuilder_choices.findchoicesoptions.md) | (Optional) options used to tweak the search that's performed. | diff --git a/doc/botbuilder-choices/classes/botbuilder_choices.choicefactory.md b/doc/botbuilder-choices/classes/botbuilder_choices.choicefactory.md index 8d0ab8b6f4..725dd1d3e4 100644 --- a/doc/botbuilder-choices/classes/botbuilder_choices.choicefactory.md +++ b/doc/botbuilder-choices/classes/botbuilder_choices.choicefactory.md @@ -4,6 +4,18 @@ # Class: ChoiceFactory + +:package: **botbuilder-choices** + +A set of utility functions to assist with the formatting a 'message' activity containing a list of choices. + +**Usage Example** + + const { ChoiceFactory } = require('botbuilder-choices'); + + const message = ChoiceFactory.forChannel(context, ['red', 'green', 'blue'], `Pick a color.`); + await context.sendActivity(message); + ## Index ### Methods @@ -22,23 +34,36 @@ ### «Static» forChannel -► **forChannel**(channelOrContext: *`string`⎮`BotContext`*, choices: *(`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[]*, text?: *`string`*, speak?: *`string`*, options?: *[ChoiceFactoryOptions](../interfaces/botbuilder_choices.choicefactoryoptions.md)*): `Partial`.<`Activity`> +► **forChannel**(channelOrContext: *`string`⎮`TurnContext`*, choices: *(`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[]*, text?: *`string`*, speak?: *`string`*, options?: *[ChoiceFactoryOptions](../interfaces/botbuilder_choices.choicefactoryoptions.md)*): `Partial`.<`Activity`> + +*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:79](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L79)* -*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:33](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L33)* +Returns a 'message' activity containing a list of choices that has been automatically formatted based on the capabilities of a given channel. The algorithm prefers to format the supplied list of choices as suggested actions but can decide to use a text based list if suggested actions aren't natively supported by the channel, there are too many choices for the channel to display, or the title of any choice is too long. + +If the algorithm decides to use a list it will use an inline list if there are 3 or less choices and all have short titles. Otherwise, a numbered list is used. + +**Usage Example** + + const message = ChoiceFactory.forChannel(context, [ + { value: 'red', action: { type: 'imBack', title: 'The Red Pill', value: 'red pill' } }, + { value: 'blue', action: { type: 'imBack', title: 'The Blue Pill', value: 'blue pill' } }, + ], `Which do you choose?`); + await context.sendActivity(message); + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| channelOrContext | `string`⎮`BotContext` | - | -| choices | (`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[] | - | -| text | `string` | - | -| speak | `string` | - | -| options | [ChoiceFactoryOptions](../interfaces/botbuilder_choices.choicefactoryoptions.md) | - | +| channelOrContext | `string`⎮`TurnContext` | Channel ID or context object for the current turn of conversation. | +| choices | (`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[] | List of choices to render. | +| text | `string` | (Optional) text of the message. | +| speak | `string` | (Optional) SSML to speak for the message. | +| options | [ChoiceFactoryOptions](../interfaces/botbuilder_choices.choicefactoryoptions.md) | (Optional) formatting options to use when rendering as a list. | @@ -60,18 +85,27 @@ ___ -*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L34)* +*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:96](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L96)* + + + +Returns a 'message' activity containing a list of choices that has been formatted as an inline list. +**Usage Example** + + // Generates a message text of `Pick a color: (1\. red, 2\. green, or 3\. blue)` + const message = ChoiceFactory.inline(['red', 'green', 'blue'], `Pick a color:`); + await context.sendActivity(message); **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| choices | (`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[] | - | -| text | `string` | - | -| speak | `string` | - | -| options | [ChoiceFactoryOptions](../interfaces/botbuilder_choices.choicefactoryoptions.md) | - | +| choices | (`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[] | List of choices to render. | +| text | `string` | (Optional) text of the message. | +| speak | `string` | (Optional) SSML to speak for the message. | +| options | [ChoiceFactoryOptions](../interfaces/botbuilder_choices.choicefactoryoptions.md) | (Optional) formatting options to tweak rendering of list. | @@ -93,18 +127,26 @@ ___ -*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:35](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L35)* +*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:112](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L112)* + + + +Returns a 'message' activity containing a list of choices that has been formatted as an numbered or bulleted list. +**Usage Example** + + const message = ChoiceFactory.list(['red', 'green', 'blue'], `Pick a color:`); + await context.sendActivity(message); **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| choices | (`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[] | - | -| text | `string` | - | -| speak | `string` | - | -| options | [ChoiceFactoryOptions](../interfaces/botbuilder_choices.choicefactoryoptions.md) | - | +| choices | (`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[] | List of choices to render. | +| text | `string` | (Optional) text of the message. | +| speak | `string` | (Optional) SSML to speak for the message. | +| options | [ChoiceFactoryOptions](../interfaces/botbuilder_choices.choicefactoryoptions.md) | (Optional) formatting options to tweak rendering of list. | @@ -122,22 +164,29 @@ ___ ### «Static» suggestedAction -► **suggestedAction**(choices: *(`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[]*, text?: *`string`*, speak?: *`string`*, options?: *[ChoiceFactoryOptions](../interfaces/botbuilder_choices.choicefactoryoptions.md)*): `Partial`.<`Activity`> +► **suggestedAction**(choices: *(`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[]*, text?: *`string`*, speak?: *`string`*): `Partial`.<`Activity`> + + +*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:127](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L127)* -*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L36)* +Returns a 'message' activity containing a list of choices that have been added as suggested actions. + +**Usage Example** + + const message = ChoiceFactory.suggestedAction(['red', 'green', 'blue'], `Pick a color:`); + await context.sendActivity(message); **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| choices | (`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[] | - | -| text | `string` | - | -| speak | `string` | - | -| options | [ChoiceFactoryOptions](../interfaces/botbuilder_choices.choicefactoryoptions.md) | - | +| choices | (`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[] | List of choices to add. | +| text | `string` | (Optional) text of the message. | +| speak | `string` | (Optional) SSML to speak for the message. | @@ -159,15 +208,22 @@ ___ -*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L37)* +*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:138](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L138)* + + + +Takes a mixed list of `string` and `Choice` based choices and returns them as a `Choice[]`. + +**Usage Example** + const choices = ChoiceFactory.toChoices(['red', 'green', 'blue']); **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| choices | (`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[]⎮`undefined` | - | +| choices | (`string`⎮[Choice](../interfaces/botbuilder_choices.choice.md))[]⎮`undefined` | List of choices to add. | diff --git a/doc/botbuilder-choices/interfaces/botbuilder_choices.choice.md b/doc/botbuilder-choices/interfaces/botbuilder_choices.choice.md index 150dd2e740..de5a4d92e9 100644 --- a/doc/botbuilder-choices/interfaces/botbuilder_choices.choice.md +++ b/doc/botbuilder-choices/interfaces/botbuilder_choices.choice.md @@ -5,6 +5,27 @@ # Interface: Choice +:package: **botbuilder-choices** + +An instance of a choice that can be used to render a choice to a user or recognize something a user picked. + +The [value](#value) will be rendered to a user unless an [action](#action) is provided in which case the actions `title` will be rendered to the user. + +At recognition time the `value` will always be what gets returned by `findChoices()` and `recognizeChoices()`. By default, the users utterance will be compared against all of the strings provided in the choice. You can disable using the `value` and/or `action.title` during recognition using the `FindChoicesOptions` structure. + +**Usage Example** + + const choice = { + value: 'red', + action: { + type: 'imBack', + title: 'The Red Pill', + value: 'red pill' + }, + synonyms: ['crimson', 'scarlet', 'ruby', 'cherry'] + }; + + ## Properties @@ -12,11 +33,11 @@ **● action**: *`CardAction`* -*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findChoices.d.ts#L15)* +*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:50](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findChoices.d.ts#L50)* -(Optional) action to use when rendering the choice as a suggested action. +(Optional) action to use when rendering the choice as a suggested action. This **MUST** be a complete action containing `type`, `title`, and `value` fields. If not specified an `imBack` action will be generated based on the choices [value](#value) field. @@ -29,11 +50,11 @@ ___ **● synonyms**: *`string`[]* -*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:17](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findChoices.d.ts#L17)* +*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findChoices.d.ts#L55)* -(Optional) list of synonyms to recognize in addition to the value. +(Optional) list of synonyms to recognize in addition to the [value](#value) and [action](#action) fields. @@ -46,11 +67,11 @@ ___ **● value**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:13](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findChoices.d.ts#L13)* +*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:44](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findChoices.d.ts#L44)* -Value to return when selected. +Value to return when recognized by `findChoices()`. Will also be used to render choices to the user if no [action](#action) is provided. diff --git a/doc/botbuilder-choices/interfaces/botbuilder_choices.choicefactoryoptions.md b/doc/botbuilder-choices/interfaces/botbuilder_choices.choicefactoryoptions.md index 026dec664d..e242c9b59b 100644 --- a/doc/botbuilder-choices/interfaces/botbuilder_choices.choicefactoryoptions.md +++ b/doc/botbuilder-choices/interfaces/botbuilder_choices.choicefactoryoptions.md @@ -5,6 +5,11 @@ # Interface: ChoiceFactoryOptions +:package: **botbuilder-choices** + +Additional options used to tweak the formatting of choice lists. + + ## Properties @@ -12,7 +17,7 @@ **● includeNumbers**: *`boolean`* -*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:30](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L30)* +*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L36)* @@ -29,7 +34,7 @@ ___ **● inlineOr**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L20)* +*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L25)* @@ -46,7 +51,7 @@ ___ **● inlineOrMore**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L25)* +*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:30](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L30)* @@ -63,7 +68,7 @@ ___ **● inlineSeparator**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L15)* +*Defined in [libraries/botbuilder-choices/lib/choiceFactory.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/choiceFactory.d.ts#L20)* diff --git a/doc/botbuilder-choices/interfaces/botbuilder_choices.findchoicesoptions.md b/doc/botbuilder-choices/interfaces/botbuilder_choices.findchoicesoptions.md index 8a9d93902c..267bef55bc 100644 --- a/doc/botbuilder-choices/interfaces/botbuilder_choices.findchoicesoptions.md +++ b/doc/botbuilder-choices/interfaces/botbuilder_choices.findchoicesoptions.md @@ -4,6 +4,11 @@ # Interface: FindChoicesOptions + +:package: **botbuilder-choices** + +Options to control the recognition performed by `findChoices()`. + ## Hierarchy @@ -27,7 +32,7 @@ *Inherited from [FindValuesOptions](botbuilder_choices.findvaluesoptions.md).[allowPartialMatches](botbuilder_choices.findvaluesoptions.md#allowpartialmatches)* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L15)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L20)* @@ -46,7 +51,7 @@ ___ *Inherited from [FindValuesOptions](botbuilder_choices.findvaluesoptions.md).[locale](botbuilder_choices.findvaluesoptions.md#locale)* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L19)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L24)* @@ -65,7 +70,7 @@ ___ *Inherited from [FindValuesOptions](botbuilder_choices.findvaluesoptions.md).[maxTokenDistance](botbuilder_choices.findvaluesoptions.md#maxtokendistance)* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:26](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L26)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:31](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L31)* @@ -82,11 +87,11 @@ ___ **● noAction**: *`boolean`* -*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findChoices.d.ts#L27)* +*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:71](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findChoices.d.ts#L71)* -(Optional) If `true`, the title of the choices action will NOT be searched over. The default is `false`. +(Optional) If `true`, the the choices `action.title` field will NOT be searched over. Defaults to `false`. @@ -99,11 +104,11 @@ ___ **● noValue**: *`boolean`* -*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findChoices.d.ts#L23)* +*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:66](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findChoices.d.ts#L66)* -(Optional) If `true`, the choices value will NOT be search over. The default is `false`. +(Optional) If `true`, the choices `value` field will NOT be search over. Defaults to `false`. @@ -118,7 +123,7 @@ ___ *Inherited from [FindValuesOptions](botbuilder_choices.findvaluesoptions.md).[tokenizer](botbuilder_choices.findvaluesoptions.md#tokenizer)* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:30](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L30)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:35](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L35)* diff --git a/doc/botbuilder-choices/interfaces/botbuilder_choices.findvaluesoptions.md b/doc/botbuilder-choices/interfaces/botbuilder_choices.findvaluesoptions.md index 867a2d2582..b309c5b691 100644 --- a/doc/botbuilder-choices/interfaces/botbuilder_choices.findvaluesoptions.md +++ b/doc/botbuilder-choices/interfaces/botbuilder_choices.findvaluesoptions.md @@ -4,6 +4,11 @@ # Interface: FindValuesOptions + +:package: **botbuilder-choices** + +Basic search options used to control how choices are recognized in a users utterance. + ## Hierarchy **FindValuesOptions** @@ -25,7 +30,7 @@ **● allowPartialMatches**: *`boolean`* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L15)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L20)* @@ -42,7 +47,7 @@ ___ **● locale**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L19)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L24)* @@ -59,7 +64,7 @@ ___ **● maxTokenDistance**: *`number`* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:26](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L26)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:31](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L31)* @@ -76,7 +81,7 @@ ___ **● tokenizer**: *[TokenizerFunction](../#tokenizerfunction)* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:30](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L30)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:35](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L35)* diff --git a/doc/botbuilder-choices/interfaces/botbuilder_choices.foundchoice.md b/doc/botbuilder-choices/interfaces/botbuilder_choices.foundchoice.md index d35a8f8d5e..08ce0b7589 100644 --- a/doc/botbuilder-choices/interfaces/botbuilder_choices.foundchoice.md +++ b/doc/botbuilder-choices/interfaces/botbuilder_choices.foundchoice.md @@ -5,6 +5,11 @@ # Interface: FoundChoice +:package: **botbuilder-choices** + +Result returned by `findChoices()`. + + ## Properties @@ -12,7 +17,7 @@ **● index**: *`number`* -*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:33](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findChoices.d.ts#L33)* +*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:82](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findChoices.d.ts#L82)* @@ -29,7 +34,7 @@ ___ **● score**: *`number`* -*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findChoices.d.ts#L38)* +*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:87](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findChoices.d.ts#L87)* @@ -46,7 +51,7 @@ ___ **● synonym**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findChoices.d.ts#L40)* +*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:89](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findChoices.d.ts#L89)* @@ -63,7 +68,7 @@ ___ **● value**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:31](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findChoices.d.ts#L31)* +*Defined in [libraries/botbuilder-choices/lib/findChoices.d.ts:80](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findChoices.d.ts#L80)* diff --git a/doc/botbuilder-choices/interfaces/botbuilder_choices.foundvalue.md b/doc/botbuilder-choices/interfaces/botbuilder_choices.foundvalue.md index 74ca8b9b3f..726a294315 100644 --- a/doc/botbuilder-choices/interfaces/botbuilder_choices.foundvalue.md +++ b/doc/botbuilder-choices/interfaces/botbuilder_choices.foundvalue.md @@ -5,6 +5,11 @@ # Interface: FoundValue +:package: **botbuilder-choices** + +INTERNAL: Raw search result returned by `findValues()`. + + ## Properties @@ -12,7 +17,7 @@ **● index**: *`number`* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L40)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:50](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L50)* @@ -29,7 +34,7 @@ ___ **● score**: *`number`* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:45](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L45)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L55)* @@ -46,7 +51,7 @@ ___ **● value**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L36)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:46](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L46)* diff --git a/doc/botbuilder-choices/interfaces/botbuilder_choices.modelresult.md b/doc/botbuilder-choices/interfaces/botbuilder_choices.modelresult.md index b5894ec455..44ff782b3c 100644 --- a/doc/botbuilder-choices/interfaces/botbuilder_choices.modelresult.md +++ b/doc/botbuilder-choices/interfaces/botbuilder_choices.modelresult.md @@ -5,11 +5,14 @@ # Interface: ModelResult -Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License. +Outer result returned by an entity recognizer like `recognizeChoices()`. This structure is wrapped around the recognized result and contains [start](#start) and [end](#end) position information to identify the span of text in the users utterance that was recognized. The actual result can be accessed through the [resolution](#resolution) property. ## Type parameters #### T : `Object` +The type of entity/resolution being returned. + + ## Properties @@ -17,9 +20,12 @@ Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT **● end**: *`number`* -*Defined in [libraries/botbuilder-choices/lib/modelResult.d.ts:11](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/modelResult.d.ts#L11)* +*Defined in [libraries/botbuilder-choices/lib/modelResult.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/modelResult.d.ts#L21)* + +End character position of the recognized substring. + @@ -31,8 +37,11 @@ ___ **● resolution**: *`T`* -*Defined in [libraries/botbuilder-choices/lib/modelResult.d.ts:13](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/modelResult.d.ts#L13)* +*Defined in [libraries/botbuilder-choices/lib/modelResult.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/modelResult.d.ts#L25)* + + +The recognized entity. @@ -45,10 +54,13 @@ ___ **● start**: *`number`* -*Defined in [libraries/botbuilder-choices/lib/modelResult.d.ts:10](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/modelResult.d.ts#L10)* +*Defined in [libraries/botbuilder-choices/lib/modelResult.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/modelResult.d.ts#L19)* +Start character position of the recognized substring. + + ___ @@ -59,9 +71,12 @@ ___ **● text**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/modelResult.d.ts:9](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/modelResult.d.ts#L9)* +*Defined in [libraries/botbuilder-choices/lib/modelResult.d.ts:17](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/modelResult.d.ts#L17)* + +Substring of the utterance that was recognized. + @@ -73,8 +88,11 @@ ___ **● typeName**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/modelResult.d.ts:12](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/modelResult.d.ts#L12)* +*Defined in [libraries/botbuilder-choices/lib/modelResult.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/modelResult.d.ts#L23)* + + +Type of entity that was recognized. diff --git a/doc/botbuilder-choices/interfaces/botbuilder_choices.sortedvalue.md b/doc/botbuilder-choices/interfaces/botbuilder_choices.sortedvalue.md index 5b5b2be333..2a1eb9ad49 100644 --- a/doc/botbuilder-choices/interfaces/botbuilder_choices.sortedvalue.md +++ b/doc/botbuilder-choices/interfaces/botbuilder_choices.sortedvalue.md @@ -5,7 +5,9 @@ # Interface: SortedValue -A value that can be sorted and still refer to its original position with a source array. +:package: **botbuilder-choices** + +INTERNAL: A value that can be sorted and still refer to its original position within a source array. The `findChoices()` function expands the passed in choices to individual `SortedValue` instances and passes them to `findValues()`. Each individual `Choice` can result in multiple synonyms that should be searched for so this data structure lets us pass each synonym as a value to search while maintaining the index of the choice that value came from. ## Properties @@ -15,7 +17,7 @@ A value that can be sorted and still refer to its original position with a sourc **● index**: *`number`* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L52)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:70](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L70)* @@ -32,7 +34,7 @@ ___ **● value**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:50](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/findValues.d.ts#L50)* +*Defined in [libraries/botbuilder-choices/lib/findValues.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/findValues.d.ts#L68)* diff --git a/doc/botbuilder-choices/interfaces/botbuilder_choices.token.md b/doc/botbuilder-choices/interfaces/botbuilder_choices.token.md index 316324358c..f9a677de37 100644 --- a/doc/botbuilder-choices/interfaces/botbuilder_choices.token.md +++ b/doc/botbuilder-choices/interfaces/botbuilder_choices.token.md @@ -5,7 +5,9 @@ # Interface: Token -Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License. +:package: **botbuilder-choices** + +Individual token returned by a `TokenizerFunction`. ## Properties @@ -15,8 +17,11 @@ Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT **● end**: *`number`* -*Defined in [libraries/botbuilder-choices/lib/tokenizer.d.ts:10](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/tokenizer.d.ts#L10)* +*Defined in [libraries/botbuilder-choices/lib/tokenizer.d.ts:17](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/tokenizer.d.ts#L17)* + + +End character position of the token within the outer string. @@ -29,8 +34,11 @@ ___ **● normalized**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/tokenizer.d.ts:12](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/tokenizer.d.ts#L12)* +*Defined in [libraries/botbuilder-choices/lib/tokenizer.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/tokenizer.d.ts#L21)* + + +Normalized form of the token. This can include things like lower casing or stemming. @@ -43,10 +51,13 @@ ___ **● start**: *`number`* -*Defined in [libraries/botbuilder-choices/lib/tokenizer.d.ts:9](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/tokenizer.d.ts#L9)* +*Defined in [libraries/botbuilder-choices/lib/tokenizer.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/tokenizer.d.ts#L15)* +Start character position of the token within the outer string. + + ___ @@ -57,8 +68,11 @@ ___ **● text**: *`string`* -*Defined in [libraries/botbuilder-choices/lib/tokenizer.d.ts:11](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-choices/lib/tokenizer.d.ts#L11)* +*Defined in [libraries/botbuilder-choices/lib/tokenizer.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/fbf16f5/libraries/botbuilder-choices/lib/tokenizer.d.ts#L19)* + + +Original text of the token. diff --git a/libraries/botbuilder-choices/lib/choiceFactory.d.ts b/libraries/botbuilder-choices/lib/choiceFactory.d.ts index 36e8754aa8..9e5048f972 100644 --- a/libraries/botbuilder-choices/lib/choiceFactory.d.ts +++ b/libraries/botbuilder-choices/lib/choiceFactory.d.ts @@ -7,6 +7,11 @@ */ import { TurnContext, Activity } from 'botbuilder'; import { Choice } from './findChoices'; +/** + * :package: **botbuilder-choices** + * + * Additional options used to tweak the formatting of choice lists. + */ export interface ChoiceFactoryOptions { /** * (Optional) character used to separate individual choices when there are more than 2 choices. @@ -25,14 +30,110 @@ export interface ChoiceFactoryOptions { inlineOrMore?: string; /** * (Optional) if `true`, inline and list style choices will be prefixed with the index of the - * choice as in "1. choice". If `false`, the list style will use a bulleted list instead. The default value is `true`. + * choice as in "1. choice". If `false`, the list style will use a bulleted list instead. The + * default value is `true`. */ includeNumbers?: boolean; } +/** + * :package: **botbuilder-choices** + * + * A set of utility functions to assist with the formatting a 'message' activity containing a list + * of choices. + * + * **Usage Example** + * + * ```JavaScript + * const { ChoiceFactory } = require('botbuilder-choices'); + * + * const message = ChoiceFactory.forChannel(context, ['red', 'green', 'blue'], `Pick a color.`); + * await context.sendActivity(message); + * ``` + */ export declare class ChoiceFactory { + /** + * Returns a 'message' activity containing a list of choices that has been automatically + * formatted based on the capabilities of a given channel. The algorithm prefers to format + * the supplied list of choices as suggested actions but can decide to use a text based list + * if suggested actions aren't natively supported by the channel, there are too many choices + * for the channel to display, or the title of any choice is too long. + * + * If the algorithm decides to use a list it will use an inline list if there are 3 or less + * choices and all have short titles. Otherwise, a numbered list is used. + * + * **Usage Example** + * + * ```JavaScript + * const message = ChoiceFactory.forChannel(context, [ + * { value: 'red', action: { type: 'imBack', title: 'The Red Pill', value: 'red pill' } }, + * { value: 'blue', action: { type: 'imBack', title: 'The Blue Pill', value: 'blue pill' } }, + * ], `Which do you choose?`); + * await context.sendActivity(message); + * ``` + * @param channelOrContext Channel ID or context object for the current turn of conversation. + * @param choices List of choices to render. + * @param text (Optional) text of the message. + * @param speak (Optional) SSML to speak for the message. + * @param options (Optional) formatting options to use when rendering as a list. + */ static forChannel(channelOrContext: string | TurnContext, choices: (string | Choice)[], text?: string, speak?: string, options?: ChoiceFactoryOptions): Partial; + /** + * Returns a 'message' activity containing a list of choices that has been formatted as an + * inline list. + * + * **Usage Example** + * + * ```JavaScript + * // Generates a message text of `Pick a color: (1. red, 2. green, or 3. blue)` + * const message = ChoiceFactory.inline(['red', 'green', 'blue'], `Pick a color:`); + * await context.sendActivity(message); + * ``` + * @param choices List of choices to render. + * @param text (Optional) text of the message. + * @param speak (Optional) SSML to speak for the message. + * @param options (Optional) formatting options to tweak rendering of list. + */ static inline(choices: (string | Choice)[], text?: string, speak?: string, options?: ChoiceFactoryOptions): Partial; + /** + * Returns a 'message' activity containing a list of choices that has been formatted as an + * numbered or bulleted list. + * + * **Usage Example** + * + * ```JavaScript + * const message = ChoiceFactory.list(['red', 'green', 'blue'], `Pick a color:`); + * await context.sendActivity(message); + * ``` + * @param choices List of choices to render. + * @param text (Optional) text of the message. + * @param speak (Optional) SSML to speak for the message. + * @param options (Optional) formatting options to tweak rendering of list. + */ static list(choices: (string | Choice)[], text?: string, speak?: string, options?: ChoiceFactoryOptions): Partial; - static suggestedAction(choices: (string | Choice)[], text?: string, speak?: string, options?: ChoiceFactoryOptions): Partial; + /** + * Returns a 'message' activity containing a list of choices that have been added as suggested + * actions. + * + * **Usage Example** + * + * ```JavaScript + * const message = ChoiceFactory.suggestedAction(['red', 'green', 'blue'], `Pick a color:`); + * await context.sendActivity(message); + * ``` + * @param choices List of choices to add. + * @param text (Optional) text of the message. + * @param speak (Optional) SSML to speak for the message. + */ + static suggestedAction(choices: (string | Choice)[], text?: string, speak?: string): Partial; + /** + * Takes a mixed list of `string` and `Choice` based choices and returns them as a `Choice[]`. + * + * **Usage Example** + * + * ```JavaScript + * const choices = ChoiceFactory.toChoices(['red', 'green', 'blue']); + * ``` + * @param choices List of choices to add. + */ static toChoices(choices: (string | Choice)[] | undefined): Choice[]; } diff --git a/libraries/botbuilder-choices/lib/choiceFactory.js b/libraries/botbuilder-choices/lib/choiceFactory.js index 7071a89cf9..2bbc89d267 100644 --- a/libraries/botbuilder-choices/lib/choiceFactory.js +++ b/libraries/botbuilder-choices/lib/choiceFactory.js @@ -9,7 +9,47 @@ Object.defineProperty(exports, "__esModule", { value: true }); const botbuilder_1 = require("botbuilder"); const channel = require("./channel"); +/** + * :package: **botbuilder-choices** + * + * A set of utility functions to assist with the formatting a 'message' activity containing a list + * of choices. + * + * **Usage Example** + * + * ```JavaScript + * const { ChoiceFactory } = require('botbuilder-choices'); + * + * const message = ChoiceFactory.forChannel(context, ['red', 'green', 'blue'], `Pick a color.`); + * await context.sendActivity(message); + * ``` + */ class ChoiceFactory { + /** + * Returns a 'message' activity containing a list of choices that has been automatically + * formatted based on the capabilities of a given channel. The algorithm prefers to format + * the supplied list of choices as suggested actions but can decide to use a text based list + * if suggested actions aren't natively supported by the channel, there are too many choices + * for the channel to display, or the title of any choice is too long. + * + * If the algorithm decides to use a list it will use an inline list if there are 3 or less + * choices and all have short titles. Otherwise, a numbered list is used. + * + * **Usage Example** + * + * ```JavaScript + * const message = ChoiceFactory.forChannel(context, [ + * { value: 'red', action: { type: 'imBack', title: 'The Red Pill', value: 'red pill' } }, + * { value: 'blue', action: { type: 'imBack', title: 'The Blue Pill', value: 'blue pill' } }, + * ], `Which do you choose?`); + * await context.sendActivity(message); + * ``` + * @param channelOrContext Channel ID or context object for the current turn of conversation. + * @param choices List of choices to render. + * @param text (Optional) text of the message. + * @param speak (Optional) SSML to speak for the message. + * @param options (Optional) formatting options to use when rendering as a list. + */ static forChannel(channelOrContext, choices, text, speak, options) { const channelId = typeof channelOrContext === 'string' ? channelOrContext : channel.getChannelId(channelOrContext); // Normalize choices @@ -31,7 +71,7 @@ class ChoiceFactory { if (!longTitles && (supportsSuggestedActions || (!hasMessageFeed && supportsCardActions))) { // We always prefer showing choices using suggested actions. If the titles are too long, however, // we'll have to show them as a text list. - return ChoiceFactory.suggestedAction(list, text, speak, options); + return ChoiceFactory.suggestedAction(list, text, speak); } else if (!longTitles && choices.length <= 3) { // If the titles are short and there are 3 or less choices we'll use an inline list. @@ -42,6 +82,22 @@ class ChoiceFactory { return ChoiceFactory.list(list, text, speak, options); } } + /** + * Returns a 'message' activity containing a list of choices that has been formatted as an + * inline list. + * + * **Usage Example** + * + * ```JavaScript + * // Generates a message text of `Pick a color: (1. red, 2. green, or 3. blue)` + * const message = ChoiceFactory.inline(['red', 'green', 'blue'], `Pick a color:`); + * await context.sendActivity(message); + * ``` + * @param choices List of choices to render. + * @param text (Optional) text of the message. + * @param speak (Optional) SSML to speak for the message. + * @param options (Optional) formatting options to tweak rendering of list. + */ static inline(choices, text, speak, options) { const opt = Object.assign({ inlineSeparator: ', ', @@ -67,6 +123,21 @@ class ChoiceFactory { // Return activity with choices as an inline list. return botbuilder_1.MessageFactory.text(txt, speak, botbuilder_1.InputHints.ExpectingInput); } + /** + * Returns a 'message' activity containing a list of choices that has been formatted as an + * numbered or bulleted list. + * + * **Usage Example** + * + * ```JavaScript + * const message = ChoiceFactory.list(['red', 'green', 'blue'], `Pick a color:`); + * await context.sendActivity(message); + * ``` + * @param choices List of choices to render. + * @param text (Optional) text of the message. + * @param speak (Optional) SSML to speak for the message. + * @param options (Optional) formatting options to tweak rendering of list. + */ static list(choices, text, speak, options) { const opt = Object.assign({ includeNumbers: true @@ -83,7 +154,21 @@ class ChoiceFactory { // Return activity with choices as a numbered list. return botbuilder_1.MessageFactory.text(txt, speak, botbuilder_1.InputHints.ExpectingInput); } - static suggestedAction(choices, text, speak, options) { + /** + * Returns a 'message' activity containing a list of choices that have been added as suggested + * actions. + * + * **Usage Example** + * + * ```JavaScript + * const message = ChoiceFactory.suggestedAction(['red', 'green', 'blue'], `Pick a color:`); + * await context.sendActivity(message); + * ``` + * @param choices List of choices to add. + * @param text (Optional) text of the message. + * @param speak (Optional) SSML to speak for the message. + */ + static suggestedAction(choices, text, speak) { // Map choices to actions const actions = ChoiceFactory.toChoices(choices).map((choice) => { if (choice.action) { @@ -96,6 +181,16 @@ class ChoiceFactory { // Return activity with choices as suggested actions return botbuilder_1.MessageFactory.suggestedActions(actions, text, speak, botbuilder_1.InputHints.ExpectingInput); } + /** + * Takes a mixed list of `string` and `Choice` based choices and returns them as a `Choice[]`. + * + * **Usage Example** + * + * ```JavaScript + * const choices = ChoiceFactory.toChoices(['red', 'green', 'blue']); + * ``` + * @param choices List of choices to add. + */ static toChoices(choices) { return (choices || []).map((choice) => typeof choice === 'string' ? { value: choice } : choice).filter((choice) => choice); } diff --git a/libraries/botbuilder-choices/lib/choiceFactory.js.map b/libraries/botbuilder-choices/lib/choiceFactory.js.map index af4bfcd5b1..8fe41e5d82 100644 --- a/libraries/botbuilder-choices/lib/choiceFactory.js.map +++ b/libraries/botbuilder-choices/lib/choiceFactory.js.map @@ -1 +1 @@ -{"version":3,"file":"choiceFactory.js","sourceRoot":"","sources":["../src/choiceFactory.ts"],"names":[],"mappings":"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"} \ No newline at end of file +{"version":3,"file":"choiceFactory.js","sourceRoot":"","sources":["../src/choiceFactory.ts"],"names":[],"mappings":"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"} \ No newline at end of file diff --git a/libraries/botbuilder-choices/lib/findChoices.d.ts b/libraries/botbuilder-choices/lib/findChoices.d.ts index 53302e602f..be40a3bb98 100644 --- a/libraries/botbuilder-choices/lib/findChoices.d.ts +++ b/libraries/botbuilder-choices/lib/findChoices.d.ts @@ -8,24 +8,73 @@ import { CardAction } from 'botbuilder'; import { ModelResult } from './modelResult'; import { FindValuesOptions } from './findValues'; +/** + * :package: **botbuilder-choices** + * + * An instance of a choice that can be used to render a choice to a user or recognize something a + * user picked. + * + * The [value](#value) will be rendered to a user unless an [action](#action) is provided in which + * case the actions `title` will be rendered to the user. + * + * At recognition time the `value` will always be what gets returned by `findChoices()` and + * `recognizeChoices()`. By default, the users utterance will be compared against all of the + * strings provided in the choice. You can disable using the `value` and/or `action.title` during + * recognition using the `FindChoicesOptions` structure. + * + * **Usage Example** + * + * ```JavaScript + * const choice = { + * value: 'red', + * action: { + * type: 'imBack', + * title: 'The Red Pill', + * value: 'red pill' + * }, + * synonyms: ['crimson', 'scarlet', 'ruby', 'cherry'] + * }; + * ``` + */ export interface Choice { - /** Value to return when selected. */ + /** + * Value to return when recognized by `findChoices()`. Will also be used to render choices + * to the user if no [action](#action) is provided. + */ value: string; - /** (Optional) action to use when rendering the choice as a suggested action. */ + /** + * (Optional) action to use when rendering the choice as a suggested action. This **MUST** + * be a complete action containing `type`, `title`, and `value` fields. If not specified an + * `imBack` action will be generated based on the choices [value](#value) field. + */ action?: CardAction; - /** (Optional) list of synonyms to recognize in addition to the value. */ + /** + * (Optional) list of synonyms to recognize in addition to the [value](#value) and + * [action](#action) fields. + */ synonyms?: string[]; } +/** + * :package: **botbuilder-choices** + * + * Options to control the recognition performed by `findChoices()`. + */ export interface FindChoicesOptions extends FindValuesOptions { /** - * (Optional) If `true`, the choices value will NOT be search over. The default is `false`. + * (Optional) If `true`, the choices `value` field will NOT be search over. Defaults to `false`. */ noValue?: boolean; /** - * (Optional) If `true`, the title of the choices action will NOT be searched over. The default is `false`. + * (Optional) If `true`, the the choices `action.title` field will NOT be searched over. + * Defaults to `false`. */ noAction?: boolean; } +/** + * :package: **botbuilder-choices** + * + * Result returned by `findChoices()`. + */ export interface FoundChoice { /** The value of the choice that was matched. */ value: string; @@ -39,4 +88,35 @@ export interface FoundChoice { /** (Optional) The synonym that was matched. */ synonym?: string; } +/** + * :package: **botbuilder-choices** + * + * Mid-level search function for recognizing a choice in an utterance. This function is layered + * above `findValues()` and simply determines all of the synonyms that should be searched for + * before calling `findValues()` to perform the actual search. The `recognizeChoices()` function is + * layered above this function and adds the ability to select a choice by index or ordinal position + * in the list. Calling this particular function is useful when you don't want the index and ordinal + * position recognition done by `recognizeChoices()`. + * + * **Usage Example** + * + * ```JavaScript + * const { findChoices } = require('botbuilder-choices'); + * + * const choices = ['red', 'green', 'blue']; + * const utterance = context.activity.text; + * const results = findChoices(utterance, choices); + * if (results.length == 1) { + * await context.sendActivity(`I like ${results[0].resolution.value} too!`); + * } else if (results.length > 1) { + * const ambiguous = results.map((r) => r.resolution.value); + * await context.sendActivity(ChoiceFactory.forChannel(context, ambiguous, `Which one?`)); + * } else { + * await context.sendActivity(ChoiceFactory.forChannel(context, choices, `I didn't get that... Which color?`)); + * } + * ``` + * @param utterance The text or user utterance to search over. For an incoming 'message' activity you can simply use `context.activity.text`. + * @param choices List of choices to search over. + * @param options (Optional) options used to tweak the search that's performed. + */ export declare function findChoices(utterance: string, choices: (string | Choice)[], options?: FindChoicesOptions): ModelResult[]; diff --git a/libraries/botbuilder-choices/lib/findChoices.js b/libraries/botbuilder-choices/lib/findChoices.js index a940d08d5e..f91ca8b909 100644 --- a/libraries/botbuilder-choices/lib/findChoices.js +++ b/libraries/botbuilder-choices/lib/findChoices.js @@ -8,6 +8,37 @@ */ Object.defineProperty(exports, "__esModule", { value: true }); const findValues_1 = require("./findValues"); +/** + * :package: **botbuilder-choices** + * + * Mid-level search function for recognizing a choice in an utterance. This function is layered + * above `findValues()` and simply determines all of the synonyms that should be searched for + * before calling `findValues()` to perform the actual search. The `recognizeChoices()` function is + * layered above this function and adds the ability to select a choice by index or ordinal position + * in the list. Calling this particular function is useful when you don't want the index and ordinal + * position recognition done by `recognizeChoices()`. + * + * **Usage Example** + * + * ```JavaScript + * const { findChoices } = require('botbuilder-choices'); + * + * const choices = ['red', 'green', 'blue']; + * const utterance = context.activity.text; + * const results = findChoices(utterance, choices); + * if (results.length == 1) { + * await context.sendActivity(`I like ${results[0].resolution.value} too!`); + * } else if (results.length > 1) { + * const ambiguous = results.map((r) => r.resolution.value); + * await context.sendActivity(ChoiceFactory.forChannel(context, ambiguous, `Which one?`)); + * } else { + * await context.sendActivity(ChoiceFactory.forChannel(context, choices, `I didn't get that... Which color?`)); + * } + * ``` + * @param utterance The text or user utterance to search over. For an incoming 'message' activity you can simply use `context.activity.text`. + * @param choices List of choices to search over. + * @param options (Optional) options used to tweak the search that's performed. + */ function findChoices(utterance, choices, options) { const opt = options || {}; // Normalize choices diff --git a/libraries/botbuilder-choices/lib/findChoices.js.map b/libraries/botbuilder-choices/lib/findChoices.js.map index a96d55541b..67d1efebba 100644 --- a/libraries/botbuilder-choices/lib/findChoices.js.map +++ b/libraries/botbuilder-choices/lib/findChoices.js.map @@ -1 +1 @@ -{"version":3,"file":"findChoices.js","sourceRoot":"","sources":["../src/findChoices.ts"],"names":[],"mappings":";AAAA;;GAEG;AACH;;;GAGG;;AAIH,6CAA0E;AA0C1E,qBAA4B,SAAiB,EAAE,OAA0B,EAAE,OAA4B;IACnG,MAAM,GAAG,GAAG,OAAO,IAAI,EAAE,CAAC;IAE1B,oBAAoB;IACpB,MAAM,IAAI,GAAa,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,KAAK,OAAO,MAAM,KAAK,QAAQ,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC;IAEvH,iDAAiD;IACjD,8FAA8F;IAC9F,yDAAyD;IACzD,MAAM,QAAQ,GAAkB,EAAE,CAAC;IACnC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK;QACvB,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;QAAC,CAAC;QAC1E,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;QAAC,CAAC;QAC1H,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAClG,CAAC,CAAC,CAAC;IAEH,2DAA2D;IAC3D,MAAM,CAAC,uBAAU,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACxC,MAAM,CAAC;YACH,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,GAAG,EAAE,CAAC,CAAC,GAAG;YACV,QAAQ,EAAE,QAAQ;YAClB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,UAAU,EAAE;gBACR,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK;gBACzB,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK;gBACzB,OAAO,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK;aAC9B;SACwB,CAAC;IAClC,CAAC,CAAC,CAAC;AACP,CAAC;AAhCD,kCAgCC"} \ No newline at end of file +{"version":3,"file":"findChoices.js","sourceRoot":"","sources":["../src/findChoices.ts"],"names":[],"mappings":";AAAA;;GAEG;AACH;;;GAGG;;AAIH,6CAA0E;AA2F1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAA4B,SAAiB,EAAE,OAA0B,EAAE,OAA4B;IACnG,MAAM,GAAG,GAAG,OAAO,IAAI,EAAE,CAAC;IAE1B,oBAAoB;IACpB,MAAM,IAAI,GAAa,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAEvH,iDAAiD;IACjD,8FAA8F;IAC9F,yDAAyD;IACzD,MAAM,QAAQ,GAAkB,EAAE,CAAC;IACnC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;QAC3B,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;QAAC,CAAC;QAC1E,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;QAAC,CAAC;QAC1H,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAClG,CAAC,CAAC,CAAC;IAEH,2DAA2D;IAC3D,MAAM,CAAC,uBAAU,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACtD,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACxC,MAAM,CAAC;YACH,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,GAAG,EAAE,CAAC,CAAC,GAAG;YACV,QAAQ,EAAE,QAAQ;YAClB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,UAAU,EAAE;gBACR,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK;gBACzB,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK;gBACzB,OAAO,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK;aAC9B;SACwB,CAAC;IAClC,CAAC,CAAC,CAAC;AACP,CAAC;AAhCD,kCAgCC"} \ No newline at end of file diff --git a/libraries/botbuilder-choices/lib/findValues.d.ts b/libraries/botbuilder-choices/lib/findValues.d.ts index 702ba9eda3..abff85ef71 100644 --- a/libraries/botbuilder-choices/lib/findValues.d.ts +++ b/libraries/botbuilder-choices/lib/findValues.d.ts @@ -7,6 +7,11 @@ */ import { TokenizerFunction } from './tokenizer'; import { ModelResult } from './modelResult'; +/** + * :package: **botbuilder-choices** + * + * Basic search options used to control how choices are recognized in a users utterance. + */ export interface FindValuesOptions { /** * (Optional) if true, then only some of the tokens in a value need to exist to be considered @@ -29,6 +34,11 @@ export interface FindValuesOptions { */ tokenizer?: TokenizerFunction; } +/** + * :package: **botbuilder-choices** + * + * INTERNAL: Raw search result returned by `findValues()`. + */ export interface FoundValue { /** * The value that was matched. @@ -44,7 +54,15 @@ export interface FoundValue { */ score: number; } -/** A value that can be sorted and still refer to its original position with a source array. */ +/** + * :package: **botbuilder-choices** + * + * INTERNAL: A value that can be sorted and still refer to its original position within a source + * array. The `findChoices()` function expands the passed in choices to individual `SortedValue` + * instances and passes them to `findValues()`. Each individual `Choice` can result in multiple + * synonyms that should be searched for so this data structure lets us pass each synonym as a value + * to search while maintaining the index of the choice that value came from. + */ export interface SortedValue { /** The value that will be sorted. */ value: string; @@ -52,6 +70,14 @@ export interface SortedValue { index: number; } /** - * Looks for a set of values within an utterance. + * :package: **botbuilder-choices** + * + * INTERNAL: Low-level function that searches for a set of values within an utterance. Higher level + * functions like `findChoices()` and `recognizeChoices()` are layered above this function. In most + * cases its easier to just call one of the higher level functions instead but this function contains + * the fuzzy search algorithm that drives choice recognition. + * @param utterance The text or user utterance to search over. + * @param values List of values to search over. + * @param options (Optional) options used to tweak the search that's performed. */ export declare function findValues(utterance: string, values: SortedValue[], options?: FindValuesOptions): ModelResult[]; diff --git a/libraries/botbuilder-choices/lib/findValues.js b/libraries/botbuilder-choices/lib/findValues.js index d7f6d3f799..243a425202 100644 --- a/libraries/botbuilder-choices/lib/findValues.js +++ b/libraries/botbuilder-choices/lib/findValues.js @@ -9,7 +9,15 @@ Object.defineProperty(exports, "__esModule", { value: true }); const tokenizer_1 = require("./tokenizer"); /** - * Looks for a set of values within an utterance. + * :package: **botbuilder-choices** + * + * INTERNAL: Low-level function that searches for a set of values within an utterance. Higher level + * functions like `findChoices()` and `recognizeChoices()` are layered above this function. In most + * cases its easier to just call one of the higher level functions instead but this function contains + * the fuzzy search algorithm that drives choice recognition. + * @param utterance The text or user utterance to search over. + * @param values List of values to search over. + * @param options (Optional) options used to tweak the search that's performed. */ function findValues(utterance, values, options) { function indexOfToken(token, startPos) { diff --git a/libraries/botbuilder-choices/lib/findValues.js.map b/libraries/botbuilder-choices/lib/findValues.js.map index d4a9b5ca29..dbb85c4e56 100644 --- a/libraries/botbuilder-choices/lib/findValues.js.map +++ b/libraries/botbuilder-choices/lib/findValues.js.map @@ -1 +1 @@ -{"version":3,"file":"findValues.js","sourceRoot":"","sources":["../src/findValues.ts"],"names":[],"mappings":"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"} \ No newline at end of file +{"version":3,"file":"findValues.js","sourceRoot":"","sources":["../src/findValues.ts"],"names":[],"mappings":";AAAA;;GAEG;AACH;;;GAGG;;AAEH,2CAAyE;AA0EzE;;;;;;;;;;GAUG;AACH,oBAA2B,SAAiB,EAAE,MAAqB,EAAE,OAA2B;IAC5F,sBAAsB,KAAY,EAAE,QAAgB;QAChD,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5C,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;gBAC5C,MAAM,CAAC,CAAC,CAAC;YACb,CAAC;QACL,CAAC;QACD,MAAM,CAAC,CAAC,CAAC,CAAC;IACd,CAAC;IAED,oBAAoB,KAAa,EAAE,KAAa,EAAE,OAAgB,EAAE,QAAgB;QAChF,0DAA0D;QAC1D,oEAAoE;QACpE,0EAA0E;QAC1E,2EAA2E;QAC3E,yEAAyE;QACzE,2CAA2C;QAC3C,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,IAAI,cAAc,GAAG,CAAC,CAAC;QACvB,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;QACf,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC;QACb,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;YACtB,mDAAmD;YACnD,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YAC1C,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;gBACX,+FAA+F;gBAC/F,MAAM,QAAQ,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;gBAClD,EAAE,CAAC,CAAC,QAAQ,IAAI,WAAW,CAAC,CAAC,CAAC;oBAC1B,uFAAuF;oBACvF,qBAAqB;oBACrB,OAAO,EAAE,CAAC;oBACV,cAAc,IAAI,QAAQ,CAAC;oBAC3B,QAAQ,GAAG,GAAG,GAAG,CAAC,CAAC;oBAEnB,wFAAwF;oBACxF,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;wBAAC,KAAK,GAAG,GAAG,CAAA;oBAAC,CAAC;oBAC9B,GAAG,GAAG,GAAG,CAAC;gBACd,CAAC;YACL,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,oCAAoC;QACpC,0FAA0F;QAC1F,IAAI,MAAyC,CAAC;QAC9C,EAAE,CAAC,CAAC,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;YACxE,8DAA8D;YAC9D,iEAAiE;YACjE,yBAAyB;YACzB,MAAM,YAAY,GAAG,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;YAE9C,sEAAsE;YACtE,wEAAwE;YACxE,uEAAuE;YACvE,iCAAiC;YACjC,MAAM,QAAQ,GAAG,CAAC,OAAO,GAAG,CAAC,OAAO,GAAG,cAAc,CAAC,CAAC,CAAA;YAEvD,yEAAyE;YACzE,MAAM,KAAK,GAAG,YAAY,GAAG,QAAQ,CAAC;YAEtC,gBAAgB;YAChB,MAAM,GAAG;gBACL,KAAK,EAAE,KAAK;gBACZ,GAAG,EAAE,GAAG;gBACR,QAAQ,EAAE,OAAO;gBACjB,UAAU,EAAE;oBACR,KAAK,EAAE,KAAK;oBACZ,KAAK,EAAE,KAAK;oBACZ,KAAK,EAAE,KAAK;iBACf;aACuB,CAAC;QACjC,CAAC;QACD,MAAM,CAAC,MAAM,CAAC;IAClB,CAAC;IAED,8FAA8F;IAC9F,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAEpE,8CAA8C;IAC9C,IAAI,OAAO,GAA8B,EAAE,CAAC;IAC5C,MAAM,GAAG,GAAG,OAAO,IAAI,EAAE,CAAC;IAC1B,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,SAAS,IAAI,4BAAgB,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,WAAW,GAAG,GAAG,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IAClF,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAC1B,+BAA+B;QAC/B,yEAAyE;QACzE,yEAAyE;QACzE,yEAAyE;QACzE,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1D,OAAO,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;YACtE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;gBACR,QAAQ,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC;gBACzB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACxB,CAAC;YAAC,IAAI,CAAC,CAAC;gBACJ,KAAK,CAAC;YACV,CAAC;QACL,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,mCAAmC;IACnC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,GAAG,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAEzE,oEAAoE;IACpE,gFAAgF;IAChF,8EAA8E;IAC9E,oBAAoB;IACpB,MAAM,OAAO,GAA8B,EAAE,CAAC;IAC9C,MAAM,YAAY,GAAiC,EAAE,CAAC;IACtD,MAAM,UAAU,GAAiC,EAAE,CAAC;IACpD,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QACtB,gBAAgB;QAChB,IAAI,GAAG,GAAG,CAAC,YAAY,CAAC,cAAc,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC/D,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5C,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAChB,GAAG,GAAG,KAAK,CAAC;gBACZ,KAAK,CAAC;YACV,CAAC;QACL,CAAC;QAED,iBAAiB;QACjB,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACN,qBAAqB;YACrB,YAAY,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;YAC5C,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;gBAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;YAAC,CAAC;YAEvE,gDAAgD;YAChD,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC;YACxC,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;YAClC,KAAK,CAAC,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;YAC7D,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,yDAAyD;IACzD,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AACpD,CAAC;AAzID,gCAyIC"} \ No newline at end of file diff --git a/libraries/botbuilder-choices/lib/modelResult.d.ts b/libraries/botbuilder-choices/lib/modelResult.d.ts index 1fed7d0598..549c95b15b 100644 --- a/libraries/botbuilder-choices/lib/modelResult.d.ts +++ b/libraries/botbuilder-choices/lib/modelResult.d.ts @@ -5,10 +5,22 @@ * Copyright (c) Microsoft Corporation. All rights reserved. * Licensed under the MIT License. */ +/** + * Outer result returned by an entity recognizer like `recognizeChoices()`. This structure is + * wrapped around the recognized result and contains [start](#start) and [end](#end) position + * information to identify the span of text in the users utterance that was recognized. The actual + * result can be accessed through the [resolution](#resolution) property. + * @param T The type of entity/resolution being returned. + */ export interface ModelResult { + /** Substring of the utterance that was recognized. */ text: string; + /** Start character position of the recognized substring. */ start: number; + /** End character position of the recognized substring. */ end: number; + /** Type of entity that was recognized. */ typeName: string; + /** The recognized entity. */ resolution: T; } diff --git a/libraries/botbuilder-choices/lib/recognizeChoices.d.ts b/libraries/botbuilder-choices/lib/recognizeChoices.d.ts index 7552fcd7ea..589e84bc28 100644 --- a/libraries/botbuilder-choices/lib/recognizeChoices.d.ts +++ b/libraries/botbuilder-choices/lib/recognizeChoices.d.ts @@ -7,4 +7,37 @@ */ import { Choice, FoundChoice, FindChoicesOptions } from './findChoices'; import { ModelResult } from './modelResult'; +/** + * :package: **botbuilder-choices** + * + * High level function for recognizing a choice in a users utterance. This is layered above the + * `findChoices()` function and adds logic to let the user specify their choice by index (they can + * say "one" to pick `choice[0]`) or ordinal position (they can say "the second one" to pick + * `choice[1]`.) The users utterance is recognized in the following order: + * + * - By name using `findChoices()`. + * - By 1's based ordinal position. + * - By 1's based index position. + * + * **Usage Example** + * + * ```JavaScript + * const { recognizeChoices } = require('botbuilder-choices'); + * + * const choices = ['red', 'green', 'blue']; + * const utterance = context.activity.text; + * const results = recognizeChoices(utterance, choices); + * if (results.length == 1) { + * await context.sendActivity(`I like ${results[0].resolution.value} too!`); + * } else if (results.length > 1) { + * const ambiguous = results.map((r) => r.resolution.value); + * await context.sendActivity(ChoiceFactory.forChannel(context, ambiguous, `Which one?`)); + * } else { + * await context.sendActivity(ChoiceFactory.forChannel(context, choices, `I didn't get that... Which color?`)); + * } + * ``` + * @param utterance The text or user utterance to search over. For an incoming 'message' activity you can simply use `context.activity.text`. + * @param choices List of choices to search over. + * @param options (Optional) options used to tweak the search that's performed. + */ export declare function recognizeChoices(utterance: string, choices: (string | Choice)[], options?: FindChoicesOptions): ModelResult[]; diff --git a/libraries/botbuilder-choices/lib/recognizeChoices.js b/libraries/botbuilder-choices/lib/recognizeChoices.js index a908ed0e07..ebee1610d3 100644 --- a/libraries/botbuilder-choices/lib/recognizeChoices.js +++ b/libraries/botbuilder-choices/lib/recognizeChoices.js @@ -9,6 +9,39 @@ Object.defineProperty(exports, "__esModule", { value: true }); const findChoices_1 = require("./findChoices"); const Recognizers = require("@microsoft/recognizers-text-number"); +/** + * :package: **botbuilder-choices** + * + * High level function for recognizing a choice in a users utterance. This is layered above the + * `findChoices()` function and adds logic to let the user specify their choice by index (they can + * say "one" to pick `choice[0]`) or ordinal position (they can say "the second one" to pick + * `choice[1]`.) The users utterance is recognized in the following order: + * + * - By name using `findChoices()`. + * - By 1's based ordinal position. + * - By 1's based index position. + * + * **Usage Example** + * + * ```JavaScript + * const { recognizeChoices } = require('botbuilder-choices'); + * + * const choices = ['red', 'green', 'blue']; + * const utterance = context.activity.text; + * const results = recognizeChoices(utterance, choices); + * if (results.length == 1) { + * await context.sendActivity(`I like ${results[0].resolution.value} too!`); + * } else if (results.length > 1) { + * const ambiguous = results.map((r) => r.resolution.value); + * await context.sendActivity(ChoiceFactory.forChannel(context, ambiguous, `Which one?`)); + * } else { + * await context.sendActivity(ChoiceFactory.forChannel(context, choices, `I didn't get that... Which color?`)); + * } + * ``` + * @param utterance The text or user utterance to search over. For an incoming 'message' activity you can simply use `context.activity.text`. + * @param choices List of choices to search over. + * @param options (Optional) options used to tweak the search that's performed. + */ function recognizeChoices(utterance, choices, options) { function matchChoiceByIndex(match) { try { diff --git a/libraries/botbuilder-choices/lib/recognizeChoices.js.map b/libraries/botbuilder-choices/lib/recognizeChoices.js.map index 730a32c9ea..30ec86fd2b 100644 --- a/libraries/botbuilder-choices/lib/recognizeChoices.js.map +++ b/libraries/botbuilder-choices/lib/recognizeChoices.js.map @@ -1 +1 @@ -{"version":3,"file":"recognizeChoices.js","sourceRoot":"","sources":["../src/recognizeChoices.ts"],"names":[],"mappings":";AAAA;;GAEG;AACH;;;GAGG;;AAEH,+CAAqF;AAErF,kEAAkE;AAElE,0BAAiC,SAAiB,EAAE,OAA0B,EAAE,OAA4B;IACxG,4BAA4B,KAAuB;QAC/C,IAAI,CAAC;YACD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACnD,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;gBACpC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC3B,OAAO,CAAC,IAAI,CAAC;oBACT,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,GAAG,EAAE,KAAK,CAAC,GAAG;oBACd,QAAQ,EAAE,QAAQ;oBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,UAAU,EAAE;wBACR,KAAK,EAAE,MAAM,CAAC,KAAK;wBACnB,KAAK,EAAE,KAAK;wBACZ,KAAK,EAAE,GAAG;qBACb;iBACJ,CAAC,CAAC;YACP,CAAC;QACL,CAAC;QAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;IAED,oBAAoB;IACpB,MAAM,IAAI,GAAa,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,KAAK,OAAO,MAAM,KAAK,QAAQ,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;IAElJ,2CAA2C;IAC3C,kGAAkG;IAClG,oGAAoG;IACpG,0CAA0C;IAC1C,MAAM,MAAM,GAAG,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC;IACpE,IAAI,OAAO,GAAG,yBAAW,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACpD,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC;QACvB,8BAA8B;QAC9B,MAAM,QAAQ,GAAG,WAAW,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACjE,EAAE,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;YACtB,QAAQ,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QACzC,CAAC;QAAC,IAAI,CAAC,CAAC;YACJ,iCAAiC;YACjC,WAAW,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QAC/E,CAAC;QAED,iEAAiE;QACjE,oFAAoF;QACpF,qCAAqC;QACrC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAC,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,CAAC,OAAO,CAAC;AACnB,CAAC;AA9CD,4CA8CC"} \ No newline at end of file +{"version":3,"file":"recognizeChoices.js","sourceRoot":"","sources":["../src/recognizeChoices.ts"],"names":[],"mappings":";AAAA;;GAEG;AACH;;;GAGG;;AAEH,+CAAqF;AAErF,kEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,0BAAiC,SAAiB,EAAE,OAA0B,EAAE,OAA4B;IACxG,4BAA4B,KAAuB;QAC/C,IAAI,CAAC;YACD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACnD,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;gBACpC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC3B,OAAO,CAAC,IAAI,CAAC;oBACT,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,GAAG,EAAE,KAAK,CAAC,GAAG;oBACd,QAAQ,EAAE,QAAQ;oBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,UAAU,EAAE;wBACR,KAAK,EAAE,MAAM,CAAC,KAAK;wBACnB,KAAK,EAAE,KAAK;wBACZ,KAAK,EAAE,GAAG;qBACb;iBACJ,CAAC,CAAC;YACP,CAAC;QACL,CAAC;QAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;IAED,oBAAoB;IACpB,MAAM,IAAI,GAAa,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;IAElJ,2CAA2C;IAC3C,kGAAkG;IAClG,oGAAoG;IACpG,0CAA0C;IAC1C,MAAM,MAAM,GAAG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IACpE,IAAI,OAAO,GAAG,yBAAW,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACpD,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC;QACvB,8BAA8B;QAC9B,MAAM,QAAQ,GAAG,WAAW,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACjE,EAAE,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;YACtB,QAAQ,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QACzC,CAAC;QAAC,IAAI,CAAC,CAAC;YACJ,iCAAiC;YACjC,WAAW,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QAC/E,CAAC;QAED,iEAAiE;QACjE,oFAAoF;QACpF,qCAAqC;QACrC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,CAAC,OAAO,CAAC;AACnB,CAAC;AA9CD,4CA8CC"} \ No newline at end of file diff --git a/libraries/botbuilder-choices/lib/tokenizer.d.ts b/libraries/botbuilder-choices/lib/tokenizer.d.ts index d13e09804f..02e9ff17d5 100644 --- a/libraries/botbuilder-choices/lib/tokenizer.d.ts +++ b/libraries/botbuilder-choices/lib/tokenizer.d.ts @@ -5,15 +5,55 @@ * Copyright (c) Microsoft Corporation. All rights reserved. * Licensed under the MIT License. */ +/** +* :package: **botbuilder-choices** +* +* Individual token returned by a `TokenizerFunction`. +*/ export interface Token { + /** Start character position of the token within the outer string. */ start: number; + /** End character position of the token within the outer string. */ end: number; + /** Original text of the token. */ text: string; + /** Normalized form of the token. This can include things like lower casing or stemming. */ normalized: string; } +/** + * :package: **botbuilder-choices** + * + * Signature for an alternate word breaker that can be passed to `recognizeChoices()`, + * `findChoices()`, or `findValues()`. The `defaultTokenizer()` is fairly simple and only breaks + * on spaces and punctuation. + * @param TokenizerFunction.text The text to be tokenized. + * @param TokenizerFunction.locale (Optional) locale of the text if known. + */ export declare type TokenizerFunction = (text: string, locale?: string) => Token[]; /** - * Simple tokenizer that breaks on spaces and punctuation. The only normalization done is to lowercase + * :package: **botbuilder-choices** + * + * Simple tokenizer that breaks on spaces and punctuation. The only normalization done is to + * lowercase the tokens. Developers can wrap this tokenizer with their own function to perform + * additional normalization like [stemming](https://github.com/words/stemmer). + * + * **Usage Example** + * + * ```JavaScript + * const { recognizeChoices, defaultTokenizer } = require('botbuilder-choices'); + * const stemmer = require('stemmer'); + * + * function customTokenizer(text, locale) { + * const tokens = defaultTokenizer(text, locale); + * tokens.forEach((t) => { + * t.normalized = stemmer(t.normalized); + * }); + * return tokens; + * } * + * const choices = ['red', 'green', 'blue']; + * const utterance = context.activity.text; + * const results = recognizeChoices(utterance, choices, { tokenizer: customTokenizer }); + * ``` */ export declare function defaultTokenizer(text: string, locale?: string): Token[]; diff --git a/libraries/botbuilder-choices/lib/tokenizer.js b/libraries/botbuilder-choices/lib/tokenizer.js index 5ec5f90686..d00a73254b 100644 --- a/libraries/botbuilder-choices/lib/tokenizer.js +++ b/libraries/botbuilder-choices/lib/tokenizer.js @@ -8,8 +8,30 @@ */ Object.defineProperty(exports, "__esModule", { value: true }); /** - * Simple tokenizer that breaks on spaces and punctuation. The only normalization done is to lowercase + * :package: **botbuilder-choices** * + * Simple tokenizer that breaks on spaces and punctuation. The only normalization done is to + * lowercase the tokens. Developers can wrap this tokenizer with their own function to perform + * additional normalization like [stemming](https://github.com/words/stemmer). + * + * **Usage Example** + * + * ```JavaScript + * const { recognizeChoices, defaultTokenizer } = require('botbuilder-choices'); + * const stemmer = require('stemmer'); + * + * function customTokenizer(text, locale) { + * const tokens = defaultTokenizer(text, locale); + * tokens.forEach((t) => { + * t.normalized = stemmer(t.normalized); + * }); + * return tokens; + * } + * + * const choices = ['red', 'green', 'blue']; + * const utterance = context.activity.text; + * const results = recognizeChoices(utterance, choices, { tokenizer: customTokenizer }); + * ``` */ function defaultTokenizer(text, locale) { const tokens = []; diff --git a/libraries/botbuilder-choices/lib/tokenizer.js.map b/libraries/botbuilder-choices/lib/tokenizer.js.map index c6ae48502e..84dfbae1d1 100644 --- a/libraries/botbuilder-choices/lib/tokenizer.js.map +++ b/libraries/botbuilder-choices/lib/tokenizer.js.map @@ -1 +1 @@ -{"version":3,"file":"tokenizer.js","sourceRoot":"","sources":["../src/tokenizer.ts"],"names":[],"mappings":";AAAA;;GAEG;AACH;;;GAGG;;AAWH;;;GAGG;AACH,0BAAiC,IAAY,EAAE,MAAe;IAC1D,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,IAAI,KAAsB,CAAC;IAC3B,qBAAqB,GAAW;QAC5B,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;YACR,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC;YAChB,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAC5C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,KAAK,GAAG,SAAS,CAAC;QACtB,CAAC;IACL,CAAC;IAED,aAAa;IACb,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IACtC,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;QAChB,wFAAwF;QACxF,8CAA8C;QAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5D,MAAM,GAAG,GAAG,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAE5C,4BAA4B;QAC5B,EAAE,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YAC5B,8DAA8D;YAC9D,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC;YAC5B,6EAA6E;YAC7E,+EAA+E;YAC/E,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACnB,MAAM,CAAC,IAAI,CAAC;gBACR,KAAK,EAAE,CAAC;gBACR,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;gBACzB,IAAI,EAAE,GAAG;gBACT,UAAU,EAAE,GAAG;aAClB,CAAC,CAAC;QACP,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;YAChB,oBAAoB;YACpB,KAAK,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAW,CAAC;QAC7C,CAAC;QAAC,IAAI,CAAC,CAAC;YACJ,0BAA0B;YAC1B,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC;QACtB,CAAC;QACD,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC;IACpB,CAAC;IACD,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACxB,MAAM,CAAC,MAAM,CAAC;AAClB,CAAC;AA9CD,4CA8CC;AAED,wBAAwB,SAAiB;IACrC,MAAM,CAAC,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;QACpC,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;QACpC,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;QACpC,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;QACpC,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;QACpC,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;QACpC,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,mBAAmB,KAAa,EAAE,IAAY,EAAE,EAAU;IACtD,MAAM,CAAC,CAAC,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC;AAC1C,CAAC"} \ No newline at end of file +{"version":3,"file":"tokenizer.js","sourceRoot":"","sources":["../src/tokenizer.ts"],"names":[],"mappings":"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"} \ No newline at end of file diff --git a/libraries/botbuilder-choices/src/choiceFactory.ts b/libraries/botbuilder-choices/src/choiceFactory.ts index 9688cf8ddb..60e9d9157f 100644 --- a/libraries/botbuilder-choices/src/choiceFactory.ts +++ b/libraries/botbuilder-choices/src/choiceFactory.ts @@ -10,6 +10,11 @@ import { MessageFactory, TurnContext, ActionTypes, InputHints, Activity, CardAct import { Choice } from './findChoices'; import * as channel from './channel'; +/** + * :package: **botbuilder-choices** + * + * Additional options used to tweak the formatting of choice lists. + */ export interface ChoiceFactoryOptions { /** * (Optional) character used to separate individual choices when there are more than 2 choices. @@ -31,13 +36,54 @@ export interface ChoiceFactoryOptions { /** * (Optional) if `true`, inline and list style choices will be prefixed with the index of the - * choice as in "1. choice". If `false`, the list style will use a bulleted list instead. The default value is `true`. + * choice as in "1. choice". If `false`, the list style will use a bulleted list instead. The + * default value is `true`. */ includeNumbers?: boolean; } +/** + * :package: **botbuilder-choices** + * + * A set of utility functions to assist with the formatting a 'message' activity containing a list + * of choices. + * + * **Usage Example** + * + * ```JavaScript + * const { ChoiceFactory } = require('botbuilder-choices'); + * + * const message = ChoiceFactory.forChannel(context, ['red', 'green', 'blue'], `Pick a color.`); + * await context.sendActivity(message); + * ``` + */ export class ChoiceFactory { + /** + * Returns a 'message' activity containing a list of choices that has been automatically + * formatted based on the capabilities of a given channel. The algorithm prefers to format + * the supplied list of choices as suggested actions but can decide to use a text based list + * if suggested actions aren't natively supported by the channel, there are too many choices + * for the channel to display, or the title of any choice is too long. + * + * If the algorithm decides to use a list it will use an inline list if there are 3 or less + * choices and all have short titles. Otherwise, a numbered list is used. + * + * **Usage Example** + * + * ```JavaScript + * const message = ChoiceFactory.forChannel(context, [ + * { value: 'red', action: { type: 'imBack', title: 'The Red Pill', value: 'red pill' } }, + * { value: 'blue', action: { type: 'imBack', title: 'The Blue Pill', value: 'blue pill' } }, + * ], `Which do you choose?`); + * await context.sendActivity(message); + * ``` + * @param channelOrContext Channel ID or context object for the current turn of conversation. + * @param choices List of choices to render. + * @param text (Optional) text of the message. + * @param speak (Optional) SSML to speak for the message. + * @param options (Optional) formatting options to use when rendering as a list. + */ static forChannel(channelOrContext: string|TurnContext, choices: (string|Choice)[], text?: string, speak?: string, options?: ChoiceFactoryOptions): Partial { const channelId = typeof channelOrContext === 'string' ? channelOrContext : channel.getChannelId(channelOrContext); @@ -62,7 +108,7 @@ export class ChoiceFactory { if (!longTitles && (supportsSuggestedActions || (!hasMessageFeed && supportsCardActions))) { // We always prefer showing choices using suggested actions. If the titles are too long, however, // we'll have to show them as a text list. - return ChoiceFactory.suggestedAction(list, text, speak, options); + return ChoiceFactory.suggestedAction(list, text, speak); } else if (!longTitles && choices.length <= 3) { // If the titles are short and there are 3 or less choices we'll use an inline list. return ChoiceFactory.inline(list, text, speak, options); @@ -72,6 +118,22 @@ export class ChoiceFactory { } } + /** + * Returns a 'message' activity containing a list of choices that has been formatted as an + * inline list. + * + * **Usage Example** + * + * ```JavaScript + * // Generates a message text of `Pick a color: (1. red, 2. green, or 3. blue)` + * const message = ChoiceFactory.inline(['red', 'green', 'blue'], `Pick a color:`); + * await context.sendActivity(message); + * ``` + * @param choices List of choices to render. + * @param text (Optional) text of the message. + * @param speak (Optional) SSML to speak for the message. + * @param options (Optional) formatting options to tweak rendering of list. + */ static inline(choices: (string|Choice)[], text?: string, speak?: string, options?: ChoiceFactoryOptions): Partial { const opt = Object.assign({ inlineSeparator: ', ', @@ -99,6 +161,21 @@ export class ChoiceFactory { return MessageFactory.text(txt, speak, InputHints.ExpectingInput); } + /** + * Returns a 'message' activity containing a list of choices that has been formatted as an + * numbered or bulleted list. + * + * **Usage Example** + * + * ```JavaScript + * const message = ChoiceFactory.list(['red', 'green', 'blue'], `Pick a color:`); + * await context.sendActivity(message); + * ``` + * @param choices List of choices to render. + * @param text (Optional) text of the message. + * @param speak (Optional) SSML to speak for the message. + * @param options (Optional) formatting options to tweak rendering of list. + */ static list(choices: (string|Choice)[], text?: string, speak?: string, options?: ChoiceFactoryOptions): Partial { const opt = Object.assign({ includeNumbers: true @@ -118,7 +195,21 @@ export class ChoiceFactory { return MessageFactory.text(txt, speak, InputHints.ExpectingInput); } - static suggestedAction(choices: (string|Choice)[], text?: string, speak?: string, options?: ChoiceFactoryOptions): Partial { + /** + * Returns a 'message' activity containing a list of choices that have been added as suggested + * actions. + * + * **Usage Example** + * + * ```JavaScript + * const message = ChoiceFactory.suggestedAction(['red', 'green', 'blue'], `Pick a color:`); + * await context.sendActivity(message); + * ``` + * @param choices List of choices to add. + * @param text (Optional) text of the message. + * @param speak (Optional) SSML to speak for the message. + */ + static suggestedAction(choices: (string|Choice)[], text?: string, speak?: string): Partial { // Map choices to actions const actions = ChoiceFactory.toChoices(choices).map((choice) => { if (choice.action) { @@ -132,8 +223,17 @@ export class ChoiceFactory { return MessageFactory.suggestedActions(actions, text, speak, InputHints.ExpectingInput); } + /** + * Takes a mixed list of `string` and `Choice` based choices and returns them as a `Choice[]`. + * + * **Usage Example** + * + * ```JavaScript + * const choices = ChoiceFactory.toChoices(['red', 'green', 'blue']); + * ``` + * @param choices List of choices to add. + */ static toChoices(choices: (string|Choice)[]|undefined): Choice[] { return (choices || []).map((choice) => typeof choice === 'string' ? { value: choice } : choice).filter((choice) => choice); } - } \ No newline at end of file diff --git a/libraries/botbuilder-choices/src/findChoices.ts b/libraries/botbuilder-choices/src/findChoices.ts index 5fafa749b6..c637bf507d 100644 --- a/libraries/botbuilder-choices/src/findChoices.ts +++ b/libraries/botbuilder-choices/src/findChoices.ts @@ -10,29 +10,78 @@ import { CardAction } from 'botbuilder'; import { ModelResult } from './modelResult'; import { findValues, FindValuesOptions, SortedValue } from './findValues'; +/** + * :package: **botbuilder-choices** + * + * An instance of a choice that can be used to render a choice to a user or recognize something a + * user picked. + * + * The [value](#value) will be rendered to a user unless an [action](#action) is provided in which + * case the actions `title` will be rendered to the user. + * + * At recognition time the `value` will always be what gets returned by `findChoices()` and + * `recognizeChoices()`. By default, the users utterance will be compared against all of the + * strings provided in the choice. You can disable using the `value` and/or `action.title` during + * recognition using the `FindChoicesOptions` structure. + * + * **Usage Example** + * + * ```JavaScript + * const choice = { + * value: 'red', + * action: { + * type: 'imBack', + * title: 'The Red Pill', + * value: 'red pill' + * }, + * synonyms: ['crimson', 'scarlet', 'ruby', 'cherry'] + * }; + * ``` + */ export interface Choice { - /** Value to return when selected. */ + /** + * Value to return when recognized by `findChoices()`. Will also be used to render choices + * to the user if no [action](#action) is provided. + */ value: string; - /** (Optional) action to use when rendering the choice as a suggested action. */ + /** + * (Optional) action to use when rendering the choice as a suggested action. This **MUST** + * be a complete action containing `type`, `title`, and `value` fields. If not specified an + * `imBack` action will be generated based on the choices [value](#value) field. + */ action?: CardAction; - /** (Optional) list of synonyms to recognize in addition to the value. */ + /** + * (Optional) list of synonyms to recognize in addition to the [value](#value) and + * [action](#action) fields. + */ synonyms?: string[]; } +/** + * :package: **botbuilder-choices** + * + * Options to control the recognition performed by `findChoices()`. + */ export interface FindChoicesOptions extends FindValuesOptions { /** - * (Optional) If `true`, the choices value will NOT be search over. The default is `false`. + * (Optional) If `true`, the choices `value` field will NOT be search over. Defaults to `false`. */ noValue?: boolean; /** - * (Optional) If `true`, the title of the choices action will NOT be searched over. The default is `false`. + * (Optional) If `true`, the the choices `action.title` field will NOT be searched over. + * Defaults to `false`. */ noAction?: boolean; } +/** + * :package: **botbuilder-choices** + * + * Result returned by `findChoices()`. + */ export interface FoundChoice { /** The value of the choice that was matched. */ value: string; @@ -50,6 +99,37 @@ export interface FoundChoice { synonym?: string; } +/** + * :package: **botbuilder-choices** + * + * Mid-level search function for recognizing a choice in an utterance. This function is layered + * above `findValues()` and simply determines all of the synonyms that should be searched for + * before calling `findValues()` to perform the actual search. The `recognizeChoices()` function is + * layered above this function and adds the ability to select a choice by index or ordinal position + * in the list. Calling this particular function is useful when you don't want the index and ordinal + * position recognition done by `recognizeChoices()`. + * + * **Usage Example** + * + * ```JavaScript + * const { findChoices } = require('botbuilder-choices'); + * + * const choices = ['red', 'green', 'blue']; + * const utterance = context.activity.text; + * const results = findChoices(utterance, choices); + * if (results.length == 1) { + * await context.sendActivity(`I like ${results[0].resolution.value} too!`); + * } else if (results.length > 1) { + * const ambiguous = results.map((r) => r.resolution.value); + * await context.sendActivity(ChoiceFactory.forChannel(context, ambiguous, `Which one?`)); + * } else { + * await context.sendActivity(ChoiceFactory.forChannel(context, choices, `I didn't get that... Which color?`)); + * } + * ``` + * @param utterance The text or user utterance to search over. For an incoming 'message' activity you can simply use `context.activity.text`. + * @param choices List of choices to search over. + * @param options (Optional) options used to tweak the search that's performed. + */ export function findChoices(utterance: string, choices: (string|Choice)[], options?: FindChoicesOptions): ModelResult[] { const opt = options || {}; diff --git a/libraries/botbuilder-choices/src/findValues.ts b/libraries/botbuilder-choices/src/findValues.ts index 0476415849..c457aa69dc 100644 --- a/libraries/botbuilder-choices/src/findValues.ts +++ b/libraries/botbuilder-choices/src/findValues.ts @@ -9,6 +9,11 @@ import { Token, TokenizerFunction, defaultTokenizer } from './tokenizer'; import { ModelResult } from './modelResult'; +/** + * :package: **botbuilder-choices** + * + * Basic search options used to control how choices are recognized in a users utterance. + */ export interface FindValuesOptions { /** * (Optional) if true, then only some of the tokens in a value need to exist to be considered @@ -35,6 +40,11 @@ export interface FindValuesOptions { tokenizer?: TokenizerFunction; } +/** + * :package: **botbuilder-choices** + * + * INTERNAL: Raw search result returned by `findValues()`. + */ export interface FoundValue { /** * The value that was matched. @@ -53,7 +63,15 @@ export interface FoundValue { score: number; } -/** A value that can be sorted and still refer to its original position with a source array. */ +/** + * :package: **botbuilder-choices** + * + * INTERNAL: A value that can be sorted and still refer to its original position within a source + * array. The `findChoices()` function expands the passed in choices to individual `SortedValue` + * instances and passes them to `findValues()`. Each individual `Choice` can result in multiple + * synonyms that should be searched for so this data structure lets us pass each synonym as a value + * to search while maintaining the index of the choice that value came from. + */ export interface SortedValue { /** The value that will be sorted. */ value: string; @@ -63,7 +81,15 @@ export interface SortedValue { } /** - * Looks for a set of values within an utterance. + * :package: **botbuilder-choices** + * + * INTERNAL: Low-level function that searches for a set of values within an utterance. Higher level + * functions like `findChoices()` and `recognizeChoices()` are layered above this function. In most + * cases its easier to just call one of the higher level functions instead but this function contains + * the fuzzy search algorithm that drives choice recognition. + * @param utterance The text or user utterance to search over. + * @param values List of values to search over. + * @param options (Optional) options used to tweak the search that's performed. */ export function findValues(utterance: string, values: SortedValue[], options?: FindValuesOptions): ModelResult[] { function indexOfToken(token: Token, startPos: number): number { diff --git a/libraries/botbuilder-choices/src/modelResult.ts b/libraries/botbuilder-choices/src/modelResult.ts index 746e5fa3c0..7a5b72c055 100644 --- a/libraries/botbuilder-choices/src/modelResult.ts +++ b/libraries/botbuilder-choices/src/modelResult.ts @@ -6,15 +6,26 @@ * Licensed under the MIT License. */ +/** + * Outer result returned by an entity recognizer like `recognizeChoices()`. This structure is + * wrapped around the recognized result and contains [start](#start) and [end](#end) position + * information to identify the span of text in the users utterance that was recognized. The actual + * result can be accessed through the [resolution](#resolution) property. + * @param T The type of entity/resolution being returned. + */ export interface ModelResult { - + /** Substring of the utterance that was recognized. */ text: string + /** Start character position of the recognized substring. */ start: number + /** End character position of the recognized substring. */ end: number + /** Type of entity that was recognized. */ typeName: string + /** The recognized entity. */ resolution: T } \ No newline at end of file diff --git a/libraries/botbuilder-choices/src/recognizeChoices.ts b/libraries/botbuilder-choices/src/recognizeChoices.ts index 18694e2b5b..da9a0b22fa 100644 --- a/libraries/botbuilder-choices/src/recognizeChoices.ts +++ b/libraries/botbuilder-choices/src/recognizeChoices.ts @@ -10,6 +10,39 @@ import { Choice, findChoices, FoundChoice, FindChoicesOptions } from './findChoi import { ModelResult } from './modelResult'; import * as Recognizers from '@microsoft/recognizers-text-number'; +/** + * :package: **botbuilder-choices** + * + * High level function for recognizing a choice in a users utterance. This is layered above the + * `findChoices()` function and adds logic to let the user specify their choice by index (they can + * say "one" to pick `choice[0]`) or ordinal position (they can say "the second one" to pick + * `choice[1]`.) The users utterance is recognized in the following order: + * + * - By name using `findChoices()`. + * - By 1's based ordinal position. + * - By 1's based index position. + * + * **Usage Example** + * + * ```JavaScript + * const { recognizeChoices } = require('botbuilder-choices'); + * + * const choices = ['red', 'green', 'blue']; + * const utterance = context.activity.text; + * const results = recognizeChoices(utterance, choices); + * if (results.length == 1) { + * await context.sendActivity(`I like ${results[0].resolution.value} too!`); + * } else if (results.length > 1) { + * const ambiguous = results.map((r) => r.resolution.value); + * await context.sendActivity(ChoiceFactory.forChannel(context, ambiguous, `Which one?`)); + * } else { + * await context.sendActivity(ChoiceFactory.forChannel(context, choices, `I didn't get that... Which color?`)); + * } + * ``` + * @param utterance The text or user utterance to search over. For an incoming 'message' activity you can simply use `context.activity.text`. + * @param choices List of choices to search over. + * @param options (Optional) options used to tweak the search that's performed. + */ export function recognizeChoices(utterance: string, choices: (string|Choice)[], options?: FindChoicesOptions): ModelResult[] { function matchChoiceByIndex(match: ModelResult) { try { diff --git a/libraries/botbuilder-choices/src/tokenizer.ts b/libraries/botbuilder-choices/src/tokenizer.ts index 07240c527f..0133f41b21 100644 --- a/libraries/botbuilder-choices/src/tokenizer.ts +++ b/libraries/botbuilder-choices/src/tokenizer.ts @@ -6,18 +6,61 @@ * Licensed under the MIT License. */ + /** + * :package: **botbuilder-choices** + * + * Individual token returned by a `TokenizerFunction`. + */ export interface Token { + /** Start character position of the token within the outer string. */ start: number; + + /** End character position of the token within the outer string. */ end: number; + + /** Original text of the token. */ text: string; + + /** Normalized form of the token. This can include things like lower casing or stemming. */ normalized: string; } +/** + * :package: **botbuilder-choices** + * + * Signature for an alternate word breaker that can be passed to `recognizeChoices()`, + * `findChoices()`, or `findValues()`. The `defaultTokenizer()` is fairly simple and only breaks + * on spaces and punctuation. + * @param TokenizerFunction.text The text to be tokenized. + * @param TokenizerFunction.locale (Optional) locale of the text if known. + */ export type TokenizerFunction = (text: string, locale?: string) => Token[]; /** - * Simple tokenizer that breaks on spaces and punctuation. The only normalization done is to lowercase - * + * :package: **botbuilder-choices** + * + * Simple tokenizer that breaks on spaces and punctuation. The only normalization done is to + * lowercase the tokens. Developers can wrap this tokenizer with their own function to perform + * additional normalization like [stemming](https://github.com/words/stemmer). + * + * **Usage Example** + * + * ```JavaScript + * const { recognizeChoices, defaultTokenizer } = require('botbuilder-choices'); + * const stemmer = require('stemmer'); + * + * function customTokenizer(text, locale) { + * const tokens = defaultTokenizer(text, locale); + * tokens.forEach((t) => { + * t.normalized = stemmer(t.normalized); + * }); + * return tokens; + * } + * + * const choices = ['red', 'green', 'blue']; + * const utterance = context.activity.text; + * const results = recognizeChoices(utterance, choices, { tokenizer: customTokenizer }); + * ``` */ export function defaultTokenizer(text: string, locale?: string): Token[] { const tokens: Token[] = []; From b50d9101b266ee5a7bfb16ac1fbc22ed5e6b9d87 Mon Sep 17 00:00:00 2001 From: Steven Ickman Date: Sat, 21 Apr 2018 19:09:51 -0700 Subject: [PATCH 2/5] Updated botbuilder-prompts docs --- doc/botbuilder-prompts/README.md | 261 ++++++++++++++---- .../enums/botbuilder_prompts.liststyle.md | 12 +- .../botbuilder_prompts.attachmentprompt.md | 38 ++- .../botbuilder_prompts.choiceprompt.md | 54 +++- .../botbuilder_prompts.confirmchoices.md | 4 + .../botbuilder_prompts.confirmprompt.md | 66 ++++- .../botbuilder_prompts.datetimeprompt.md | 47 +++- .../botbuilder_prompts.founddatetime.md | 8 +- .../botbuilder_prompts.numberprompt.md | 38 ++- .../botbuilder_prompts.oauthprompt.md | 192 +++++++++++++ .../botbuilder_prompts.oauthpromptsettings.md | 65 +++++ .../botbuilder_prompts.textprompt.md | 38 ++- .../lib/attachmentPrompt.d.ts | 59 +++- .../lib/attachmentPrompt.js | 23 ++ .../lib/attachmentPrompt.js.map | 2 +- .../botbuilder-prompts/lib/choicePrompt.d.ts | 69 ++++- .../botbuilder-prompts/lib/choicePrompt.js | 20 +- .../lib/choicePrompt.js.map | 2 +- .../botbuilder-prompts/lib/confirmPrompt.d.ts | 96 ++++++- .../botbuilder-prompts/lib/confirmPrompt.js | 20 +- .../lib/confirmPrompt.js.map | 2 +- .../lib/datetimePrompt.d.ts | 68 ++++- .../botbuilder-prompts/lib/datetimePrompt.js | 22 ++ .../lib/datetimePrompt.js.map | 2 +- .../botbuilder-prompts/lib/numberPrompt.d.ts | 56 +++- .../botbuilder-prompts/lib/numberPrompt.js | 20 ++ .../lib/numberPrompt.js.map | 2 +- .../botbuilder-prompts/lib/oauthPrompt.d.ts | 115 +++++++- .../botbuilder-prompts/lib/oauthPrompt.js | 37 ++- .../botbuilder-prompts/lib/oauthPrompt.js.map | 2 +- .../botbuilder-prompts/lib/textPrompt.d.ts | 55 +++- .../botbuilder-prompts/lib/textPrompt.js | 17 ++ .../botbuilder-prompts/lib/textPrompt.js.map | 2 +- .../src/attachmentPrompt.ts | 59 +++- .../botbuilder-prompts/src/choicePrompt.ts | 71 ++++- .../botbuilder-prompts/src/confirmPrompt.ts | 100 ++++++- .../botbuilder-prompts/src/datetimePrompt.ts | 68 ++++- .../botbuilder-prompts/src/numberPrompt.ts | 58 +++- .../botbuilder-prompts/src/oauthPrompt.ts | 116 +++++++- .../botbuilder-prompts/src/textPrompt.ts | 55 +++- 40 files changed, 1853 insertions(+), 188 deletions(-) create mode 100644 doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthprompt.md create mode 100644 doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthpromptsettings.md diff --git a/doc/botbuilder-prompts/README.md b/doc/botbuilder-prompts/README.md index ee9afbf841..bd435aef59 100644 --- a/doc/botbuilder-prompts/README.md +++ b/doc/botbuilder-prompts/README.md @@ -20,12 +20,13 @@ * [DatetimePrompt](interfaces/botbuilder_prompts.datetimeprompt.md) * [FoundDatetime](interfaces/botbuilder_prompts.founddatetime.md) * [NumberPrompt](interfaces/botbuilder_prompts.numberprompt.md) +* [OAuthPrompt](interfaces/botbuilder_prompts.oauthprompt.md) +* [OAuthPromptSettings](interfaces/botbuilder_prompts.oauthpromptsettings.md) * [TextPrompt](interfaces/botbuilder_prompts.textprompt.md) ### Type aliases -* [ChoicePromptValidator](#choicepromptvalidator) * [PromptValidator](#promptvalidator) @@ -36,61 +37,24 @@ * [createConfirmPrompt](#createconfirmprompt) * [createDatetimePrompt](#createdatetimeprompt) * [createNumberPrompt](#createnumberprompt) +* [createOAuthPrompt](#createoauthprompt) * [createTextPrompt](#createtextprompt) --- ## Type aliases - - -### ChoicePromptValidator - -**Τ ChoicePromptValidator**: *`function`* - -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:60](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L60)* - - - -Signature of a handler that can be passed to a prompt to provide additional validation logic or to customize the reply sent to the user when their response is invalid. -*__param__*: Type of output that will be returned by the validator. This can be changed from the input type by the validator. - - -#### Type declaration -►(context: *[BotContext]()*, value: *[FoundChoice]()⎮`undefined`*, choices: *(`string`⎮[Choice]())[]*): [Promiseable]()`O`⎮`undefined` - - - -**Parameters:** - -| Param | Type | Description | -| ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | -| value | [FoundChoice]()⎮`undefined` | The value that was recognized or `undefined` if not recognized. | -| choices | (`string`⎮[Choice]())[] | Array of choices that should be prompted for. | - - - - - -**Returns:** [Promiseable]()`O`⎮`undefined` - - - - - - -___ - ### PromptValidator **Τ PromptValidator**: *`function`* -*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:32](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L32)* +*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:66](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L66)* + +:package: **botbuilder-prompts** Signature of a handler that can be passed to a prompt to provide additional validation logic or to customize the reply sent to the user when their response is invalid. *__param__*: Type of value that will recognized and passed to the validator as input. @@ -99,7 +63,7 @@ Signature of a handler that can be passed to a prompt to provide additional vali #### Type declaration -►(context: *[BotContext]()*, value: *`R`⎮`undefined`*): [Promiseable]()`O`⎮`undefined` +►(context: *[TurnContext]()*, value: *`R`⎮`undefined`*): [Promiseable]()`O`⎮`undefined` @@ -107,7 +71,7 @@ Signature of a handler that can be passed to a prompt to provide additional vali | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | +| context | [TurnContext]() | Context for the current turn of conversation. | | value | `R`⎮`undefined` | The value that was recognized or `undefined` if not recognized. | @@ -133,16 +97,39 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts:29](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts#L29)* +*Defined in [libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts:84](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts#L84)* +:package: **botbuilder-prompts** + Creates a new prompt that asks the user to upload one or more attachments. +**Usage Example** + + const { createAttachmentPrompt } = require('botbuilder-prompts'); + + const imagePrompt = createAttachmentPrompt(async (context, values) => { + if (values && values.length > 0) { + for (let i = 0; i < values.length; i++) { + if (!values[i].contentType.startsWith('image')) { + await imagePrompt.prompt(context, `Only images are accepted.`); + return undefined; + } + } + } else { + await imagePrompt.prompt(context, `Please upload at least one image.`); + } + return values; + }); + **Type parameters:** #### O + +(Optional) type of result returned by the `recognize()` method. This defaults to an `attachment[]` but can be changed by the prompts custom validator. + **Parameters:** | Param | Type | Description | @@ -165,26 +152,42 @@ ___ ### createChoicePrompt -► **createChoicePrompt**O(validator?: *[ChoicePromptValidator](#choicepromptvalidator)`O`*, defaultLocale?: *`undefined`⎮`string`*): [ChoicePrompt](interfaces/botbuilder_prompts.choiceprompt.md)`O` +► **createChoicePrompt**O(validator?: *[PromptValidator](#promptvalidator)[FoundChoice](), `O`*, defaultLocale?: *`undefined`⎮`string`*): [ChoicePrompt](interfaces/botbuilder_prompts.choiceprompt.md)`O` -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:66](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L66)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:119](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L119)* +:package: **botbuilder-prompts** + Creates a new prompt that asks the user to select from a list of choices. +**Usage Example** + + const { createChoicePrompt } = require('botbuilder-prompts'); + + const colorPrompt = createChoicePrompt(async (context, found) => { + if (!found) { + await colorPrompt.prompt(context, ['red', 'green', 'blue'], `Please choose a color from the list or say "cancel".`); + } + return found; + }); + **Type parameters:** #### O + +(Optional) type of result returned by the `recognize()` method. This defaults to an instance of `FoundChoice` but can be changed by the prompts custom validator. + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| validator | [ChoicePromptValidator](#choicepromptvalidator)`O` | (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. | -| defaultLocale | `undefined`⎮`string` | (Optional) locale to use if `context.request.locale` not specified. Defaults to a value of `en-us`. | +| validator | [PromptValidator](#promptvalidator)[FoundChoice](), `O` | (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. | +| defaultLocale | `undefined`⎮`string` | (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. | @@ -206,22 +209,38 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:58](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L58)* +*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:134](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L134)* + +:package: **botbuilder-prompts** Creates a new prompt that asks the user to answer a yes/no question. +**Usage Example** + + const { createConfirmPrompt } = require('botbuilder-prompts'); + + const confirmPrompt = createConfirmPrompt(async (context, confirmed) => { + if (typeof confirmed != 'boolean') { + await confirmPrompt.prompt(context, `Please answer "yes" or "no".`); + } + return confirmed; + }); + **Type parameters:** #### O + +(Optional) type of result returned by the `recognize()` method. This defaults to a boolean `true` or `false` but can be changed by the prompts custom validator. + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | | validator | [PromptValidator](#promptvalidator)`O` | (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. | -| defaultLocale | `undefined`⎮`string` | (Optional) locale to use if `context.request.locale` not specified. Defaults to a value of `en-us`. | +| defaultLocale | `undefined`⎮`string` | (Optional) locale to use if `context.activity.locale` is not specified. Defaults to a value of `en-us`. | @@ -243,22 +262,44 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:50](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L50)* +*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:114](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L114)* + +:package: **botbuilder-prompts** Creates a new prompt that asks the user to reply with a date or time. +**Usage Example** + + const { createDatetimePrompt } = require('botbuilder-prompts'); + + const timePrompt = createDatetimePrompt(async (context, values) => { + try { + if (!Array.isArray(values) || values.length < 0) { throw new Error('missing time') } + if (values[0].type !== 'datetime') { throw new Error('unsupported type') } + const value = new Date(values[0].value); + if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } + return value; + } catch (err) { + await context.sendActivity(`Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); + return undefined; + } + }); + **Type parameters:** #### O + +(Optional) type of result returned by the `recognize()` method. This defaults to an instance of `FoundDateTime` but can be changed by the prompts custom validator. + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | | validator | [PromptValidator](#promptvalidator)[FoundDatetime](interfaces/botbuilder_prompts.founddatetime.md)[], `O` | (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. | -| defaultLocale | `undefined`⎮`string` | (Optional) locale to use if `context.request.locale` not specified. Defaults to a value of `en-us`. | +| defaultLocale | `undefined`⎮`string` | (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. | @@ -280,22 +321,42 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/numberPrompt.d.ts:30](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/numberPrompt.d.ts#L30)* +*Defined in [libraries/botbuilder-prompts/lib/numberPrompt.d.ts:82](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/numberPrompt.d.ts#L82)* + +:package: **botbuilder-prompts** Creates a new prompt that asks the user to reply with a number. +**Usage Example** + + const { createNumberPrompt } = require('botbuilder-prompts'); + + const agePrompt = createNumberPrompt(async (context, value) => { + if (typeof value == 'number') { + if (value >= 1 && value < 111) { + // Return age rounded down to nearest whole number. + return Math.floor(value); + } + } + await agePrompt.prompt(context, `Please enter a number between 1 and 110 or say "cancel".`); + return undefined; + }); + **Type parameters:** #### O + +(Optional) type of result returned by the `recognize()` method. This defaults to `number` but can be changed by the prompts custom validator. + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | | validator | [PromptValidator](#promptvalidator)`number`, `O` | (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. | -| defaultLocale | `undefined`⎮`string` | (Optional) locale to use if `context.request.locale` not specified. Defaults to a value of `en-us`. | +| defaultLocale | `undefined`⎮`string` | (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. | @@ -307,6 +368,77 @@ Creates a new prompt that asks the user to reply with a number. +___ + + + +### createOAuthPrompt + +► **createOAuthPrompt**O(settings: *[OAuthPromptSettings](interfaces/botbuilder_prompts.oauthpromptsettings.md)*, validator?: *[PromptValidator](#promptvalidator)[TokenResponse](), `O`*): [OAuthPrompt](interfaces/botbuilder_prompts.oauthprompt.md)`O` + + + +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:154](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L154)* + + + +:package: **botbuilder-prompts** + +Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) service. + +**Usage Example** + + async function ensureLogin(context, state, botLogic) { + const now = new Date().getTime(); + if (state.token && now < (new Date(state.token.expiration).getTime() - 60000)) { + return botLogic(context); + } else { + const loginPrompt = createOAuthPrompt({ + connectionName: 'GitConnection', + title: 'Login To GitHub' + }); + const token = await state.loginActive ? loginPrompt.recognize(context) : loginPrompt.getUserToken(context); + if (token) { + state.loginActive = false; + state.token = token; + return botLogic(context); + } else if (context.activity.type === 'message') { + if (!state.loginActive) { + state.loginActive = true; + state.loginStart = now; + await loginPrompt.prompt(context); + } else if (now >= (state.loginStart + (5 * 60 * 1000))) { + state.loginActive = false; + await context.sendActivity(`We're having a problem logging you in. Please try again later.`); + } + } + } + } + + +**Type parameters:** + +#### O + +(Optional) type of result returned by the `recognize()` method. This defaults to an instance of `TokenResponse` but can be changed by the prompts custom validator. + +**Parameters:** + +| Param | Type | Description | +| ------ | ------ | ------ | +| settings | [OAuthPromptSettings](interfaces/botbuilder_prompts.oauthpromptsettings.md) | Configuration settings for the OAuthPrompt. | +| validator | [PromptValidator](#promptvalidator)[TokenResponse](), `O` | (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. | + + + + + +**Returns:** [OAuthPrompt](interfaces/botbuilder_prompts.oauthprompt.md)`O` + + + + + ___ @@ -317,16 +449,33 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L37)* +*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:88](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L88)* +:package: **botbuilder-prompts** + Creates a new prompt that asks the user to enter some text. +**Usage Example** + + const { createTextPrompt } = require('botbuilder-prompts'); + + const namePrompt = createTextPrompt(async (context, value) => { + if (value && value.length >= 3) { + return value; + } + await namePrompt.prompt(context, `Your entry must be at least 3 characters in length.`); + return undefined; + }); + **Type parameters:** #### O + +(Optional) type of result returned by the `recognize()` method. This defaults to return a `string` but can be changed by the prompts custom validator. + **Parameters:** | Param | Type | Description | diff --git a/doc/botbuilder-prompts/enums/botbuilder_prompts.liststyle.md b/doc/botbuilder-prompts/enums/botbuilder_prompts.liststyle.md index 99868d9b6e..4708acb4f6 100644 --- a/doc/botbuilder-prompts/enums/botbuilder_prompts.liststyle.md +++ b/doc/botbuilder-prompts/enums/botbuilder_prompts.liststyle.md @@ -5,6 +5,8 @@ # Enumeration: ListStyle +:package: **botbuilder-prompts** + Controls the way that choices for a `ChoicePrompt` or yes/no options for a `ConfirmPrompt` are presented to a user. ## Index @@ -27,7 +29,7 @@ Controls the way that choices for a `ChoicePrompt` or yes/no options for a `Conf ** auto**: = 1 -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:18](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L18)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L21)* @@ -44,7 +46,7 @@ ___ ** inline**: = 2 -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L20)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L23)* @@ -61,7 +63,7 @@ ___ ** list**: = 3 -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:22](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L22)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L25)* @@ -78,7 +80,7 @@ ___ ** none**: = 0 -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:16](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L16)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L19)* @@ -95,7 +97,7 @@ ___ ** suggestedAction**: = 4 -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L24)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L27)* diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.attachmentprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.attachmentprompt.md index e322f555b1..8b628c3506 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.attachmentprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.attachmentprompt.md @@ -5,32 +5,47 @@ # Interface: AttachmentPrompt +:package: **botbuilder-prompts** + Prompts the user to upload one or more attachments. +**Usage Example** + + const { createAttachmentPrompt } = require('botbuilder-prompts'); + + const imagePrompt = createAttachmentPrompt(); + ## Type parameters #### O +(Optional) type of result returned by the [recognize()](#recognize) method. This defaults to an `attachment[]` but can be changed by the prompts custom validator. + + ## Methods ### prompt -► **prompt**(context: *[BotContext]()*, prompt: *`string`⎮[Partial]()[Activity]()*, speak?: *`undefined`⎮`string`*): `Promise`.<`void`> +► **prompt**(context: *[TurnContext]()*, prompt: *`string`⎮[Partial]()[Activity]()*, speak?: *`undefined`⎮`string`*): `Promise`.<`void`> -*Defined in [libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts:18](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts#L18)* +*Defined in [libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts#L37)* Sends a formated prompt to the user. +**Usage Example** + + await imagePrompt.prompt(context, `Upload an image(s).`); + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | +| context | [TurnContext]() | Context for the current turn of conversation. | | prompt | `string`⎮[Partial]()[Activity]() | Text or activity to send as the prompt. | | speak | `undefined`⎮`string` | (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. | @@ -50,22 +65,31 @@ ___ ### recognize -► **recognize**(context: *[BotContext]()*): `Promise`.<`O`⎮`undefined`> +► **recognize**(context: *[TurnContext]()*): `Promise`.<`O`⎮`undefined`> + + + +*Defined in [libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts#L55)* -*Defined in [libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts#L23)* +Recognizes and validates the users reply. The result of the call will either be the recognized value or `undefined`. +The recognize() method will not automatically re-prompt the user so either the caller or the prompts custom validator will need to implement re-prompting logic. +**Usage Example** -Recognizes and validates the users reply. + const images = await imagePrompt.recognize(context); + if (images) { + // Process images + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | +| context | [TurnContext]() | Context for the current turn of conversation. | diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.choiceprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.choiceprompt.md index 514ab1c224..f42b1b03f1 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.choiceprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.choiceprompt.md @@ -5,11 +5,22 @@ # Interface: ChoicePrompt +:package: **botbuilder-prompts** + Prompts the user to select from a list of choices. +**Usage Example** + + const { createChoicePrompt } = require('botbuilder-prompts'); + + const choicePrompt = createChoicePrompt(); + ## Type parameters #### O +(Optional) type of result returned by the [recognize()](#recognize) method. This defaults to an instance of `FoundChoice` but can be changed by the prompts custom validator. + + ## Properties @@ -17,7 +28,7 @@ Prompts the user to select from a list of choices. **● choiceOptions**: *[ChoiceFactoryOptions]()* -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L34)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:50](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L50)* @@ -34,7 +45,7 @@ ___ **● recognizerOptions**: *[FindChoicesOptions]()* -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L36)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L52)* @@ -51,7 +62,7 @@ ___ **● style**: *[ListStyle](../enums/botbuilder_prompts.liststyle.md)* -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:32](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L32)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:48](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L48)* @@ -68,23 +79,31 @@ ___ ### prompt -► **prompt**(context: *[BotContext]()*, choices: *(`string`⎮[Choice]())[]*, prompt?: *`string`⎮[Partial]()[Activity]()*, speak?: *`undefined`⎮`string`*): `Promise`.<`void`> +► **prompt**(context: *[TurnContext]()*, choices: *(`string`⎮[Choice]())[]*, prompt?: *`string`⎮[Partial]()[Activity]()*, speak?: *`undefined`⎮`string`*): `Promise`.<`void`> -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:44](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L44)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:74](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L74)* Sends a formated prompt to the user. +By default, this will attempt to send the provided list of choices as buttons using `ChoiceFactory.forChannel()`. It may fallback to sending the choices as a text based list for any number of reasons. You can set the prompts [style](#style) property to force the use of a particular rendering style. + +Further tweaks can be made to the rendering of choices using the [choiceOptions](#choiceoptions) property. + +**Usage Example** + + await colorPrompt.prompt(context, ['red', 'green', 'blue'], `Pick a color.`); + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | -| choices | (`string`⎮[Choice]())[] | Array of choices that should be prompted for. | +| context | [TurnContext]() | Context for the current turn of conversation. | +| choices | (`string`⎮[Choice]())[] | Array of choices that should be prompted for. This may be different then the choices passed to [recognize()](#recognize). | | prompt | `string`⎮[Partial]()[Activity]() | (Optional) Text or activity to send as the prompt. | | speak | `undefined`⎮`string` | (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. | @@ -104,23 +123,34 @@ ___ ### recognize -► **recognize**(context: *[BotContext]()*, choices: *(`string`⎮[Choice]())[]*): `Promise`.<`O`⎮`undefined`> +► **recognize**(context: *[TurnContext]()*, choices: *(`string`⎮[Choice]())[]*): `Promise`.<`O`⎮`undefined`> + + + +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:96](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L96)* + +Recognizes and validates the users reply. The result of the call will either be the recognized value or `undefined`. -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:50](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L50)* +The recognize() method will not automatically re-prompt the user so either the caller or the prompts custom validator will need to implement re-prompting logic. +The search options for the underlying choice recognizer can be tweaked using the prompts [recognizerOptions](#recognizeroptions) property. +**Usage Example** -Recognizes and validates the users reply. + const choice = await colorPrompt.recognize(context, ['red', 'green', 'blue']); + if (choice) { + const color = choice.value; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | -| choices | (`string`⎮[Choice]())[] | Array of choices that should be recognized against. | +| context | [TurnContext]() | Context for the current turn of conversation. | +| choices | (`string`⎮[Choice]())[] | Array of choices that should be recognized against. This may be different then the choices passed to [prompt()](#prompt). | diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.confirmchoices.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.confirmchoices.md index 769456b589..08f9948a4a 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.confirmchoices.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.confirmchoices.md @@ -5,11 +5,15 @@ # Interface: ConfirmChoices +:package: **botbuilder-prompts** + Map of `ConfirmPrompt` choices for each locale the bot supports. ## Indexable \[locale: `string`\]: (`string`⎮[Choice]())[] +:package: **botbuilder-prompts** + Map of `ConfirmPrompt` choices for each locale the bot supports. diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.confirmprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.confirmprompt.md index 78272272bc..ac4b4ff31f 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.confirmprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.confirmprompt.md @@ -5,11 +5,24 @@ # Interface: ConfirmPrompt +:package: **botbuilder-prompts** + Prompts the user to answer a yes/no question. +The [prompt()](#prompt) method will attempt to send a set of buttons yes/no buttons for the user to click. By default, the text of the titles for these buttons will always be in English but you can easily add support for other languages using the prompts [choices](#choices) property. + +**Usage Example** + + const { createConfirmPrompt } = require('botbuilder-prompts'); + + const confirmPrompt = createConfirmPrompt(); + ## Type parameters #### O +(Optional) type of result returned by the [recognize()](#recognize) method. This defaults to a boolean `true` or `false` but can be changed by the prompts custom validator. + + ## Properties @@ -17,11 +30,11 @@ Prompts the user to answer a yes/no question. **● choiceOptions**: *[ChoiceFactoryOptions]()* -*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L39)* +*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L68)* -Additional options used to configure the output of the choice factory. +Additional options used to configure the output of the `ChoiceFactory`. Defaults to `{ includeNumbers: false }`. @@ -34,18 +47,22 @@ ___ **● choices**: *[ConfirmChoices](botbuilder_prompts.confirmchoices.md)* -*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:32](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L32)* +*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:58](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L58)* Allows for the localization of the confirm prompts yes/no choices to other locales besides english. The key of each entry is the languages locale code and should be lower cased. A default fallback set of choices can be specified using a key of '*'. +The default choices are configured to be `{ '*': ['yes', 'no'] }`. + **Example usage:** + const confirmPrompt = createConfirmPrompt(); + // Configure yes/no choices for english and spanish (default) - ConfirmPrompt.choices['*'] = ['sí', 'no']; - ConfirmPrompt.choices['es'] = ['sí', 'no']; - ConfirmPrompt.choices['en-us'] = ['yes', 'no']; + confirmPrompt.choices['*'] = ['sí', 'no']; + confirmPrompt.choices['es'] = ['sí', 'no']; + confirmPrompt.choices['en-us'] = ['yes', 'no']; @@ -58,7 +75,7 @@ ___ **● style**: *[ListStyle](../enums/botbuilder_prompts.liststyle.md)* -*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L37)* +*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:63](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L63)* @@ -75,22 +92,30 @@ ___ ### prompt -► **prompt**(context: *[BotContext]()*, prompt: *`string`⎮[Partial]()[Activity]()*, speak?: *`undefined`⎮`string`*): `Promise`.<`void`> +► **prompt**(context: *[TurnContext]()*, prompt: *`string`⎮[Partial]()[Activity]()*, speak?: *`undefined`⎮`string`*): `Promise`.<`void`> -*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:46](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L46)* +*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:89](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L89)* Sends a formated prompt to the user. +By default, this will attempt to send the user yes & no choices as buttons using `ChoiceFactory.forChannel()`. If the channel doesn't support buttons it will fallback to appending `(yes or no)` to the prompt. You can override this behavior using the prompts [style](#style) property. + +Further tweaks can be made to the rendering of the yes/no choices using the [choiceOptions](#choiceoptions) property. + +**Usage Example** + + await confirmPrompt.prompt(context, `This will cancel your order. Are you sure?`); + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | +| context | [TurnContext]() | Context for the current turn of conversation. | | prompt | `string`⎮[Partial]()[Activity]() | Text or activity to send as the prompt. | | speak | `undefined`⎮`string` | (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. | @@ -110,22 +135,35 @@ ___ ### recognize -► **recognize**(context: *[BotContext]()*): `Promise`.<`O`⎮`undefined`> +► **recognize**(context: *[TurnContext]()*): `Promise`.<`O`⎮`undefined`> + + + +*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:111](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L111)* -*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L51)* +Recognizes and validates the users reply. The result of the call will either be the recognized value or `undefined`. +The recognize() method will not automatically re-prompt the user so either the caller or the prompts custom validator will need to implement re-prompting logic. +**Usage Example** -Recognizes and validates the users reply. + const confirmed = await confirmPrompt.recognize(context); + if (typeof confirmed == 'boolean') { + if (confirmed) { + // User said yes + } else { + // User said no + } + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | +| context | [TurnContext]() | Context for the current turn of conversation. | diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.datetimeprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.datetimeprompt.md index 51d5e6a7dc..3ea4c7b51c 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.datetimeprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.datetimeprompt.md @@ -5,32 +5,47 @@ # Interface: DatetimePrompt -Prompts the user to reply with a date or time. +:package: **botbuilder-prompts** + +Prompts the user to reply with a date and/or time. The user can use natural language utterances like "tomorrow at 9am". + +**Usage Example** + + const { createDatetimePrompt } = require('botbuilder-prompts'); + + const timePrompt = createDatetimePrompt(); ## Type parameters #### O +(Optional) type of result returned by the [recognize()](#recognize) method. This defaults to an instance of `FoundDateTime[]` but can be changed by the prompts custom validator. + + ## Methods ### prompt -► **prompt**(context: *[BotContext]()*, prompt: *`string`⎮[Partial]()[Activity]()*, speak?: *`undefined`⎮`string`*): `Promise`.<`void`> +► **prompt**(context: *[TurnContext]()*, prompt: *`string`⎮[Partial]()[Activity]()*, speak?: *`undefined`⎮`string`*): `Promise`.<`void`> -*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L38)* +*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:60](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L60)* Sends a formated prompt to the user. +**Usage Example** + + await timePrompt.prompt(context, `What time should I set your alarm for?`); + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | +| context | [TurnContext]() | Context for the current turn of conversation. | | prompt | `string`⎮[Partial]()[Activity]() | Text or activity to send as the prompt. | | speak | `undefined`⎮`string` | (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. | @@ -50,22 +65,38 @@ ___ ### recognize -► **recognize**(context: *[BotContext]()*): `Promise`.<`O`⎮`undefined`> +► **recognize**(context: *[TurnContext]()*): `Promise`.<`O`⎮`undefined`> + + + +*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:85](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L85)* -*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:43](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L43)* +Recognizes and validates the users reply. The result of the call will either be the recognized value or `undefined`. +The recognize() method will not automatically re-prompt the user so either the caller or the prompts custom validator will need to implement re-prompting logic. +**Usage Example** -Recognizes and validates the users reply. + const values = await timePrompt.recognize(context); + if (values && values.length > 0) { + const time = values[0]; + switch (time.type) { + case 'date': + case 'time': + case 'datetime': + const date = new Date(time.value); + break; + } + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | +| context | [TurnContext]() | Context for the current turn of conversation. | diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.founddatetime.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.founddatetime.md index 34c8cbcb6d..477bc45ffc 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.founddatetime.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.founddatetime.md @@ -5,6 +5,8 @@ # Interface: FoundDatetime +:package: **botbuilder-prompts** + Datetime result returned by `DatetimePrompt`. For more details see the LUIS docs for [builtin.datetimev2](https://docs.microsoft.com/en-us/azure/cognitive-services/luis/luis-reference-prebuilt-entities#builtindatetimev2). @@ -15,7 +17,7 @@ Datetime result returned by `DatetimePrompt`. For more details see the LUIS docs **● timex**: *`string`* -*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:18](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L18)* +*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L20)* @@ -32,7 +34,7 @@ ___ **● type**: *`string`* -*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L23)* +*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L25)* @@ -49,7 +51,7 @@ ___ **● value**: *`string`* -*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:28](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L28)* +*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:30](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L30)* diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.numberprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.numberprompt.md index e10371c3f5..0834e85e60 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.numberprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.numberprompt.md @@ -5,32 +5,47 @@ # Interface: NumberPrompt +:package: **botbuilder-prompts** + Prompts the user to reply with a number. +**Usage Example** + + const { createNumberPrompt } = require('botbuilder-prompts'); + + const agePrompt = createNumberPrompt(); + ## Type parameters #### O +(Optional) type of result returned by the [recognize()](#recognize) method. This defaults to `number` but can be changed by the prompts custom validator. + + ## Methods ### prompt -► **prompt**(context: *[BotContext]()*, prompt: *`string`⎮[Partial]()[Activity]()*, speak?: *`undefined`⎮`string`*): `Promise`.<`void`> +► **prompt**(context: *[TurnContext]()*, prompt: *`string`⎮[Partial]()[Activity]()*, speak?: *`undefined`⎮`string`*): `Promise`.<`void`> -*Defined in [libraries/botbuilder-prompts/lib/numberPrompt.d.ts:18](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/numberPrompt.d.ts#L18)* +*Defined in [libraries/botbuilder-prompts/lib/numberPrompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/numberPrompt.d.ts#L37)* Sends a formated prompt to the user. +**Usage Example** + + await agePrompt.prompt(context, `How old are you?`); + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | +| context | [TurnContext]() | Context for the current turn of conversation. | | prompt | `string`⎮[Partial]()[Activity]() | Text or activity to send as the prompt. | | speak | `undefined`⎮`string` | (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. | @@ -50,22 +65,31 @@ ___ ### recognize -► **recognize**(context: *[BotContext]()*): `Promise`.<`O`⎮`undefined`> +► **recognize**(context: *[TurnContext]()*): `Promise`.<`O`⎮`undefined`> + + + +*Defined in [libraries/botbuilder-prompts/lib/numberPrompt.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/numberPrompt.d.ts#L55)* -*Defined in [libraries/botbuilder-prompts/lib/numberPrompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/numberPrompt.d.ts#L23)* +Recognizes and validates the users reply. The result of the call will either be the recognized value or `undefined`. +The recognize() method will not automatically re-prompt the user so either the caller or the prompts custom validator will need to implement re-prompting logic. +**Usage Example** -Recognizes and validates the users reply. + const age = await agePrompt.recognize(context); + if (typeof age == 'number') { + // Save age and continue + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | +| context | [TurnContext]() | Context for the current turn of conversation. | diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthprompt.md new file mode 100644 index 0000000000..d68176bca9 --- /dev/null +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthprompt.md @@ -0,0 +1,192 @@ +[Bot Builder SDK - Prompts](../README.md) > [OAuthPrompt](../interfaces/botbuilder_prompts.oauthprompt.md) + + + +# Interface: OAuthPrompt + + +:package: **botbuilder-prompts** + +Prompts the user to sign in using the Bot Frameworks Single Sign On (SSO) service. + +**Usage Example** + + const { createOAuthPrompt } = require('botbuilder-prompts'); + + const loginPrompt = createOAuthPrompt({ + connectionName: 'GitConnection', + title: 'Login To GitHub' + }); + +## Type parameters +#### O + +(Optional) type of result returned by the [recognize()](#recognize) method. This defaults to an instance of `TokenResponse` but can be changed by the prompts custom validator. + + +## Methods + + +### getUserToken + +► **getUserToken**(context: *[TurnContext]()*): `Promise`.<`O`⎮`undefined`> + + + +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:101](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L101)* + + + +Attempts to retrieve the cached token for a signed in user. You will generally want to call this before calling [prompt()](#prompt) to send the user a signin card. + +**Usage Example** + + const token = await loginPrompt.getUserToken(context); + if (!token) { + await loginPrompt.prompt(context); + } + + +**Parameters:** + +| Param | Type | Description | +| ------ | ------ | ------ | +| context | [TurnContext]() | Context for the current turn of conversation. | + + + + + +**Returns:** `Promise`.<`O`⎮`undefined`> + + + + + +___ + + + +### prompt + +► **prompt**(context: *[TurnContext]()*, prompt?: *[Partial]()[Activity]()*): `Promise`.<`void`> + + + +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:57](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L57)* + + + +Sends a formated prompt to the user. + +An `OAuthCard` will be automatically created and sent to the user requesting them to signin. If you need to localize the card or customize the message sent to the user for any reason you can pass in the `Activity` to send. This should just be an activity of type `message` and contain at least one attachment that's an `OAuthCard`. + +**Usage Example** + + await loginPrompt.prompt(context); + + +**Parameters:** + +| Param | Type | Description | +| ------ | ------ | ------ | +| context | [TurnContext]() | Context for the current turn of conversation. | +| prompt | [Partial]()[Activity]() | (Optional) activity to send along the user. This should include an attachment containing an `OAuthCard`. If ommited, an activity will be automatically generated. | + + + + + +**Returns:** `Promise`.<`void`> + + + + + +___ + + + +### recognize + +► **recognize**(context: *[TurnContext]()*): `Promise`.<`O`⎮`undefined`> + + + +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:86](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L86)* + + + +Attempts to resolve the token after [prompt()](#prompt) has been called. There are two core flows that need to be supported to complete a users signin: + +* The automatic signin flow where the SSO service will forward the bot the users access token using either an `event` or `invoke` activity. +* The "magic code" flow where a user is prompted by the SSO service to send the bot a six digit code confirming their identity. This code will be sent as a standard `message` activity. + +The `recognize()` method automatically handles both flows for the bot but you should ensure that you don't accidentally filter out the `event` and `invoke` activities before calling recognize(). Because of this we generally recommend you put the call to recognize() towards the beginning of your bot logic. + +You should also be prepared for the case where the user fails to enter the correct "magic code" or simply decides they don't want to click the signin button. + +**Usage Example** + + const token = await loginPrompt.recognize(context); + if (token) { + // Save token and continue. + } + + +**Parameters:** + +| Param | Type | Description | +| ------ | ------ | ------ | +| context | [TurnContext]() | Context for the current turn of conversation. | + + + + + +**Returns:** `Promise`.<`O`⎮`undefined`> + + + + + +___ + + + +### signOutUser + +► **signOutUser**(context: *[TurnContext]()*): `Promise`.<`void`> + + + +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:112](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L112)* + + + +Signs the user out of the service. + +**Usage Example** + + await loginPrompt.signOutUser(context); + + +**Parameters:** + +| Param | Type | Description | +| ------ | ------ | ------ | +| context | [TurnContext]() | Context for the current turn of conversation. | + + + + + +**Returns:** `Promise`.<`void`> + + + + + +___ + + diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthpromptsettings.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthpromptsettings.md new file mode 100644 index 0000000000..98d435f812 --- /dev/null +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthpromptsettings.md @@ -0,0 +1,65 @@ +[Bot Builder SDK - Prompts](../README.md) > [OAuthPromptSettings](../interfaces/botbuilder_prompts.oauthpromptsettings.md) + + + +# Interface: OAuthPromptSettings + + +:package: **botbuilder-prompts** + +Defines settings for an OAuthPrompt. + + +## Properties + + +### connectionName + +**● connectionName**: *`string`* + +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:17](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L17)* + + + +Name of the OAuth connection being used. + + + + +___ + + + +### «Optional» text + +**● text**: *`undefined`⎮`string`* + +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L21)* + + + +(Optional) additional text to include on the signin card. + + + + +___ + + + +### title + +**● title**: *`string`* + +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L19)* + + + +Title of the cards signin button. + + + + +___ + + diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.textprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.textprompt.md index f00c8ffdfc..230c6b7c06 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.textprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.textprompt.md @@ -5,32 +5,47 @@ # Interface: TextPrompt +:package: **botbuilder-prompts** + Prompts the user to reply with some text. +**Usage Example** + + const { createTextPrompt } = require('botbuilder-prompts'); + + const agePrompt = createTextPrompt(); + ## Type parameters #### O +(Optional) type of result returned by the [recognize()](#recognize) method. This defaults to return a `string` but can be changed by the prompts custom validator. + + ## Methods ### prompt -► **prompt**(context: *[BotContext]()*, prompt: *`string`⎮[Partial]()[Activity]()*, speak?: *`undefined`⎮`string`*): `Promise`.<`void`> +► **prompt**(context: *[TurnContext]()*, prompt: *`string`⎮[Partial]()[Activity]()*, speak?: *`undefined`⎮`string`*): `Promise`.<`void`> -*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:17](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L17)* +*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L36)* Sends a formated prompt to the user. +**Usage Example** + + await namePrompt.prompt(context, `What's name?`); + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | +| context | [TurnContext]() | Context for the current turn of conversation. | | prompt | `string`⎮[Partial]()[Activity]() | Text or activity to send as the prompt. | | speak | `undefined`⎮`string` | (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. | @@ -50,22 +65,31 @@ ___ ### recognize -► **recognize**(context: *[BotContext]()*): `Promise`.<`O`⎮`undefined`> +► **recognize**(context: *[TurnContext]()*): `Promise`.<`O`⎮`undefined`> + + + +*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:54](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L54)* -*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:22](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L22)* +Recognizes and validates the users reply. The result of the call will either be the recognized value or `undefined`. +The recognize() method will not automatically re-prompt the user so either the caller or the prompts custom validator will need to implement re-prompting logic. +**Usage Example** -Recognizes and validates the users reply. + const name = await namePrompt.recognize(context); + if (name) { + // Save name and continue + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | [BotContext]() | Context for the current turn of conversation. | +| context | [TurnContext]() | Context for the current turn of conversation. | diff --git a/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts b/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts index 637287fb31..411e744902 100644 --- a/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts @@ -7,23 +7,78 @@ */ import { Activity, Attachment, TurnContext } from 'botbuilder'; import { PromptValidator } from './textPrompt'; -/** Prompts the user to upload one or more attachments. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to upload one or more attachments. + * + * **Usage Example** + * + * ```JavaScript + * const { createAttachmentPrompt } = require('botbuilder-prompts'); + * + * const imagePrompt = createAttachmentPrompt(); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to an `attachment[]` but can be changed by the prompts custom validator. + */ export interface AttachmentPrompt { /** * Sends a formated prompt to the user. + * + * **Usage Example** + * + * ```JavaScript + * await imagePrompt.prompt(context, `Upload an image(s).`); + * ``` * @param context Context for the current turn of conversation. * @param prompt Text or activity to send as the prompt. * @param speak (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. */ prompt(context: TurnContext, prompt: string | Partial, speak?: string): Promise; /** - * Recognizes and validates the users reply. + * Recognizes and validates the users reply. The result of the call will either be the + * recognized value or `undefined`. + * + * The recognize() method will not automatically re-prompt the user so either the caller or the + * prompts custom validator will need to implement re-prompting logic. + * + * **Usage Example** + * + * ```JavaScript + * const images = await imagePrompt.recognize(context); + * if (images) { + * // Process images + * } + * ``` * @param context Context for the current turn of conversation. */ recognize(context: TurnContext): Promise; } /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to upload one or more attachments. + * + * **Usage Example** + * + * ```JavaScript + * const { createAttachmentPrompt } = require('botbuilder-prompts'); + * + * const imagePrompt = createAttachmentPrompt(async (context, values) => { + * if (values && values.length > 0) { + * for (let i = 0; i < values.length; i++) { + * if (!values[i].contentType.startsWith('image')) { + * await imagePrompt.prompt(context, `Only images are accepted.`); + * return undefined; + * } + * } + * } else { + * await imagePrompt.prompt(context, `Please upload at least one image.`); + * } + * return values; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to an `attachment[]` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. */ export declare function createAttachmentPrompt(validator?: PromptValidator): AttachmentPrompt; diff --git a/libraries/botbuilder-prompts/lib/attachmentPrompt.js b/libraries/botbuilder-prompts/lib/attachmentPrompt.js index 562686a733..53ff1480b1 100644 --- a/libraries/botbuilder-prompts/lib/attachmentPrompt.js +++ b/libraries/botbuilder-prompts/lib/attachmentPrompt.js @@ -2,7 +2,30 @@ Object.defineProperty(exports, "__esModule", { value: true }); const internal_1 = require("./internal"); /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to upload one or more attachments. + * + * **Usage Example** + * + * ```JavaScript + * const { createAttachmentPrompt } = require('botbuilder-prompts'); + * + * const imagePrompt = createAttachmentPrompt(async (context, values) => { + * if (values && values.length > 0) { + * for (let i = 0; i < values.length; i++) { + * if (!values[i].contentType.startsWith('image')) { + * await imagePrompt.prompt(context, `Only images are accepted.`); + * return undefined; + * } + * } + * } else { + * await imagePrompt.prompt(context, `Please upload at least one image.`); + * } + * return values; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to an `attachment[]` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. */ function createAttachmentPrompt(validator) { diff --git a/libraries/botbuilder-prompts/lib/attachmentPrompt.js.map b/libraries/botbuilder-prompts/lib/attachmentPrompt.js.map index 140f53f533..05fb0a0a71 100644 --- a/libraries/botbuilder-prompts/lib/attachmentPrompt.js.map +++ b/libraries/botbuilder-prompts/lib/attachmentPrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"attachmentPrompt.js","sourceRoot":"","sources":["../src/attachmentPrompt.ts"],"names":[],"mappings":";;AASA,yCAAwC;AAmBxC;;;GAGG;AACH,gCAAyD,SAA4C;IACjG,MAAM,CAAC;QACH,MAAM,EAAE,gBAAgB,OAAO,EAAE,MAAM,EAAE,KAAK;YAC1C,MAAM,CAAC,qBAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;QACD,SAAS,EAAE,mBAAmB,OAAO;YACjC,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;YAC3E,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAa,CAAC,CAAC;QACnF,CAAC;KACJ,CAAC;AACN,CAAC;AAVD,wDAUC"} \ No newline at end of file +{"version":3,"file":"attachmentPrompt.js","sourceRoot":"","sources":["../src/attachmentPrompt.ts"],"names":[],"mappings":";;AASA,yCAAwC;AAmDxC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,gCAAyD,SAA4C;IACjG,MAAM,CAAC;QACH,MAAM,EAAE,gBAAgB,OAAO,EAAE,MAAM,EAAE,KAAK;YAC1C,MAAM,CAAC,qBAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;QACD,SAAS,EAAE,mBAAmB,OAAO;YACjC,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;YAC3E,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAa,CAAC,CAAC;QACnF,CAAC;KACJ,CAAC;AACN,CAAC;AAVD,wDAUC"} \ No newline at end of file diff --git a/libraries/botbuilder-prompts/lib/choicePrompt.d.ts b/libraries/botbuilder-prompts/lib/choicePrompt.d.ts index bdba398a25..d55b7cf86c 100644 --- a/libraries/botbuilder-prompts/lib/choicePrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/choicePrompt.d.ts @@ -9,6 +9,8 @@ import { Activity, TurnContext } from 'botbuilder'; import { FoundChoice, Choice, ChoiceFactoryOptions, FindChoicesOptions } from 'botbuilder-choices'; import { PromptValidator } from './textPrompt'; /** + * :package: **botbuilder-prompts** + * * Controls the way that choices for a `ChoicePrompt` or yes/no options for a `ConfirmPrompt` are * presented to a user. */ @@ -24,7 +26,20 @@ export declare enum ListStyle { /** Add choices to prompt as suggested actions. */ suggestedAction = 4, } -/** Prompts the user to select from a list of choices. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to select from a list of choices. + * + * **Usage Example** + * + * ```JavaScript + * const { createChoicePrompt } = require('botbuilder-prompts'); + * + * const choicePrompt = createChoicePrompt(); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to an instance of `FoundChoice` but can be changed by the prompts custom validator. + */ export interface ChoicePrompt { /** * Style of choices sent to user when [prompt()](#prompt) is called. Defaults @@ -37,21 +52,67 @@ export interface ChoicePrompt { recognizerOptions: FindChoicesOptions; /** * Sends a formated prompt to the user. + * + * By default, this will attempt to send the provided list of choices as buttons using + * `ChoiceFactory.forChannel()`. It may fallback to sending the choices as a text based list + * for any number of reasons. You can set the prompts [style](#style) property to force the use + * of a particular rendering style. + * + * Further tweaks can be made to the rendering of choices using the + * [choiceOptions](#choiceoptions) property. + * + * **Usage Example** + * + * ```JavaScript + * await colorPrompt.prompt(context, ['red', 'green', 'blue'], `Pick a color.`); + * ``` * @param context Context for the current turn of conversation. - * @param choices Array of choices that should be prompted for. + * @param choices Array of choices that should be prompted for. This may be different then the choices passed to [recognize()](#recognize). * @param prompt (Optional) Text or activity to send as the prompt. * @param speak (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. */ prompt(context: TurnContext, choices: (string | Choice)[], prompt?: string | Partial, speak?: string): Promise; /** - * Recognizes and validates the users reply. + * Recognizes and validates the users reply. The result of the call will either be the + * recognized value or `undefined`. + * + * The recognize() method will not automatically re-prompt the user so either the caller or the + * prompts custom validator will need to implement re-prompting logic. + * + * The search options for the underlying choice recognizer can be tweaked using the prompts + * [recognizerOptions](#recognizeroptions) property. + * + * **Usage Example** + * + * ```JavaScript + * const choice = await colorPrompt.recognize(context, ['red', 'green', 'blue']); + * if (choice) { + * const color = choice.value; + * } + * ``` * @param context Context for the current turn of conversation. - * @param choices Array of choices that should be recognized against. + * @param choices Array of choices that should be recognized against. This may be different then the choices passed to [prompt()](#prompt). */ recognize(context: TurnContext, choices: (string | Choice)[]): Promise; } /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to select from a list of choices. + * + * **Usage Example** + * + * ```JavaScript + * const { createChoicePrompt } = require('botbuilder-prompts'); + * + * const colorPrompt = createChoicePrompt(async (context, found) => { + * if (!found) { + * await colorPrompt.prompt(context, ['red', 'green', 'blue'], `Please choose a color from the list or say "cancel".`); + * } + * return found; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to an instance of `FoundChoice` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. * @param defaultLocale (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-prompts/lib/choicePrompt.js b/libraries/botbuilder-prompts/lib/choicePrompt.js index c3b2ddf7bf..458d27b665 100644 --- a/libraries/botbuilder-prompts/lib/choicePrompt.js +++ b/libraries/botbuilder-prompts/lib/choicePrompt.js @@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true }); const botbuilder_choices_1 = require("botbuilder-choices"); const internal_1 = require("./internal"); /** + * :package: **botbuilder-prompts** + * * Controls the way that choices for a `ChoicePrompt` or yes/no options for a `ConfirmPrompt` are * presented to a user. */ @@ -20,7 +22,23 @@ var ListStyle; ListStyle[ListStyle["suggestedAction"] = 4] = "suggestedAction"; })(ListStyle = exports.ListStyle || (exports.ListStyle = {})); /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to select from a list of choices. + * + * **Usage Example** + * + * ```JavaScript + * const { createChoicePrompt } = require('botbuilder-prompts'); + * + * const colorPrompt = createChoicePrompt(async (context, found) => { + * if (!found) { + * await colorPrompt.prompt(context, ['red', 'green', 'blue'], `Please choose a color from the list or say "cancel".`); + * } + * return found; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to an instance of `FoundChoice` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. * @param defaultLocale (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. */ @@ -44,7 +62,7 @@ function createChoicePrompt(validator, defaultLocale) { msg = botbuilder_choices_1.ChoiceFactory.list(choices, prompt, speak, this.choiceOptions); break; case ListStyle.suggestedAction: - msg = botbuilder_choices_1.ChoiceFactory.suggestedAction(choices, prompt, speak, this.choiceOptions); + msg = botbuilder_choices_1.ChoiceFactory.suggestedAction(choices, prompt, speak); break; case ListStyle.none: msg = { type: 'message', text: prompt }; diff --git a/libraries/botbuilder-prompts/lib/choicePrompt.js.map b/libraries/botbuilder-prompts/lib/choicePrompt.js.map index b19f892a12..1a70a45324 100644 --- a/libraries/botbuilder-prompts/lib/choicePrompt.js.map +++ b/libraries/botbuilder-prompts/lib/choicePrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"choicePrompt.js","sourceRoot":"","sources":["../src/choicePrompt.ts"],"names":[],"mappings":"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"} \ No newline at end of file +{"version":3,"file":"choicePrompt.js","sourceRoot":"","sources":["../src/choicePrompt.ts"],"names":[],"mappings":"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"} \ No newline at end of file diff --git a/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts b/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts index 6fbdbde48d..ba0734a659 100644 --- a/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts @@ -9,50 +9,126 @@ import { Activity, TurnContext } from 'botbuilder'; import { ChoiceFactoryOptions, Choice } from 'botbuilder-choices'; import { PromptValidator } from './textPrompt'; import { ListStyle } from './choicePrompt'; -/** Map of `ConfirmPrompt` choices for each locale the bot supports. */ +/** + * :package: **botbuilder-prompts** + * + * Map of `ConfirmPrompt` choices for each locale the bot supports. + */ export interface ConfirmChoices { [locale: string]: (string | Choice)[]; } -/** Prompts the user to answer a yes/no question. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to answer a yes/no question. + * + * The [prompt()](#prompt) method will attempt to send a set of buttons yes/no buttons for the + * user to click. By default, the text of the titles for these buttons will always be in English + * but you can easily add support for other languages using the prompts [choices](#choices) + * property. + * + * **Usage Example** + * + * ```JavaScript + * const { createConfirmPrompt } = require('botbuilder-prompts'); + * + * const confirmPrompt = createConfirmPrompt(); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to a boolean `true` or `false` but can be changed by the prompts custom validator. + */ export interface ConfirmPrompt { /** * Allows for the localization of the confirm prompts yes/no choices to other locales besides * english. The key of each entry is the languages locale code and should be lower cased. A * default fallback set of choices can be specified using a key of '*'. * + * The default choices are configured to be `{ '*': ['yes', 'no'] }`. + * * **Example usage:** * * ```JavaScript + * const confirmPrompt = createConfirmPrompt(); + * // Configure yes/no choices for english and spanish (default) - * ConfirmPrompt.choices['*'] = ['sí', 'no']; - * ConfirmPrompt.choices['es'] = ['sí', 'no']; - * ConfirmPrompt.choices['en-us'] = ['yes', 'no']; + * confirmPrompt.choices['*'] = ['sí', 'no']; + * confirmPrompt.choices['es'] = ['sí', 'no']; + * confirmPrompt.choices['en-us'] = ['yes', 'no']; * ``` */ choices: ConfirmChoices; /** - * Style of choices sent to user when [prompt()](#prompt) is called. Defaults - * to `ListStyle.auto`. + * Style of choices sent to user when [prompt()](#prompt) is called. Defaults to + * `ListStyle.auto`. */ style: ListStyle; - /** Additional options used to configure the output of the choice factory. */ + /** + * Additional options used to configure the output of the `ChoiceFactory`. Defaults to + * `{ includeNumbers: false }`. + */ choiceOptions: ChoiceFactoryOptions; /** * Sends a formated prompt to the user. + * + * By default, this will attempt to send the user yes & no choices as buttons using + * `ChoiceFactory.forChannel()`. If the channel doesn't support buttons it will fallback to + * appending ` (yes or no)` to the prompt. You can override this behavior using the prompts + * [style](#style) property. + * + * Further tweaks can be made to the rendering of the yes/no choices using the + * [choiceOptions](#choiceoptions) property. + * + * **Usage Example** + * + * ```JavaScript + * await confirmPrompt.prompt(context, `This will cancel your order. Are you sure?`); + * ``` * @param context Context for the current turn of conversation. * @param prompt Text or activity to send as the prompt. * @param speak (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. */ prompt(context: TurnContext, prompt: string | Partial, speak?: string): Promise; /** - * Recognizes and validates the users reply. + * Recognizes and validates the users reply. The result of the call will either be the + * recognized value or `undefined`. + * + * The recognize() method will not automatically re-prompt the user so either the caller or the + * prompts custom validator will need to implement re-prompting logic. + * + * **Usage Example** + * + * ```JavaScript + * const confirmed = await confirmPrompt.recognize(context); + * if (typeof confirmed == 'boolean') { + * if (confirmed) { + * // User said yes + * } else { + * // User said no + * } + * } + * ``` * @param context Context for the current turn of conversation. */ recognize(context: TurnContext): Promise; } /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to answer a yes/no question. + * + * **Usage Example** + * + * ```JavaScript + * const { createConfirmPrompt } = require('botbuilder-prompts'); + * + * const confirmPrompt = createConfirmPrompt(async (context, confirmed) => { + * if (typeof confirmed != 'boolean') { + * await confirmPrompt.prompt(context, `Please answer "yes" or "no".`); + * } + * return confirmed; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to a boolean `true` or `false` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. - * @param defaultLocale (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. + * @param defaultLocale (Optional) locale to use if `context.activity.locale` is not specified. Defaults to a value of `en-us`. */ export declare function createConfirmPrompt(validator?: PromptValidator, defaultLocale?: string): ConfirmPrompt; diff --git a/libraries/botbuilder-prompts/lib/confirmPrompt.js b/libraries/botbuilder-prompts/lib/confirmPrompt.js index 0934f32cb3..56db54ddac 100644 --- a/libraries/botbuilder-prompts/lib/confirmPrompt.js +++ b/libraries/botbuilder-prompts/lib/confirmPrompt.js @@ -5,9 +5,25 @@ const internal_1 = require("./internal"); const choicePrompt_1 = require("./choicePrompt"); const Recognizers = require("@microsoft/recognizers-text-choice"); /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to answer a yes/no question. + * + * **Usage Example** + * + * ```JavaScript + * const { createConfirmPrompt } = require('botbuilder-prompts'); + * + * const confirmPrompt = createConfirmPrompt(async (context, confirmed) => { + * if (typeof confirmed != 'boolean') { + * await confirmPrompt.prompt(context, `Please answer "yes" or "no".`); + * } + * return confirmed; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to a boolean `true` or `false` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. - * @param defaultLocale (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. + * @param defaultLocale (Optional) locale to use if `context.activity.locale` is not specified. Defaults to a value of `en-us`. */ function createConfirmPrompt(validator, defaultLocale) { return { @@ -35,7 +51,7 @@ function createConfirmPrompt(validator, defaultLocale) { msg = botbuilder_choices_1.ChoiceFactory.list(choices, prompt, speak, this.choiceOptions); break; case choicePrompt_1.ListStyle.suggestedAction: - msg = botbuilder_choices_1.ChoiceFactory.suggestedAction(choices, prompt, speak, this.choiceOptions); + msg = botbuilder_choices_1.ChoiceFactory.suggestedAction(choices, prompt, speak); break; case choicePrompt_1.ListStyle.none: msg = { type: 'message', text: prompt }; diff --git a/libraries/botbuilder-prompts/lib/confirmPrompt.js.map b/libraries/botbuilder-prompts/lib/confirmPrompt.js.map index f75bf3fe0e..44cb2e2747 100644 --- a/libraries/botbuilder-prompts/lib/confirmPrompt.js.map +++ b/libraries/botbuilder-prompts/lib/confirmPrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"confirmPrompt.js","sourceRoot":"","sources":["../src/confirmPrompt.ts"],"names":[],"mappings":"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"} \ No newline at end of file +{"version":3,"file":"confirmPrompt.js","sourceRoot":"","sources":["../src/confirmPrompt.ts"],"names":[],"mappings":"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"} \ No newline at end of file diff --git a/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts b/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts index de9caff0f4..7a1d8bb335 100644 --- a/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts @@ -8,6 +8,8 @@ import { Activity, TurnContext } from 'botbuilder'; import { PromptValidator } from './textPrompt'; /** + * :package: **botbuilder-prompts** + * * Datetime result returned by `DatetimePrompt`. For more details see the LUIS docs for * [builtin.datetimev2](https://docs.microsoft.com/en-us/azure/cognitive-services/luis/luis-reference-prebuilt-entities#builtindatetimev2). */ @@ -27,23 +29,85 @@ export interface FoundDatetime { */ value: string; } -/** Prompts the user to reply with a date or time. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to reply with a date and/or time. The user can use natural language utterances + * like "tomorrow at 9am". + * + * **Usage Example** + * + * ```JavaScript + * const { createDatetimePrompt } = require('botbuilder-prompts'); + * + * const timePrompt = createDatetimePrompt(); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to an instance of `FoundDateTime[]` but can be changed by the prompts custom validator. + */ export interface DatetimePrompt { /** * Sends a formated prompt to the user. + * + * **Usage Example** + * + * ```JavaScript + * await timePrompt.prompt(context, `What time should I set your alarm for?`); + * ``` * @param context Context for the current turn of conversation. * @param prompt Text or activity to send as the prompt. * @param speak (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. */ prompt(context: TurnContext, prompt: string | Partial, speak?: string): Promise; /** - * Recognizes and validates the users reply. + * Recognizes and validates the users reply. The result of the call will either be the + * recognized value or `undefined`. + * + * The recognize() method will not automatically re-prompt the user so either the caller or the + * prompts custom validator will need to implement re-prompting logic. + * + * **Usage Example** + * + * ```JavaScript + * const values = await timePrompt.recognize(context); + * if (values && values.length > 0) { + * const time = values[0]; + * switch (time.type) { + * case 'date': + * case 'time': + * case 'datetime': + * const date = new Date(time.value); + * break; + * } + * } + * ``` * @param context Context for the current turn of conversation. */ recognize(context: TurnContext): Promise; } /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to reply with a date or time. + * + * **Usage Example** + * + * ```JavaScript + * const { createDatetimePrompt } = require('botbuilder-prompts'); + * + * const timePrompt = createDatetimePrompt(async (context, values) => { + * try { + * if (!Array.isArray(values) || values.length < 0) { throw new Error('missing time') } + * if (values[0].type !== 'datetime') { throw new Error('unsupported type') } + * const value = new Date(values[0].value); + * if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } + * return value; + * } catch (err) { + * await context.sendActivity(`Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); + * return undefined; + * } + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to an instance of `FoundDateTime` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. * @param defaultLocale (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-prompts/lib/datetimePrompt.js b/libraries/botbuilder-prompts/lib/datetimePrompt.js index 0a7cb37168..f23682a1af 100644 --- a/libraries/botbuilder-prompts/lib/datetimePrompt.js +++ b/libraries/botbuilder-prompts/lib/datetimePrompt.js @@ -3,7 +3,29 @@ Object.defineProperty(exports, "__esModule", { value: true }); const internal_1 = require("./internal"); const Recognizers = require("@microsoft/recognizers-text-date-time"); /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to reply with a date or time. + * + * **Usage Example** + * + * ```JavaScript + * const { createDatetimePrompt } = require('botbuilder-prompts'); + * + * const timePrompt = createDatetimePrompt(async (context, values) => { + * try { + * if (!Array.isArray(values) || values.length < 0) { throw new Error('missing time') } + * if (values[0].type !== 'datetime') { throw new Error('unsupported type') } + * const value = new Date(values[0].value); + * if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } + * return value; + * } catch (err) { + * await context.sendActivity(`Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); + * return undefined; + * } + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to an instance of `FoundDateTime` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. * @param defaultLocale (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-prompts/lib/datetimePrompt.js.map b/libraries/botbuilder-prompts/lib/datetimePrompt.js.map index eb6ef5dc50..cf618147e8 100644 --- a/libraries/botbuilder-prompts/lib/datetimePrompt.js.map +++ b/libraries/botbuilder-prompts/lib/datetimePrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"datetimePrompt.js","sourceRoot":"","sources":["../src/datetimePrompt.ts"],"names":[],"mappings":";;AASA,yCAAwC;AACxC,qEAAqE;AA0CrE;;;;GAIG;AACH,8BAA0D,SAA+C,EAAE,aAAsB;IAC7H,MAAM,CAAC;QACH,MAAM,EAAE,gBAAgB,OAAO,EAAE,MAAM,EAAE,KAAK;YAC1C,MAAM,CAAC,qBAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;QACD,SAAS,EAAE,mBAAmB,OAAO;YACjC,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;YACvC,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;YACrC,MAAM,MAAM,GAAI,OAAO,CAAC,MAAM,IAAI,aAAa,IAAI,OAAO,CAAC;YAC3D,MAAM,OAAO,GAAG,WAAW,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YACjE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;YACtG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAa,CAAC,CAAC;QACnF,CAAC;KACJ,CAAC;AACN,CAAC;AAdD,oDAcC"} \ No newline at end of file +{"version":3,"file":"datetimePrompt.js","sourceRoot":"","sources":["../src/datetimePrompt.ts"],"names":[],"mappings":";;AASA,yCAAwC;AACxC,qEAAqE;AAoFrE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,8BAA0D,SAA+C,EAAE,aAAsB;IAC7H,MAAM,CAAC;QACH,MAAM,EAAE,gBAAgB,OAAO,EAAE,MAAM,EAAE,KAAK;YAC1C,MAAM,CAAC,qBAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;QACD,SAAS,EAAE,mBAAmB,OAAO;YACjC,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;YACvC,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;YACrC,MAAM,MAAM,GAAI,OAAO,CAAC,MAAM,IAAI,aAAa,IAAI,OAAO,CAAC;YAC3D,MAAM,OAAO,GAAG,WAAW,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YACjE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;YACtG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAa,CAAC,CAAC;QACnF,CAAC;KACJ,CAAC;AACN,CAAC;AAdD,oDAcC"} \ No newline at end of file diff --git a/libraries/botbuilder-prompts/lib/numberPrompt.d.ts b/libraries/botbuilder-prompts/lib/numberPrompt.d.ts index 81ff90f13a..2b74e5afa8 100644 --- a/libraries/botbuilder-prompts/lib/numberPrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/numberPrompt.d.ts @@ -7,23 +7,75 @@ */ import { Activity, TurnContext } from 'botbuilder'; import { PromptValidator } from './textPrompt'; -/** Prompts the user to reply with a number. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to reply with a number. + * + * **Usage Example** + * + * ```JavaScript + * const { createNumberPrompt } = require('botbuilder-prompts'); + * + * const agePrompt = createNumberPrompt(); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to `number` but can be changed by the prompts custom validator. + */ export interface NumberPrompt { /** * Sends a formated prompt to the user. + * + * **Usage Example** + * + * ```JavaScript + * await agePrompt.prompt(context, `How old are you?`); + * ``` * @param context Context for the current turn of conversation. * @param prompt Text or activity to send as the prompt. * @param speak (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. */ prompt(context: TurnContext, prompt: string | Partial, speak?: string): Promise; /** - * Recognizes and validates the users reply. + * Recognizes and validates the users reply. The result of the call will either be the + * recognized value or `undefined`. + * + * The recognize() method will not automatically re-prompt the user so either the caller or the + * prompts custom validator will need to implement re-prompting logic. + * + * **Usage Example** + * + * ```JavaScript + * const age = await agePrompt.recognize(context); + * if (typeof age == 'number') { + * // Save age and continue + * } + * ``` * @param context Context for the current turn of conversation. */ recognize(context: TurnContext): Promise; } /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to reply with a number. + * + * **Usage Example** + * + * ```JavaScript + * const { createNumberPrompt } = require('botbuilder-prompts'); + * + * const agePrompt = createNumberPrompt(async (context, value) => { + * if (typeof value == 'number') { + * if (value >= 1 && value < 111) { + * // Return age rounded down to nearest whole number. + * return Math.floor(value); + * } + * } + * await agePrompt.prompt(context, `Please enter a number between 1 and 110 or say "cancel".`); + * return undefined; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to `number` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. * @param defaultLocale (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-prompts/lib/numberPrompt.js b/libraries/botbuilder-prompts/lib/numberPrompt.js index 2500d8f369..e8da2025de 100644 --- a/libraries/botbuilder-prompts/lib/numberPrompt.js +++ b/libraries/botbuilder-prompts/lib/numberPrompt.js @@ -3,7 +3,27 @@ Object.defineProperty(exports, "__esModule", { value: true }); const internal_1 = require("./internal"); const Recognizers = require("@microsoft/recognizers-text-number"); /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to reply with a number. + * + * **Usage Example** + * + * ```JavaScript + * const { createNumberPrompt } = require('botbuilder-prompts'); + * + * const agePrompt = createNumberPrompt(async (context, value) => { + * if (typeof value == 'number') { + * if (value >= 1 && value < 111) { + * // Return age rounded down to nearest whole number. + * return Math.floor(value); + * } + * } + * await agePrompt.prompt(context, `Please enter a number between 1 and 110 or say "cancel".`); + * return undefined; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to `number` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. * @param defaultLocale (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-prompts/lib/numberPrompt.js.map b/libraries/botbuilder-prompts/lib/numberPrompt.js.map index c82ccb2f6a..f99b2c009f 100644 --- a/libraries/botbuilder-prompts/lib/numberPrompt.js.map +++ b/libraries/botbuilder-prompts/lib/numberPrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"numberPrompt.js","sourceRoot":"","sources":["../src/numberPrompt.ts"],"names":[],"mappings":";;AASA,yCAAwC;AACxC,kEAAkE;AAmBlE;;;;GAIG;AACH,4BAA+C,SAAsC,EAAE,aAAsB;IACzG,MAAM,CAAC;QACH,MAAM,EAAE,gBAAgB,OAAO,EAAE,MAAM,EAAE,KAAK;YAC1C,MAAM,CAAC,qBAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;QACD,SAAS,EAAE,mBAAmB,OAAO;YACjC,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;YACvC,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;YACrC,MAAM,MAAM,GAAI,OAAO,CAAC,MAAM,IAAI,aAAa,IAAI,OAAO,CAAC;YAC3D,MAAM,OAAO,GAAG,WAAW,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAChH,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAY,CAAC,CAAC;QACjF,CAAC;KACJ,CAAC;AACN,CAAC;AAdD,gDAcC"} \ No newline at end of file +{"version":3,"file":"numberPrompt.js","sourceRoot":"","sources":["../src/numberPrompt.ts"],"names":[],"mappings":";;AASA,yCAAwC;AACxC,kEAAkE;AAmDlE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,4BAA+C,SAAsC,EAAE,aAAsB;IACzG,MAAM,CAAC;QACH,MAAM,EAAE,gBAAgB,OAAO,EAAE,MAAM,EAAE,KAAK;YAC1C,MAAM,CAAC,qBAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;QACD,SAAS,EAAE,mBAAmB,OAAO;YACjC,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;YACvC,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;YACrC,MAAM,MAAM,GAAI,OAAO,CAAC,MAAM,IAAI,aAAa,IAAI,OAAO,CAAC;YAC3D,MAAM,OAAO,GAAG,WAAW,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAChH,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAY,CAAC,CAAC;QACjF,CAAC;KACJ,CAAC;AACN,CAAC;AAdD,gDAcC"} \ No newline at end of file diff --git a/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts b/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts index e628f2e3bc..41782352d0 100644 --- a/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts @@ -7,7 +7,11 @@ */ import { Activity, TurnContext, TokenResponse } from 'botbuilder'; import { PromptValidator } from './textPrompt'; -/** Defines settings for an OAuthPrompt. */ +/** + * :package: **botbuilder-prompts** + * + * Defines settings for an OAuthPrompt. + */ export interface OAuthPromptSettings { /** Name of the OAuth connection being used. */ connectionName: string; @@ -16,33 +20,134 @@ export interface OAuthPromptSettings { /** (Optional) additional text to include on the signin card. */ text?: string; } -/** Prompts the user to sign in using the Bot Frameworks Single Sign On (SSO) service. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to sign in using the Bot Frameworks Single Sign On (SSO) service. + * + * **Usage Example** + * + * ```JavaScript + * const { createOAuthPrompt } = require('botbuilder-prompts'); + * + * const loginPrompt = createOAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to an instance of `TokenResponse` but can be changed by the prompts custom validator. + */ export interface OAuthPrompt { /** * Sends a formated prompt to the user. + * + * An `OAuthCard` will be automatically created and sent to the user requesting them to + * signin. If you need to localize the card or customize the message sent to the user for any + * reason you can pass in the `Activity` to send. This should just be an activity of type + * `message` and contain at least one attachment that's an `OAuthCard`. + * + * **Usage Example** + * + * ```JavaScript + * await loginPrompt.prompt(context); + * ``` * @param context Context for the current turn of conversation. * @param prompt (Optional) activity to send along the user. This should include an attachment containing an `OAuthCard`. If ommited, an activity will be automatically generated. */ prompt(context: TurnContext, prompt?: Partial): Promise; /** - * Recognizes and validates replies to a call to [prompt()](#prompt). + * Attempts to resolve the token after [prompt()](#prompt) has been called. There are two core + * flows that need to be supported to complete a users signin: + * + * - The automatic signin flow where the SSO service will forward the bot the users access + * token using either an `event` or `invoke` activity. + * - The "magic code" flow where a user is prompted by the SSO service to send the bot a six + * digit code confirming their identity. This code will be sent as a standard `message` activity. + * + * The `recognize()` method automatically handles both flows for the bot but you should ensure + * that you don't accidentally filter out the `event` and `invoke` activities before calling + * recognize(). Because of this we generally recommend you put the call to recognize() towards + * the beginning of your bot logic. + * + * You should also be prepared for the case where the user fails to enter the correct + * "magic code" or simply decides they don't want to click the signin button. + * + * **Usage Example** + * + * ```JavaScript + * const token = await loginPrompt.recognize(context); + * if (token) { + * // Save token and continue. + * } + * ``` * @param context Context for the current turn of conversation. * @param connectionName Name of the auth connection to use. */ recognize(context: TurnContext): Promise; /** - * Attempts to retrieve the cached token for a signed in user. + * Attempts to retrieve the cached token for a signed in user. You will generally want to call + * this before calling [prompt()](#prompt) to send the user a signin card. + * + * **Usage Example** + * + * ```JavaScript + * const token = await loginPrompt.getUserToken(context); + * if (!token) { + * await loginPrompt.prompt(context); + * } + * ``` * @param context Context for the current turn of conversation. */ getUserToken(context: TurnContext): Promise; /** * Signs the user out of the service. + * + * **Usage Example** + * + * ```JavaScript + * await loginPrompt.signOutUser(context); + * ``` * @param context Context for the current turn of conversation. */ signOutUser(context: TurnContext): Promise; } /** - * Creates a new prompt that asks the user to enter some text. + * :package: **botbuilder-prompts** + * + * Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) + * service. + * + * **Usage Example** + * + * ```JavaScript + * async function ensureLogin(context, state, botLogic) { + * const now = new Date().getTime(); + * if (state.token && now < (new Date(state.token.expiration).getTime() - 60000)) { + * return botLogic(context); + * } else { + * const loginPrompt = createOAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * const token = await state.loginActive ? loginPrompt.recognize(context) : loginPrompt.getUserToken(context); + * if (token) { + * state.loginActive = false; + * state.token = token; + * return botLogic(context); + * } else if (context.activity.type === 'message') { + * if (!state.loginActive) { + * state.loginActive = true; + * state.loginStart = now; + * await loginPrompt.prompt(context); + * } else if (now >= (state.loginStart + (5 * 60 * 1000))) { + * state.loginActive = false; + * await context.sendActivity(`We're having a problem logging you in. Please try again later.`); + * } + * } + * } + * } + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to an instance of `TokenResponse` but can be changed by the prompts custom validator. * @param settings Configuration settings for the OAuthPrompt. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. */ diff --git a/libraries/botbuilder-prompts/lib/oauthPrompt.js b/libraries/botbuilder-prompts/lib/oauthPrompt.js index ee1d6ff533..f3f55c2141 100644 --- a/libraries/botbuilder-prompts/lib/oauthPrompt.js +++ b/libraries/botbuilder-prompts/lib/oauthPrompt.js @@ -10,7 +10,42 @@ Object.defineProperty(exports, "__esModule", { value: true }); const botbuilder_1 = require("botbuilder"); const internal_1 = require("./internal"); /** - * Creates a new prompt that asks the user to enter some text. + * :package: **botbuilder-prompts** + * + * Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) + * service. + * + * **Usage Example** + * + * ```JavaScript + * async function ensureLogin(context, state, botLogic) { + * const now = new Date().getTime(); + * if (state.token && now < (new Date(state.token.expiration).getTime() - 60000)) { + * return botLogic(context); + * } else { + * const loginPrompt = createOAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * const token = await state.loginActive ? loginPrompt.recognize(context) : loginPrompt.getUserToken(context); + * if (token) { + * state.loginActive = false; + * state.token = token; + * return botLogic(context); + * } else if (context.activity.type === 'message') { + * if (!state.loginActive) { + * state.loginActive = true; + * state.loginStart = now; + * await loginPrompt.prompt(context); + * } else if (now >= (state.loginStart + (5 * 60 * 1000))) { + * state.loginActive = false; + * await context.sendActivity(`We're having a problem logging you in. Please try again later.`); + * } + * } + * } + * } + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to an instance of `TokenResponse` but can be changed by the prompts custom validator. * @param settings Configuration settings for the OAuthPrompt. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. */ diff --git a/libraries/botbuilder-prompts/lib/oauthPrompt.js.map b/libraries/botbuilder-prompts/lib/oauthPrompt.js.map index 04551ea29c..2cf3a9e062 100644 --- a/libraries/botbuilder-prompts/lib/oauthPrompt.js.map +++ b/libraries/botbuilder-prompts/lib/oauthPrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"oauthPrompt.js","sourceRoot":"","sources":["../src/oauthPrompt.ts"],"names":[],"mappings":"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"} \ No newline at end of file +{"version":3,"file":"oauthPrompt.js","sourceRoot":"","sources":["../src/oauthPrompt.ts"],"names":[],"mappings":"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"} \ No newline at end of file diff --git a/libraries/botbuilder-prompts/lib/textPrompt.d.ts b/libraries/botbuilder-prompts/lib/textPrompt.d.ts index a70314a97d..a662b68705 100644 --- a/libraries/botbuilder-prompts/lib/textPrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/textPrompt.d.ts @@ -6,22 +6,56 @@ * Licensed under the MIT License. */ import { Promiseable, Activity, TurnContext } from 'botbuilder'; -/** Prompts the user to reply with some text. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to reply with some text. + * + * **Usage Example** + * + * ```JavaScript + * const { createTextPrompt } = require('botbuilder-prompts'); + * + * const agePrompt = createTextPrompt(); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to return a `string` but can be changed by the prompts custom validator. + */ export interface TextPrompt { /** * Sends a formated prompt to the user. + * + * **Usage Example** + * + * ```JavaScript + * await namePrompt.prompt(context, `What's name?`); + * ``` * @param context Context for the current turn of conversation. * @param prompt Text or activity to send as the prompt. * @param speak (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. */ prompt(context: TurnContext, prompt: string | Partial, speak?: string): Promise; /** - * Recognizes and validates the users reply. + * Recognizes and validates the users reply. The result of the call will either be the + * recognized value or `undefined`. + * + * The recognize() method will not automatically re-prompt the user so either the caller or the + * prompts custom validator will need to implement re-prompting logic. + * + * **Usage Example** + * + * ```JavaScript + * const name = await namePrompt.recognize(context); + * if (name) { + * // Save name and continue + * } + * ``` * @param context Context for the current turn of conversation. */ recognize(context: TurnContext): Promise; } /** + * :package: **botbuilder-prompts** + * * Signature of a handler that can be passed to a prompt to provide additional validation logic * or to customize the reply sent to the user when their response is invalid. * @param R Type of value that will recognized and passed to the validator as input. @@ -31,7 +65,24 @@ export interface TextPrompt { */ export declare type PromptValidator = (context: TurnContext, value: R | undefined) => Promiseable; /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to enter some text. + * + * **Usage Example** + * + * ```JavaScript + * const { createTextPrompt } = require('botbuilder-prompts'); + * + * const namePrompt = createTextPrompt(async (context, value) => { + * if (value && value.length >= 3) { + * return value; + * } + * await namePrompt.prompt(context, `Your entry must be at least 3 characters in length.`); + * return undefined; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to return a `string` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. */ export declare function createTextPrompt(validator?: PromptValidator): TextPrompt; diff --git a/libraries/botbuilder-prompts/lib/textPrompt.js b/libraries/botbuilder-prompts/lib/textPrompt.js index 1ddf00160e..bc20ec8877 100644 --- a/libraries/botbuilder-prompts/lib/textPrompt.js +++ b/libraries/botbuilder-prompts/lib/textPrompt.js @@ -2,7 +2,24 @@ Object.defineProperty(exports, "__esModule", { value: true }); const internal_1 = require("./internal"); /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to enter some text. + * + * **Usage Example** + * + * ```JavaScript + * const { createTextPrompt } = require('botbuilder-prompts'); + * + * const namePrompt = createTextPrompt(async (context, value) => { + * if (value && value.length >= 3) { + * return value; + * } + * await namePrompt.prompt(context, `Your entry must be at least 3 characters in length.`); + * return undefined; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to return a `string` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. */ function createTextPrompt(validator) { diff --git a/libraries/botbuilder-prompts/lib/textPrompt.js.map b/libraries/botbuilder-prompts/lib/textPrompt.js.map index 9cda8d6536..765afd58f2 100644 --- a/libraries/botbuilder-prompts/lib/textPrompt.js.map +++ b/libraries/botbuilder-prompts/lib/textPrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"textPrompt.js","sourceRoot":"","sources":["../src/textPrompt.ts"],"names":[],"mappings":";;AAQA,yCAAwC;AA6BxC;;;GAGG;AACH,0BAA6C,SAAsC;IAC/E,MAAM,CAAC;QACH,MAAM,EAAE,gBAAgB,OAAO,EAAE,MAAM,EAAE,KAAK;YAC1C,MAAM,CAAC,qBAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;QACD,SAAS,EAAE,mBAAmB,OAAO;YACjC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACrF,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAY,CAAC,CAAC;QACjF,CAAC;KACJ,CAAC;AACN,CAAC;AAVD,4CAUC"} \ No newline at end of file +{"version":3,"file":"textPrompt.js","sourceRoot":"","sources":["../src/textPrompt.ts"],"names":[],"mappings":";;AAQA,yCAAwC;AA+DxC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,0BAA6C,SAAsC;IAC/E,MAAM,CAAC;QACH,MAAM,EAAE,gBAAgB,OAAO,EAAE,MAAM,EAAE,KAAK;YAC1C,MAAM,CAAC,qBAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;QACD,SAAS,EAAE,mBAAmB,OAAO;YACjC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACrF,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAY,CAAC,CAAC;QACjF,CAAC;KACJ,CAAC;AACN,CAAC;AAVD,4CAUC"} \ No newline at end of file diff --git a/libraries/botbuilder-prompts/src/attachmentPrompt.ts b/libraries/botbuilder-prompts/src/attachmentPrompt.ts index 998e4383ab..48554c66ad 100644 --- a/libraries/botbuilder-prompts/src/attachmentPrompt.ts +++ b/libraries/botbuilder-prompts/src/attachmentPrompt.ts @@ -9,10 +9,29 @@ import { Promiseable, Activity, Attachment, TurnContext } from 'botbuilder'; import { PromptValidator } from './textPrompt'; import { sendPrompt } from './internal'; -/** Prompts the user to upload one or more attachments. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to upload one or more attachments. + * + * **Usage Example** + * + * ```JavaScript + * const { createAttachmentPrompt } = require('botbuilder-prompts'); + * + * const imagePrompt = createAttachmentPrompt(); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to an `attachment[]` but can be changed by the prompts custom validator. + */ export interface AttachmentPrompt { /** * Sends a formated prompt to the user. + * + * **Usage Example** + * + * ```JavaScript + * await imagePrompt.prompt(context, `Upload an image(s).`); + * ``` * @param context Context for the current turn of conversation. * @param prompt Text or activity to send as the prompt. * @param speak (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. @@ -20,14 +39,50 @@ export interface AttachmentPrompt { prompt(context: TurnContext, prompt: string|Partial, speak?: string): Promise; /** - * Recognizes and validates the users reply. + * Recognizes and validates the users reply. The result of the call will either be the + * recognized value or `undefined`. + * + * The recognize() method will not automatically re-prompt the user so either the caller or the + * prompts custom validator will need to implement re-prompting logic. + * + * **Usage Example** + * + * ```JavaScript + * const images = await imagePrompt.recognize(context); + * if (images) { + * // Process images + * } + * ``` * @param context Context for the current turn of conversation. */ recognize(context: TurnContext): Promise; } /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to upload one or more attachments. + * + * **Usage Example** + * + * ```JavaScript + * const { createAttachmentPrompt } = require('botbuilder-prompts'); + * + * const imagePrompt = createAttachmentPrompt(async (context, values) => { + * if (values && values.length > 0) { + * for (let i = 0; i < values.length; i++) { + * if (!values[i].contentType.startsWith('image')) { + * await imagePrompt.prompt(context, `Only images are accepted.`); + * return undefined; + * } + * } + * } else { + * await imagePrompt.prompt(context, `Please upload at least one image.`); + * } + * return values; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to an `attachment[]` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. */ export function createAttachmentPrompt(validator?: PromptValidator): AttachmentPrompt { diff --git a/libraries/botbuilder-prompts/src/choicePrompt.ts b/libraries/botbuilder-prompts/src/choicePrompt.ts index c6929afbc8..615d20bc34 100644 --- a/libraries/botbuilder-prompts/src/choicePrompt.ts +++ b/libraries/botbuilder-prompts/src/choicePrompt.ts @@ -11,6 +11,8 @@ import { PromptValidator } from './textPrompt'; import { sendPrompt } from './internal'; /** + * :package: **botbuilder-prompts** + * * Controls the way that choices for a `ChoicePrompt` or yes/no options for a `ConfirmPrompt` are * presented to a user. */ @@ -31,7 +33,20 @@ export enum ListStyle { suggestedAction } -/** Prompts the user to select from a list of choices. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to select from a list of choices. + * + * **Usage Example** + * + * ```JavaScript + * const { createChoicePrompt } = require('botbuilder-prompts'); + * + * const choicePrompt = createChoicePrompt(); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to an instance of `FoundChoice` but can be changed by the prompts custom validator. + */ export interface ChoicePrompt { /** * Style of choices sent to user when [prompt()](#prompt) is called. Defaults @@ -47,23 +62,69 @@ export interface ChoicePrompt { /** * Sends a formated prompt to the user. + * + * By default, this will attempt to send the provided list of choices as buttons using + * `ChoiceFactory.forChannel()`. It may fallback to sending the choices as a text based list + * for any number of reasons. You can set the prompts [style](#style) property to force the use + * of a particular rendering style. + * + * Further tweaks can be made to the rendering of choices using the + * [choiceOptions](#choiceoptions) property. + * + * **Usage Example** + * + * ```JavaScript + * await colorPrompt.prompt(context, ['red', 'green', 'blue'], `Pick a color.`); + * ``` * @param context Context for the current turn of conversation. - * @param choices Array of choices that should be prompted for. + * @param choices Array of choices that should be prompted for. This may be different then the choices passed to [recognize()](#recognize). * @param prompt (Optional) Text or activity to send as the prompt. * @param speak (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. */ prompt(context: TurnContext, choices: (string|Choice)[], prompt?: string|Partial, speak?: string): Promise; /** - * Recognizes and validates the users reply. + * Recognizes and validates the users reply. The result of the call will either be the + * recognized value or `undefined`. + * + * The recognize() method will not automatically re-prompt the user so either the caller or the + * prompts custom validator will need to implement re-prompting logic. + * + * The search options for the underlying choice recognizer can be tweaked using the prompts + * [recognizerOptions](#recognizeroptions) property. + * + * **Usage Example** + * + * ```JavaScript + * const choice = await colorPrompt.recognize(context, ['red', 'green', 'blue']); + * if (choice) { + * const color = choice.value; + * } + * ``` * @param context Context for the current turn of conversation. - * @param choices Array of choices that should be recognized against. + * @param choices Array of choices that should be recognized against. This may be different then the choices passed to [prompt()](#prompt). */ recognize(context: TurnContext, choices: (string|Choice)[]): Promise; } /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to select from a list of choices. + * + * **Usage Example** + * + * ```JavaScript + * const { createChoicePrompt } = require('botbuilder-prompts'); + * + * const colorPrompt = createChoicePrompt(async (context, found) => { + * if (!found) { + * await colorPrompt.prompt(context, ['red', 'green', 'blue'], `Please choose a color from the list or say "cancel".`); + * } + * return found; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to an instance of `FoundChoice` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. * @param defaultLocale (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. */ @@ -87,7 +148,7 @@ export function createChoicePrompt(validator?: PromptValidator< msg = ChoiceFactory.list(choices, prompt, speak, this.choiceOptions); break; case ListStyle.suggestedAction: - msg = ChoiceFactory.suggestedAction(choices, prompt, speak, this.choiceOptions); + msg = ChoiceFactory.suggestedAction(choices, prompt, speak); break; case ListStyle.none: msg = { type: 'message', text: prompt }; diff --git a/libraries/botbuilder-prompts/src/confirmPrompt.ts b/libraries/botbuilder-prompts/src/confirmPrompt.ts index 3116833bec..346bf1cb3d 100644 --- a/libraries/botbuilder-prompts/src/confirmPrompt.ts +++ b/libraries/botbuilder-prompts/src/confirmPrompt.ts @@ -12,40 +12,83 @@ import { sendPrompt } from './internal'; import { ListStyle } from './choicePrompt'; import * as Recognizers from '@microsoft/recognizers-text-choice'; -/** Map of `ConfirmPrompt` choices for each locale the bot supports. */ +/** + * :package: **botbuilder-prompts** + * + * Map of `ConfirmPrompt` choices for each locale the bot supports. + */ export interface ConfirmChoices { [locale:string]: (string|Choice)[]; } -/** Prompts the user to answer a yes/no question. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to answer a yes/no question. + * + * The [prompt()](#prompt) method will attempt to send a set of buttons yes/no buttons for the + * user to click. By default, the text of the titles for these buttons will always be in English + * but you can easily add support for other languages using the prompts [choices](#choices) + * property. + * + * **Usage Example** + * + * ```JavaScript + * const { createConfirmPrompt } = require('botbuilder-prompts'); + * + * const confirmPrompt = createConfirmPrompt(); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to a boolean `true` or `false` but can be changed by the prompts custom validator. + */ export interface ConfirmPrompt { /** * Allows for the localization of the confirm prompts yes/no choices to other locales besides * english. The key of each entry is the languages locale code and should be lower cased. A * default fallback set of choices can be specified using a key of '*'. * + * The default choices are configured to be `{ '*': ['yes', 'no'] }`. + * * **Example usage:** * * ```JavaScript + * const confirmPrompt = createConfirmPrompt(); + * // Configure yes/no choices for english and spanish (default) - * ConfirmPrompt.choices['*'] = ['sí', 'no']; - * ConfirmPrompt.choices['es'] = ['sí', 'no']; - * ConfirmPrompt.choices['en-us'] = ['yes', 'no']; + * confirmPrompt.choices['*'] = ['sí', 'no']; + * confirmPrompt.choices['es'] = ['sí', 'no']; + * confirmPrompt.choices['en-us'] = ['yes', 'no']; * ``` */ choices: ConfirmChoices; /** - * Style of choices sent to user when [prompt()](#prompt) is called. Defaults - * to `ListStyle.auto`. + * Style of choices sent to user when [prompt()](#prompt) is called. Defaults to + * `ListStyle.auto`. */ style: ListStyle; - /** Additional options used to configure the output of the choice factory. */ + /** + * Additional options used to configure the output of the `ChoiceFactory`. Defaults to + * `{ includeNumbers: false }`. + */ choiceOptions: ChoiceFactoryOptions; /** - * Sends a formated prompt to the user. + * Sends a formated prompt to the user. + * + * By default, this will attempt to send the user yes & no choices as buttons using + * `ChoiceFactory.forChannel()`. If the channel doesn't support buttons it will fallback to + * appending ` (yes or no)` to the prompt. You can override this behavior using the prompts + * [style](#style) property. + * + * Further tweaks can be made to the rendering of the yes/no choices using the + * [choiceOptions](#choiceoptions) property. + * + * **Usage Example** + * + * ```JavaScript + * await confirmPrompt.prompt(context, `This will cancel your order. Are you sure?`); + * ``` * @param context Context for the current turn of conversation. * @param prompt Text or activity to send as the prompt. * @param speak (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. @@ -53,16 +96,49 @@ export interface ConfirmPrompt { prompt(context: TurnContext, prompt: string|Partial, speak?: string): Promise; /** - * Recognizes and validates the users reply. + * Recognizes and validates the users reply. The result of the call will either be the + * recognized value or `undefined`. + * + * The recognize() method will not automatically re-prompt the user so either the caller or the + * prompts custom validator will need to implement re-prompting logic. + * + * **Usage Example** + * + * ```JavaScript + * const confirmed = await confirmPrompt.recognize(context); + * if (typeof confirmed == 'boolean') { + * if (confirmed) { + * // User said yes + * } else { + * // User said no + * } + * } + * ``` * @param context Context for the current turn of conversation. */ recognize(context: TurnContext): Promise; } /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to answer a yes/no question. + * + * **Usage Example** + * + * ```JavaScript + * const { createConfirmPrompt } = require('botbuilder-prompts'); + * + * const confirmPrompt = createConfirmPrompt(async (context, confirmed) => { + * if (typeof confirmed != 'boolean') { + * await confirmPrompt.prompt(context, `Please answer "yes" or "no".`); + * } + * return confirmed; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to a boolean `true` or `false` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. - * @param defaultLocale (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. + * @param defaultLocale (Optional) locale to use if `context.activity.locale` is not specified. Defaults to a value of `en-us`. */ export function createConfirmPrompt(validator?: PromptValidator, defaultLocale?: string): ConfirmPrompt { return { @@ -89,7 +165,7 @@ export function createConfirmPrompt(validator?: PromptValidator, msg = ChoiceFactory.list(choices, prompt, speak, this.choiceOptions); break; case ListStyle.suggestedAction: - msg = ChoiceFactory.suggestedAction(choices, prompt, speak, this.choiceOptions); + msg = ChoiceFactory.suggestedAction(choices, prompt, speak); break; case ListStyle.none: msg = { type: 'message', text: prompt }; diff --git a/libraries/botbuilder-prompts/src/datetimePrompt.ts b/libraries/botbuilder-prompts/src/datetimePrompt.ts index fe6910a864..0ea4ca26c3 100644 --- a/libraries/botbuilder-prompts/src/datetimePrompt.ts +++ b/libraries/botbuilder-prompts/src/datetimePrompt.ts @@ -11,6 +11,8 @@ import { sendPrompt } from './internal'; import * as Recognizers from '@microsoft/recognizers-text-date-time'; /** + * :package: **botbuilder-prompts** + * * Datetime result returned by `DatetimePrompt`. For more details see the LUIS docs for * [builtin.datetimev2](https://docs.microsoft.com/en-us/azure/cognitive-services/luis/luis-reference-prebuilt-entities#builtindatetimev2). */ @@ -33,10 +35,30 @@ export interface FoundDatetime { value: string; } -/** Prompts the user to reply with a date or time. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to reply with a date and/or time. The user can use natural language utterances + * like "tomorrow at 9am". + * + * **Usage Example** + * + * ```JavaScript + * const { createDatetimePrompt } = require('botbuilder-prompts'); + * + * const timePrompt = createDatetimePrompt(); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to an instance of `FoundDateTime[]` but can be changed by the prompts custom validator. + */ export interface DatetimePrompt { /** * Sends a formated prompt to the user. + * + * **Usage Example** + * + * ```JavaScript + * await timePrompt.prompt(context, `What time should I set your alarm for?`); + * ``` * @param context Context for the current turn of conversation. * @param prompt Text or activity to send as the prompt. * @param speak (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. @@ -44,14 +66,56 @@ export interface DatetimePrompt { prompt(context: TurnContext, prompt: string|Partial, speak?: string): Promise; /** - * Recognizes and validates the users reply. + * Recognizes and validates the users reply. The result of the call will either be the + * recognized value or `undefined`. + * + * The recognize() method will not automatically re-prompt the user so either the caller or the + * prompts custom validator will need to implement re-prompting logic. + * + * **Usage Example** + * + * ```JavaScript + * const values = await timePrompt.recognize(context); + * if (values && values.length > 0) { + * const time = values[0]; + * switch (time.type) { + * case 'date': + * case 'time': + * case 'datetime': + * const date = new Date(time.value); + * break; + * } + * } + * ``` * @param context Context for the current turn of conversation. */ recognize(context: TurnContext): Promise; } /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to reply with a date or time. + * + * **Usage Example** + * + * ```JavaScript + * const { createDatetimePrompt } = require('botbuilder-prompts'); + * + * const timePrompt = createDatetimePrompt(async (context, values) => { + * try { + * if (!Array.isArray(values) || values.length < 0) { throw new Error('missing time') } + * if (values[0].type !== 'datetime') { throw new Error('unsupported type') } + * const value = new Date(values[0].value); + * if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } + * return value; + * } catch (err) { + * await context.sendActivity(`Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); + * return undefined; + * } + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to an instance of `FoundDateTime` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. * @param defaultLocale (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-prompts/src/numberPrompt.ts b/libraries/botbuilder-prompts/src/numberPrompt.ts index 00903fc8c7..af7ec6a949 100644 --- a/libraries/botbuilder-prompts/src/numberPrompt.ts +++ b/libraries/botbuilder-prompts/src/numberPrompt.ts @@ -10,10 +10,29 @@ import { PromptValidator } from './textPrompt'; import { sendPrompt } from './internal'; import * as Recognizers from '@microsoft/recognizers-text-number'; -/** Prompts the user to reply with a number. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to reply with a number. + * + * **Usage Example** + * + * ```JavaScript + * const { createNumberPrompt } = require('botbuilder-prompts'); + * + * const agePrompt = createNumberPrompt(); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to `number` but can be changed by the prompts custom validator. + */ export interface NumberPrompt { /** - * Sends a formated prompt to the user. + * Sends a formated prompt to the user. + * + * **Usage Example** + * + * ```JavaScript + * await agePrompt.prompt(context, `How old are you?`); + * ``` * @param context Context for the current turn of conversation. * @param prompt Text or activity to send as the prompt. * @param speak (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. @@ -21,14 +40,47 @@ export interface NumberPrompt { prompt(context: TurnContext, prompt: string|Partial, speak?: string): Promise; /** - * Recognizes and validates the users reply. + * Recognizes and validates the users reply. The result of the call will either be the + * recognized value or `undefined`. + * + * The recognize() method will not automatically re-prompt the user so either the caller or the + * prompts custom validator will need to implement re-prompting logic. + * + * **Usage Example** + * + * ```JavaScript + * const age = await agePrompt.recognize(context); + * if (typeof age == 'number') { + * // Save age and continue + * } + * ``` * @param context Context for the current turn of conversation. */ recognize(context: TurnContext): Promise; } /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to reply with a number. + * + * **Usage Example** + * + * ```JavaScript + * const { createNumberPrompt } = require('botbuilder-prompts'); + * + * const agePrompt = createNumberPrompt(async (context, value) => { + * if (typeof value == 'number') { + * if (value >= 1 && value < 111) { + * // Return age rounded down to nearest whole number. + * return Math.floor(value); + * } + * } + * await agePrompt.prompt(context, `Please enter a number between 1 and 110 or say "cancel".`); + * return undefined; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to `number` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. * @param defaultLocale (Optional) locale to use if `context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-prompts/src/oauthPrompt.ts b/libraries/botbuilder-prompts/src/oauthPrompt.ts index e7096565ef..8cbfcbd938 100644 --- a/libraries/botbuilder-prompts/src/oauthPrompt.ts +++ b/libraries/botbuilder-prompts/src/oauthPrompt.ts @@ -9,7 +9,11 @@ import { Promiseable, Activity, TurnContext, Attachment, TokenResponse, BotFrame import { PromptValidator } from './textPrompt'; import { sendPrompt } from './internal'; -/** Defines settings for an OAuthPrompt. */ +/** + * :package: **botbuilder-prompts** + * + * Defines settings for an OAuthPrompt. + */ export interface OAuthPromptSettings { /** Name of the OAuth connection being used. */ connectionName: string; @@ -21,37 +25,139 @@ export interface OAuthPromptSettings { text?: string; } -/** Prompts the user to sign in using the Bot Frameworks Single Sign On (SSO) service. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to sign in using the Bot Frameworks Single Sign On (SSO) service. + * + * **Usage Example** + * + * ```JavaScript + * const { createOAuthPrompt } = require('botbuilder-prompts'); + * + * const loginPrompt = createOAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to an instance of `TokenResponse` but can be changed by the prompts custom validator. + */ export interface OAuthPrompt { /** * Sends a formated prompt to the user. + * + * An `OAuthCard` will be automatically created and sent to the user requesting them to + * signin. If you need to localize the card or customize the message sent to the user for any + * reason you can pass in the `Activity` to send. This should just be an activity of type + * `message` and contain at least one attachment that's an `OAuthCard`. + * + * **Usage Example** + * + * ```JavaScript + * await loginPrompt.prompt(context); + * ``` * @param context Context for the current turn of conversation. * @param prompt (Optional) activity to send along the user. This should include an attachment containing an `OAuthCard`. If ommited, an activity will be automatically generated. */ prompt(context: TurnContext, prompt?: Partial): Promise; /** - * Recognizes and validates replies to a call to [prompt()](#prompt). + * Attempts to resolve the token after [prompt()](#prompt) has been called. There are two core + * flows that need to be supported to complete a users signin: + * + * - The automatic signin flow where the SSO service will forward the bot the users access + * token using either an `event` or `invoke` activity. + * - The "magic code" flow where a user is prompted by the SSO service to send the bot a six + * digit code confirming their identity. This code will be sent as a standard `message` activity. + * + * The `recognize()` method automatically handles both flows for the bot but you should ensure + * that you don't accidentally filter out the `event` and `invoke` activities before calling + * recognize(). Because of this we generally recommend you put the call to recognize() towards + * the beginning of your bot logic. + * + * You should also be prepared for the case where the user fails to enter the correct + * "magic code" or simply decides they don't want to click the signin button. + * + * **Usage Example** + * + * ```JavaScript + * const token = await loginPrompt.recognize(context); + * if (token) { + * // Save token and continue. + * } + * ``` * @param context Context for the current turn of conversation. * @param connectionName Name of the auth connection to use. */ recognize(context: TurnContext): Promise; /** - * Attempts to retrieve the cached token for a signed in user. + * Attempts to retrieve the cached token for a signed in user. You will generally want to call + * this before calling [prompt()](#prompt) to send the user a signin card. + * + * **Usage Example** + * + * ```JavaScript + * const token = await loginPrompt.getUserToken(context); + * if (!token) { + * await loginPrompt.prompt(context); + * } + * ``` * @param context Context for the current turn of conversation. */ getUserToken(context: TurnContext): Promise; /** * Signs the user out of the service. + * + * **Usage Example** + * + * ```JavaScript + * await loginPrompt.signOutUser(context); + * ``` * @param context Context for the current turn of conversation. */ signOutUser(context: TurnContext): Promise; } + /** - * Creates a new prompt that asks the user to enter some text. + * :package: **botbuilder-prompts** + * + * Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) + * service. + * + * **Usage Example** + * + * ```JavaScript + * async function ensureLogin(context, state, botLogic) { + * const now = new Date().getTime(); + * if (state.token && now < (new Date(state.token.expiration).getTime() - 60000)) { + * return botLogic(context); + * } else { + * const loginPrompt = createOAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * const token = await state.loginActive ? loginPrompt.recognize(context) : loginPrompt.getUserToken(context); + * if (token) { + * state.loginActive = false; + * state.token = token; + * return botLogic(context); + * } else if (context.activity.type === 'message') { + * if (!state.loginActive) { + * state.loginActive = true; + * state.loginStart = now; + * await loginPrompt.prompt(context); + * } else if (now >= (state.loginStart + (5 * 60 * 1000))) { + * state.loginActive = false; + * await context.sendActivity(`We're having a problem logging you in. Please try again later.`); + * } + * } + * } + * } + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to an instance of `TokenResponse` but can be changed by the prompts custom validator. * @param settings Configuration settings for the OAuthPrompt. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. */ diff --git a/libraries/botbuilder-prompts/src/textPrompt.ts b/libraries/botbuilder-prompts/src/textPrompt.ts index 4ff84fbc8d..f14f6cc762 100644 --- a/libraries/botbuilder-prompts/src/textPrompt.ts +++ b/libraries/botbuilder-prompts/src/textPrompt.ts @@ -8,10 +8,29 @@ import { Promiseable, Activity, TurnContext } from 'botbuilder'; import { sendPrompt } from './internal'; -/** Prompts the user to reply with some text. */ +/** + * :package: **botbuilder-prompts** + * + * Prompts the user to reply with some text. + * + * **Usage Example** + * + * ```JavaScript + * const { createTextPrompt } = require('botbuilder-prompts'); + * + * const agePrompt = createTextPrompt(); + * ``` + * @param O (Optional) type of result returned by the [recognize()](#recognize) method. This defaults to return a `string` but can be changed by the prompts custom validator. + */ export interface TextPrompt { /** * Sends a formated prompt to the user. + * + * **Usage Example** + * + * ```JavaScript + * await namePrompt.prompt(context, `What's name?`); + * ``` * @param context Context for the current turn of conversation. * @param prompt Text or activity to send as the prompt. * @param speak (Optional) SSML that should be spoken for prompt. The prompts `inputHint` will be automatically set to `expectingInput`. @@ -19,13 +38,28 @@ export interface TextPrompt { prompt(context: TurnContext, prompt: string|Partial, speak?: string): Promise; /** - * Recognizes and validates the users reply. + * Recognizes and validates the users reply. The result of the call will either be the + * recognized value or `undefined`. + * + * The recognize() method will not automatically re-prompt the user so either the caller or the + * prompts custom validator will need to implement re-prompting logic. + * + * **Usage Example** + * + * ```JavaScript + * const name = await namePrompt.recognize(context); + * if (name) { + * // Save name and continue + * } + * ``` * @param context Context for the current turn of conversation. */ recognize(context: TurnContext): Promise; } /** + * :package: **botbuilder-prompts** + * * Signature of a handler that can be passed to a prompt to provide additional validation logic * or to customize the reply sent to the user when their response is invalid. * @param R Type of value that will recognized and passed to the validator as input. @@ -36,7 +70,24 @@ export interface TextPrompt { export type PromptValidator = (context: TurnContext, value: R|undefined) => Promiseable; /** + * :package: **botbuilder-prompts** + * * Creates a new prompt that asks the user to enter some text. + * + * **Usage Example** + * + * ```JavaScript + * const { createTextPrompt } = require('botbuilder-prompts'); + * + * const namePrompt = createTextPrompt(async (context, value) => { + * if (value && value.length >= 3) { + * return value; + * } + * await namePrompt.prompt(context, `Your entry must be at least 3 characters in length.`); + * return undefined; + * }); + * ``` + * @param O (Optional) type of result returned by the `recognize()` method. This defaults to return a `string` but can be changed by the prompts custom validator. * @param validator (Optional) validator for providing additional validation logic or customizing the prompt sent to the user when invalid. */ export function createTextPrompt(validator?: PromptValidator): TextPrompt { From ce7c4b3c4429e7c4ac9a5820ee593e8d0bb78ec8 Mon Sep 17 00:00:00 2001 From: Steven Ickman Date: Wed, 25 Apr 2018 12:49:10 -0700 Subject: [PATCH 3/5] updated docs for dialogs and prompts --- doc/botbuilder-dialogs/README.md | 56 +-- .../botbuilder_dialogs.attachmentprompt.md | 144 +++++-- .../botbuilder_dialogs.choiceprompt.md | 135 +++++-- .../botbuilder_dialogs.compositecontrol.md | 159 ++++++-- .../botbuilder_dialogs.confirmprompt.md | 164 +++++--- .../classes/botbuilder_dialogs.control.md | 66 +++- .../botbuilder_dialogs.datetimeprompt.md | 146 ++++--- .../botbuilder_dialogs.dialogcontext.md | 72 ++-- .../classes/botbuilder_dialogs.dialogset.md | 89 +++-- .../botbuilder_dialogs.numberprompt.md | 149 ++++--- .../classes/botbuilder_dialogs.oauthprompt.md | 371 ++++++++++++++++++ .../classes/botbuilder_dialogs.prompt.md | 76 ++-- .../classes/botbuilder_dialogs.textprompt.md | 137 +++++-- .../classes/botbuilder_dialogs.waterfall.md | 12 +- .../botbuilder_dialogs.choicepromptoptions.md | 12 +- .../interfaces/botbuilder_dialogs.dialog.md | 14 +- .../botbuilder_dialogs.dialoginstance.md | 7 +- .../botbuilder_dialogs.dialogresult.md | 10 +- ..._dialogs.oauthpromptsettingswithtimeout.md | 44 +++ .../botbuilder_dialogs.promptoptions.md | 10 +- doc/botbuilder-prompts/README.md | 32 +- .../enums/botbuilder_prompts.liststyle.md | 10 +- .../botbuilder_prompts.attachmentprompt.md | 10 +- .../botbuilder_prompts.choiceprompt.md | 16 +- .../botbuilder_prompts.confirmprompt.md | 16 +- .../botbuilder_prompts.datetimeprompt.md | 10 +- .../botbuilder_prompts.founddatetime.md | 6 +- .../botbuilder_prompts.numberprompt.md | 10 +- .../botbuilder_prompts.oauthprompt.md | 18 +- .../botbuilder_prompts.oauthpromptsettings.md | 6 +- .../botbuilder_prompts.textprompt.md | 12 +- .../lib/compositeControl.d.ts | 158 +++++++- .../lib/compositeControl.js | 144 ++++++- .../lib/compositeControl.js.map | 2 +- libraries/botbuilder-dialogs/lib/control.d.ts | 50 ++- libraries/botbuilder-dialogs/lib/control.js | 48 ++- .../botbuilder-dialogs/lib/control.js.map | 2 +- libraries/botbuilder-dialogs/lib/dialog.d.ts | 4 + .../botbuilder-dialogs/lib/dialogContext.d.ts | 8 + .../botbuilder-dialogs/lib/dialogContext.js | 6 + .../lib/dialogContext.js.map | 2 +- .../botbuilder-dialogs/lib/dialogSet.d.ts | 107 +++-- libraries/botbuilder-dialogs/lib/dialogSet.js | 100 ++++- .../botbuilder-dialogs/lib/dialogSet.js.map | 2 +- .../lib/prompts/attachmentPrompt.d.ts | 87 +++- .../lib/prompts/attachmentPrompt.js | 87 +++- .../lib/prompts/attachmentPrompt.js.map | 2 +- .../lib/prompts/choicePrompt.d.ts | 82 +++- .../lib/prompts/choicePrompt.js | 76 +++- .../lib/prompts/choicePrompt.js.map | 2 +- .../lib/prompts/confirmPrompt.d.ts | 104 +++-- .../lib/prompts/confirmPrompt.js | 104 +++-- .../lib/prompts/confirmPrompt.js.map | 2 +- .../lib/prompts/datetimePrompt.d.ts | 85 ++-- .../lib/prompts/datetimePrompt.js | 85 ++-- .../lib/prompts/datetimePrompt.js.map | 2 +- .../lib/prompts/numberPrompt.d.ts | 90 ++++- .../lib/prompts/numberPrompt.js | 90 ++++- .../lib/prompts/numberPrompt.js.map | 2 +- .../lib/prompts/oauthPrompt.d.ts | 123 ++++++ .../lib/prompts/oauthPrompt.js | 117 ++++++ .../lib/prompts/oauthPrompt.js.map | 2 +- .../lib/prompts/prompt.d.ts | 12 +- .../botbuilder-dialogs/lib/prompts/prompt.js | 6 + .../lib/prompts/prompt.js.map | 2 +- .../lib/prompts/textPrompt.d.ts | 79 +++- .../lib/prompts/textPrompt.js | 79 +++- .../lib/prompts/textPrompt.js.map | 2 +- .../botbuilder-dialogs/lib/waterfall.d.ts | 6 + libraries/botbuilder-dialogs/lib/waterfall.js | 2 + .../botbuilder-dialogs/lib/waterfall.js.map | 2 +- .../src/compositeControl.ts | 156 +++++++- libraries/botbuilder-dialogs/src/control.ts | 50 ++- libraries/botbuilder-dialogs/src/dialog.ts | 6 +- .../botbuilder-dialogs/src/dialogContext.ts | 8 + libraries/botbuilder-dialogs/src/dialogSet.ts | 109 +++-- .../src/prompts/attachmentPrompt.ts | 87 +++- .../src/prompts/choicePrompt.ts | 82 +++- .../src/prompts/confirmPrompt.ts | 106 +++-- .../src/prompts/datetimePrompt.ts | 85 ++-- .../src/prompts/numberPrompt.ts | 92 +++-- .../src/prompts/oauthPrompt.ts | 133 ++++++- .../botbuilder-dialogs/src/prompts/prompt.ts | 12 +- .../src/prompts/textPrompt.ts | 79 +++- libraries/botbuilder-dialogs/src/waterfall.ts | 6 + .../lib/attachmentPrompt.d.ts | 8 +- .../lib/attachmentPrompt.js | 2 +- .../botbuilder-prompts/lib/choicePrompt.d.ts | 8 +- .../botbuilder-prompts/lib/choicePrompt.js | 2 +- .../botbuilder-prompts/lib/confirmPrompt.d.ts | 10 +- .../botbuilder-prompts/lib/confirmPrompt.js | 2 +- .../lib/datetimePrompt.d.ts | 10 +- .../botbuilder-prompts/lib/datetimePrompt.js | 4 +- .../botbuilder-prompts/lib/numberPrompt.d.ts | 8 +- .../botbuilder-prompts/lib/numberPrompt.js | 2 +- .../botbuilder-prompts/lib/oauthPrompt.d.ts | 12 +- .../botbuilder-prompts/lib/oauthPrompt.js | 2 +- .../botbuilder-prompts/lib/textPrompt.d.ts | 10 +- .../botbuilder-prompts/lib/textPrompt.js | 2 +- .../src/attachmentPrompt.ts | 8 +- .../botbuilder-prompts/src/choicePrompt.ts | 8 +- .../botbuilder-prompts/src/confirmPrompt.ts | 10 +- .../botbuilder-prompts/src/datetimePrompt.ts | 10 +- .../botbuilder-prompts/src/numberPrompt.ts | 8 +- .../botbuilder-prompts/src/oauthPrompt.ts | 12 +- .../botbuilder-prompts/src/textPrompt.ts | 10 +- 106 files changed, 4058 insertions(+), 1085 deletions(-) create mode 100644 doc/botbuilder-dialogs/classes/botbuilder_dialogs.oauthprompt.md create mode 100644 doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md diff --git a/doc/botbuilder-dialogs/README.md b/doc/botbuilder-dialogs/README.md index e1cd4d352e..dd1b8564c6 100644 --- a/doc/botbuilder-dialogs/README.md +++ b/doc/botbuilder-dialogs/README.md @@ -17,6 +17,7 @@ * [DialogContext](classes/botbuilder_dialogs.dialogcontext.md) * [DialogSet](classes/botbuilder_dialogs.dialogset.md) * [NumberPrompt](classes/botbuilder_dialogs.numberprompt.md) +* [OAuthPrompt](classes/botbuilder_dialogs.oauthprompt.md) * [Prompt](classes/botbuilder_dialogs.prompt.md) * [TextPrompt](classes/botbuilder_dialogs.textprompt.md) * [Waterfall](classes/botbuilder_dialogs.waterfall.md) @@ -28,12 +29,12 @@ * [Dialog](interfaces/botbuilder_dialogs.dialog.md) * [DialogInstance](interfaces/botbuilder_dialogs.dialoginstance.md) * [DialogResult](interfaces/botbuilder_dialogs.dialogresult.md) +* [OAuthPromptSettingsWithTimeout](interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md) * [PromptOptions](interfaces/botbuilder_dialogs.promptoptions.md) ### Type aliases -* [PromptValidator](#promptvalidator) * [SkipStepFunction](#skipstepfunction) * [WaterfallStep](#waterfallstep) @@ -41,61 +42,18 @@ --- ## Type aliases - - -### PromptValidator - -**Τ PromptValidator**: *`function`* - -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:33](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L33)* - - - -Signature of a function that can be passed in to the constructor of all prompts. This function will be called every time the user replies to a prompt and can be used to add additional validation logic to a prompt or to customize the reply sent when the user send a reply that isn't recognized. -*__param__*: Type of dialog context object passed to validator. - -*__param__*: Type of value that will recognized and passed to the validator as input. - -*__param__*: Type of output that will be returned by the validator. This can be changed from the input type by the validator. - -*__param__*: Dialog context for the current turn of conversation with the user. - - -#### Type declaration -►(dc: *[DialogContext](classes/botbuilder_dialogs.dialogcontext.md)`C`*, value: *`R`⎮`undefined`*): `Promiseable`.<`any`> - - - -**Parameters:** - -| Param | Type | Description | -| ------ | ------ | ------ | -| dc | [DialogContext](classes/botbuilder_dialogs.dialogcontext.md)`C` | - | -| value | `R`⎮`undefined` | The value that was recognized or wasn't recognized. Depending on the prompt this can be either undefined or an empty array to indicate an unrecognized value. | - - - - - -**Returns:** `Promiseable`.<`any`> - - - - - - -___ - ### SkipStepFunction **Τ SkipStepFunction**: *`function`* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L55)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:59](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L59)* +:package: **botbuilder-dialogs** + When called, control will skip to the next waterfall step. #### Type declaration @@ -128,9 +86,11 @@ ___ **Τ WaterfallStep**: *`function`* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:50](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L50)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L52)* + +:package: **botbuilder-dialogs** Function signature of a waterfall step. diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.attachmentprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.attachmentprompt.md index 4cdb8bc2ec..a37c0c6b6d 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.attachmentprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.attachmentprompt.md @@ -5,9 +5,15 @@ # Class: AttachmentPrompt +:package: **botbuilder-dialogs** + Prompts a user to upload attachments like images. By default the prompt will return to the calling dialog a `Attachment[]` but this can be overridden using a custom `PromptValidator`. -**Example usage:** +The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a control if your bot is using some other conversation management system. + +### Dialog Usage + +When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to upload one or more attachments which will be passed as an argument to the callers next waterfall step: const { DialogSet, AttachmentPrompt } = require('botbuilder-dialogs'); @@ -16,23 +22,71 @@ Prompts a user to upload attachments like images. By default the prompt will ret dialogs.add('attachmentPrompt', new AttachmentPrompt()); dialogs.add('uploadImage', [ - function (dc) { + async function (dc) { return dc.prompt('attachmentPrompt', `Send me image(s)`); }, - function (dc, attachments) { - dc.batch.reply(`Processing ${attachments.length} images.`); + async function (dc, attachments) { + await dc.context.sendActivity(`Processing ${attachments.length} images.`); return dc.end(); } ]); +If the users response to the prompt fails to be recognized they will be automatically re-prompted to try again. By default the original prompt is re-sent to the user but you can provide an alternate prompt to send by passing in additional options: + + return dc.prompt('attachmentPrompt', `Send me image(s)`, { retryPrompt: `I didn't get anything. Send me an image.` }); + +The prompts retry logic can also be completely customized by passing the prompts constructor a custom validator: + + dialogs.add('imagePrompt', new AttachmentPrompt(async (context, values) => { + if (values && values.length > 0) { + for (let i = 0; i < values.length; i++) { + if (!values[i].contentType.startsWith('image')) { + await context.sendActivity(`Only images are accepted.`); + return undefined; + } + } + } else { + await context.sendActivity(`Please upload at least one image.`); + } + return values; + })); + +### Control Usage + +If your bot isn't dialog based you can still use the prompt on its own as a control. You will just need start the prompt from somewhere within your bots logic by calling the prompts `begin()` method: + + const state = {}; + const prompt = new AttachmentPrompt(); + await prompt.begin(context, state, { + prompt: `Send me image(s)`, + retryPrompt: `I didn't get anything. Send me an image.` + }); + +The prompt will populate the `state` object you passed in with information it needs to process the users response. You should save this off to your bots conversation state as you'll need to pass it to the prompts `continue()` method on the next turn of conversation with the user: + + const prompt = new AttachmentPrompt(); + const result = await prompt.continue(context, state); + if (!result.active) { + const attachments = result.result; + } + +The `continue()` method returns a `DialogResult` object which can be used to determine when the prompt is finished and then to access the results of the prompt. To interrupt or cancel the prompt simply delete the `state` object your bot is persisting. + ## Type parameters -#### C : `BotContext` +#### C : `TurnContext` + +The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + +#### O + +(Optional) output type returned by prompt. This defaults to an `Attachment[]` but can be changed by a custom validator passed to the prompt. + +#### R #### O -#### C : `BotContext` ## Hierarchy -↳ [Prompt](botbuilder_dialogs.prompt.md)`C`, `Attachment`[] +↳ [Prompt](botbuilder_dialogs.prompt.md)`C` **↳ AttachmentPrompt** @@ -74,34 +128,23 @@ Prompts a user to upload attachments like images. By default the prompt will ret -### ⊕ **new AttachmentPrompt**(validator?: *[PromptValidator](../#promptvalidator)`C`, `Attachment`[]*): [AttachmentPrompt](botbuilder_dialogs.attachmentprompt.md) +### ⊕ **new AttachmentPrompt**(validator?: *`PromptValidator`.<`Attachment`[]>,.<`O`>*): [AttachmentPrompt](botbuilder_dialogs.attachmentprompt.md) *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L36)* - +*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:107](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L107)* -Creates a new instance of the prompt. -**Example usage:** - - dialogs.add('imagePrompt', new AttachmentPrompt((dc, values) => { - if (!Array.isArray(values) || values.length < 1) { - dc.batch.reply(`Send me an image or say "cancel".`); - return undefined; - } else { - return values; - } - })); +Creates a new `AttachmentPrompt` instance. **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| validator | [PromptValidator](../#promptvalidator)`C`, `Attachment`[] | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | +| validator | `PromptValidator`.<`Attachment`[]>,.<`O`> | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | @@ -121,7 +164,7 @@ Creates a new instance of the prompt. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L15)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -135,29 +178,40 @@ ___ ### begin -► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* + +Starts the control. Depending on the control, its possible for the control to finish immediately so it's advised to check the result object returned by `begin()` and ensure that the control is still active before continuing. + +**Usage Example:** + + const state = {}; + const result = await control.begin(context, state); + if (!result.active) { + const value = result.result; + } + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | -| options | `O` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. | +| options | `O` | (Optional) additional options supported by the control. | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -169,28 +223,38 @@ ___ ### continue -► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:22](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L22)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* + + + +Passes a users reply to the control for further processing. The bot should keep calling `continue()` for future turns until the control returns a result with `Active == false`. To cancel or interrupt the prompt simply delete the `state` object being persisted. + +**Usage Example:** + const result = await control.continue(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that was previously initialized by a call to [begin()](#begin). | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -210,7 +274,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -245,7 +309,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L40)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -277,7 +341,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L55)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:113](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L113)* @@ -305,13 +369,13 @@ ___ ### «Protected» onRecognize -► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`Attachment`[]⎮`undefined`> +► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`O`⎮`undefined`> *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:56](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L56)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:114](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L114)* @@ -326,7 +390,7 @@ ___ -**Returns:** `Promise`.<`Attachment`[]⎮`undefined`> +**Returns:** `Promise`.<`O`⎮`undefined`> diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.choiceprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.choiceprompt.md index 3fca4ce8d6..3fe89b510d 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.choiceprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.choiceprompt.md @@ -5,9 +5,15 @@ # Class: ChoicePrompt +:package: **botbuilder-dialogs** + Prompts a user to confirm something with a yes/no response. By default the prompt will return to the calling dialog a `boolean` representing the users selection. -**Example usage:** +The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a control if your bot is using some other conversation management system. + +### Dialog Usage + +When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to select a choice from a list and their choice will be passed as an argument to the callers next waterfall step: const { DialogSet, ChoicePrompt } = require('botbuilder-dialogs'); @@ -15,24 +21,58 @@ Prompts a user to confirm something with a yes/no response. By default the promp dialogs.add('choicePrompt', new ChoicePrompt()); - dialogs.add('choiceDemo', [ - function (dc) { - return dc.prompt('choicePrompt', `choice: select a color`, ['red', 'green', 'blue']); + dialogs.add('colorPrompt', [ + async function (dc) { + return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue']); }, - function (dc, choice) { - dc.batch.reply(`Recognized choice: ${JSON.stringify(choice)}`); + async function (dc, choice) { + const color = choice.value; + await dc.context.sendActivity(`I like ${color} too!`); return dc.end(); } ]); +If the users response to the prompt fails to be recognized they will be automatically re-prompted to try again. By default the original prompt is re-sent to the user but you can provide an alternate prompt to send by passing in additional options: + + return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue'], { retryPrompt: `I didn't catch that. Select a color from the list.` }); + +### Control Usage + +If your bot isn't dialog based you can still use the prompt on its own as a control. You will just need start the prompt from somewhere within your bots logic by calling the prompts `begin()` method: + + const state = {}; + const prompt = new ChoicePrompt(); + await prompt.begin(context, state, { + choices: ['red', 'green', 'blue'], + prompt: `Select a color`, + retryPrompt: `I didn't catch that. Select a color from the list.` + }); + +The prompt will populate the `state` object you passed in with information it needs to process the users response. You should save this off to your bots conversation state as you'll need to pass it to the prompts `continue()` method on the next turn of conversation with the user: + + const prompt = new ChoicePrompt(); + const result = await prompt.continue(context, state); + if (!result.active) { + const color = result.result; + } + +The `continue()` method returns a `DialogResult` object which can be used to determine when the prompt is finished and then to access the results of the prompt. To interrupt or cancel the prompt simply delete the `state` object your bot is persisting. + ## Type parameters -#### C : `BotContext` +#### C : `TurnContext` + +The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + +#### O + +(Optional) output type returned by prompt. This defaults to an instance of `FoundChoice` but can be changed by a custom validator passed to the prompt. + +#### R #### O -#### C : `BotContext` ## Hierarchy -↳ [Prompt](botbuilder_dialogs.prompt.md)`C`, `prompts.FoundChoice` +↳ [Prompt](botbuilder_dialogs.prompt.md)`C` **↳ ChoicePrompt** @@ -77,28 +117,24 @@ Prompts a user to confirm something with a yes/no response. By default the promp -### ⊕ **new ChoicePrompt**(validator?: *[PromptValidator](../#promptvalidator)`C`, `prompts.FoundChoice`*, defaultLocale?: *`string`*): [ChoicePrompt](botbuilder_dialogs.choiceprompt.md) +### ⊕ **new ChoicePrompt**(validator?: *`PromptValidator`.<`prompts.FoundChoice`>,.<`O`>*, defaultLocale?: *`string`*): [ChoicePrompt](botbuilder_dialogs.choiceprompt.md) *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:42](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L42)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L100)* -Creates a new instance of the prompt. - -**Example usage:** - - dialogs.add('choicePrompt', new ChoicePrompt()); +Creates a new `ChoicePrompt` instance. **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| validator | [PromptValidator](../#promptvalidator)`C`, `prompts.FoundChoice` | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | -| defaultLocale | `string` | (Optional) locale to use if `dc.context.request.locale` not specified. Defaults to a value of `en-us`. | +| validator | `PromptValidator`.<`prompts.FoundChoice`>,.<`O`> | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | +| defaultLocale | `string` | (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. | @@ -118,7 +154,7 @@ Creates a new instance of the prompt. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L15)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -132,29 +168,40 @@ ___ ### begin -► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* + + +Starts the control. Depending on the control, its possible for the control to finish immediately so it's advised to check the result object returned by `begin()` and ensure that the control is still active before continuing. + +**Usage Example:** + + const state = {}; + const result = await control.begin(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | -| options | `O` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. | +| options | `O` | (Optional) additional options supported by the control. | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -170,7 +217,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:60](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L60)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:112](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L112)* @@ -199,28 +246,38 @@ ___ ### continue -► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:22](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L22)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* + + + +Passes a users reply to the control for further processing. The bot should keep calling `continue()` for future turns until the control returns a result with `Active == false`. To cancel or interrupt the prompt simply delete the `state` object being persisted. + +**Usage Example:** + const result = await control.continue(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that was previously initialized by a call to [begin()](#begin). | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -240,7 +297,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -275,7 +332,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L40)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -307,7 +364,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:71](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L71)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:123](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L123)* @@ -335,13 +392,13 @@ ___ ### «Protected» onRecognize -► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[ChoicePromptOptions](../interfaces/botbuilder_dialogs.choicepromptoptions.md)*): `Promise`.<`prompts.FoundChoice`⎮`undefined`> +► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[ChoicePromptOptions](../interfaces/botbuilder_dialogs.choicepromptoptions.md)*): `Promise`.<`O`⎮`undefined`> *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:72](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L72)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L124)* @@ -356,7 +413,7 @@ ___ -**Returns:** `Promise`.<`prompts.FoundChoice`⎮`undefined`> +**Returns:** `Promise`.<`O`⎮`undefined`> @@ -372,7 +429,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:65](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L65)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:117](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L117)* @@ -405,7 +462,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:70](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L70)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:122](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L122)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.compositecontrol.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.compositecontrol.md index f91a46749e..1caef9886d 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.compositecontrol.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.compositecontrol.md @@ -4,13 +4,101 @@ # Class: CompositeControl + +:package: **botbuilder-dialogs** + +A `CompositeControl` makes it easy to take an existing set of dialogs and package them up as a control that can be used within another bot. The control can be used either as a dialog added to the other bots `DialogSet` or on its own for bots that are using some other conversation management system. + +### Control Packaging + +You'll typically want to package your control as a new class derived from `CompositeControl`. Within your controls constructor you'll pass the `DialogSet` containing your controls dialogs and the `ID` of the initial dialog that should be started anytime a caller calls the dialog. + +If your control needs to be configured then you can pass through the configuration settings as a set of `defaultOptions` which will be merged with any options passed in by the caller when they call `begin()`. These will then be passed as arguments to the initial dialog that gets started. + +Here's a fairly simple example of a `ProfileControl` that's designed to prompt the user to enter their name and phone number which it will return as a JSON object to the caller: + + const { CompositeControl, DialogSet, TextPrompt } = require('botbuilder-dialogs'); + + const dialogs = new DialogSet(); + + class ProfileControl extends CompositeControl { + constructor() { + super(dialogs, 'fillProfile'); + } + } + module.exports.ProfileControl = ProfileControl; + + dialogs.add('fillProfile', [ + async function (dc, options) { + dc.instance.state = {}; + return dc.prompt('textPrompt', `What's your name?`); + }, + async function (dc, name) { + dc.instance.state.name = name; + return dc.prompt('textPrompt', `What's your phone number?`); + }, + async function (dc, phone) { + dc.instance.state.phone = phone; + + // Return completed profile + return dc.end(dc.instance.state); + } + ]); + + dialogs.add('textPrompt', new TextPrompt()); + +### Consume as Dialog + +On the consumption side the control we created can be used by a bot in much the same way they would use any other prompt. They can add a new instance of the control as a named dialog to their bots `DialogSet` and then start it using a call to `DialogContext.begin()`. If the control accepts options these can be passed in to the `begin()` call as well. + + const { DialogSet } = require('botbuilder-dialogs'); + const { ProfileControl } = require('./profileControl'); + + const dialogs = new DialogSet(); + + dialogs.add('getProfile', new ProfileControl()); + + dialogs.add('firstrun', [ + async function (dc) { + await dc.context.sendActivity(`Welcome! We need to ask a few questions to get started.`); + return dc.begin('getProfile'); + }, + async function (dc, profile) { + await dc.context.sendActivity(`Thanks ${profile.name}!`); + return dc.end(); + } + ]); + +### Control Usage + +If the consuming bot isn't dialog based they can still use your control. They will just need start the control from somewhere within their bots logic by calling the controls `begin()` method: + + const state = {}; + const control = new ProfileControl(); + await prompt.begin(context, state); + +The control will populate the `state` object passed in with information it needs to process the users response. This should be saved off with the bots conversation state as it needs to be passed into the controls `continue()` method on the next turn of conversation with the user: + + const control = new ProfileControl(); + const result = await control.continue(context, state); + if (!result.active) { + const profile = result.result; + } + +The `continue()` method returns a `DialogResult` object which can be used to determine when the control is finished and then to access any results it might have returned. To interrupt or cancel the control simply delete the `state` object the bot has been persisting. + ## Type parameters #### R + +(Optional) type of result that's expected to be returned by the control. + #### O -#### C : `BotContext` + +(Optional) options that can be passed into the [begin()](#begin) method. + ## Implements -* [Dialog](../interfaces/botbuilder_dialogs.dialog.md)`C` +* [Dialog](../interfaces/botbuilder_dialogs.dialog.md)`TurnContext` ## Index @@ -40,21 +128,21 @@ -### ⊕ **new CompositeControl**(dialogs: *[DialogSet](botbuilder_dialogs.dialogset.md)`C`*, dialogId: *`string`*, defaultOptions?: *`O`*): [CompositeControl](botbuilder_dialogs.compositecontrol.md) +### ⊕ **new CompositeControl**(dialogs: *[DialogSet](botbuilder_dialogs.dialogset.md)`TurnContext`*, dialogId: *`string`*, defaultOptions?: *`O`*): [CompositeControl](botbuilder_dialogs.compositecontrol.md) -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:18](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L18)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L126)* -Creates a new CompositeControl instance. +Creates a new `CompositeControl` instance. **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| dialogs | [DialogSet](botbuilder_dialogs.dialogset.md)`C` | Controls dialog set. | +| dialogs | [DialogSet](botbuilder_dialogs.dialogset.md)`TurnContext` | Controls dialog set. | | dialogId | `string` | ID of the root dialog that should be started anytime the control is started. | | defaultOptions | `O` | (Optional) set of default options that should be passed to controls root dialog. These will be merged with arguments passed in by the caller. | @@ -74,7 +162,7 @@ Creates a new CompositeControl instance. **● defaultOptions**: *`O`* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:18](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L18)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L126)* @@ -88,7 +176,7 @@ ___ **● dialogId**: *`string`* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:17](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L17)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:125](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L125)* @@ -100,9 +188,9 @@ ___ ### «Protected» dialogs -**● dialogs**: *[DialogSet](botbuilder_dialogs.dialogset.md)`C`* +**● dialogs**: *[DialogSet](botbuilder_dialogs.dialogset.md)`TurnContext`* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:16](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L16)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L124)* @@ -116,21 +204,32 @@ ___ ### begin -► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> +► **begin**(context: *`TurnContext`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> + + + +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:152](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L152)* + +Starts the control. Depending on the control, its possible for the control to finish immediately so it's advised to check the result object returned by `begin()` and ensure that the control is still active before continuing. -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:26](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L26)* +**Usage Example:** + const state = {}; + const result = await control.begin(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | -| options | `O` | - | +| context | `TurnContext` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. | +| options | `O` | (Optional) additional options supported by the control. | @@ -148,20 +247,30 @@ ___ ### continue -► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> +► **continue**(context: *`TurnContext`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> + + + +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:169](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L169)* + +Passes a users reply to the control for further processing. The bot should keep calling `continue()` for future turns until the control returns a result with `Active == false`. To cancel or interrupt the prompt simply delete the `state` object being persisted. -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L27)* +**Usage Example:** + const result = await control.continue(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | +| context | `TurnContext` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that was previously initialized by a call to [begin()](#begin). | @@ -179,13 +288,13 @@ ___ ### dialogBegin -► **dialogBegin**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, dialogArgs?: *`any`*): `Promise`.<`any`> +► **dialogBegin**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`TurnContext`*, dialogArgs?: *`any`*): `Promise`.<`any`> *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogBegin](../interfaces/botbuilder_dialogs.dialog.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:28](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L28)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:170](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L170)* @@ -193,7 +302,7 @@ ___ | Param | Type | Description | | ------ | ------ | ------ | -| dc | [DialogContext](botbuilder_dialogs.dialogcontext.md)`C` | - | +| dc | [DialogContext](botbuilder_dialogs.dialogcontext.md)`TurnContext` | - | | dialogArgs | `any` | - | @@ -212,13 +321,13 @@ ___ ### dialogContinue -► **dialogContinue**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*): `Promise`.<`any`> +► **dialogContinue**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`TurnContext`*): `Promise`.<`any`> *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogContinue](../interfaces/botbuilder_dialogs.dialog.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:29](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L29)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:171](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L171)* @@ -226,7 +335,7 @@ ___ | Param | Type | Description | | ------ | ------ | ------ | -| dc | [DialogContext](botbuilder_dialogs.dialogcontext.md)`C` | - | +| dc | [DialogContext](botbuilder_dialogs.dialogcontext.md)`TurnContext` | - | diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.confirmprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.confirmprompt.md index 76c4c51226..3d12aa2d97 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.confirmprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.confirmprompt.md @@ -5,9 +5,15 @@ # Class: ConfirmPrompt +:package: **botbuilder-dialogs** + Prompts a user to confirm something with a yes/no response. By default the prompt will return to the calling dialog a `boolean` representing the users selection. -**Example usage:** +The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a control if your bot is using some other conversation management system. + +### Dialog Usage + +When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to answer a `yes/no` or `true/false` question and the users response will be passed as an argument to the callers next waterfall step: const { DialogSet, ConfirmPrompt } = require('botbuilder-dialogs'); @@ -15,24 +21,67 @@ Prompts a user to confirm something with a yes/no response. By default the promp dialogs.add('confirmPrompt', new ConfirmPrompt()); - dialogs.add('confirmDemo', [ - function (dc) { - return dc.prompt('confirmPrompt', `confirm: answer "yes" or "no"`); + dialogs.add('confirmCancel', [ + async function (dc) { + return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`); }, - function (dc, value) { - dc.batch.reply(`Recognized value: ${value}`); + async function (dc, cancel) { + if (cancel) { + await dc.context.sendActivity(`Order cancelled.`); + } return dc.end(); } ]); +If the users response to the prompt fails to be recognized they will be automatically re-prompted to try again. By default the original prompt is re-sent to the user but you can provide an alternate prompt to send by passing in additional options: + + return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`, { retryPrompt: `Please answer "yes" or "no".` }); + +The prompts retry logic can also be completely customized by passing the prompts constructor a custom validator: + + dialogs.add('confirmPrompt', new ConfirmPrompt(async (context, value) => { + if (typeof confirmed != 'boolean') { + await context.sendActivity(`Please answer "yes" or "no".`); + } + return confirmed; + })); + +### Control Usage + +If your bot isn't dialog based you can still use the prompt on its own as a control. You will just need start the prompt from somewhere within your bots logic by calling the prompts `begin()` method: + + const state = {}; + const prompt = new ConfirmPrompt(); + await prompt.begin(context, state, { + prompt: `This will cancel your order. Are you sure?`, + retryPrompt: `Please answer "yes" or "no".` + }); + +The prompt will populate the `state` object you passed in with information it needs to process the users response. You should save this off to your bots conversation state as you'll need to pass it to the prompts `continue()` method on the next turn of conversation with the user: + + const prompt = new ConfirmPrompt(); + const result = await prompt.continue(context, state); + if (!result.active) { + const cancelOrder = result.result; + } + +The `continue()` method returns a `DialogResult` object which can be used to determine when the prompt is finished and then to access the results of the prompt. To interrupt or cancel the prompt simply delete the `state` object your bot is persisting. + ## Type parameters -#### C : `BotContext` +#### C : `TurnContext` + +The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + +#### O + +(Optional) output type returned by prompt. This defaults to a boolean `true` or `false` but can be changed by a custom validator passed to the prompt. + +#### R #### O -#### C : `BotContext` ## Hierarchy -↳ [Prompt](botbuilder_dialogs.prompt.md)`C`, `boolean` +↳ [Prompt](botbuilder_dialogs.prompt.md)`C` **↳ ConfirmPrompt** @@ -77,35 +126,24 @@ Prompts a user to confirm something with a yes/no response. By default the promp -### ⊕ **new ConfirmPrompt**(validator?: *[PromptValidator](../#promptvalidator)`C`, `boolean`*, defaultLocale?: *`string`*): [ConfirmPrompt](botbuilder_dialogs.confirmprompt.md) +### ⊕ **new ConfirmPrompt**(validator?: *`PromptValidator`.<`boolean`>,.<`O`>*, defaultLocale?: *`string`*): [ConfirmPrompt](botbuilder_dialogs.confirmprompt.md) *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L52)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L124)* -Creates a new instance of the prompt. - -**Example usage:** - - dialogs.add('confirmPrompt', new ConfirmPrompt((dc, value) => { - if (value === undefined) { - dc.batch.reply(`Invalid answer. Answer with "yes" or "no".`); - return undefined; - } else { - return value; - } - })); +Creates a new `ConfirmPrompt` instance. **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| validator | [PromptValidator](../#promptvalidator)`C`, `boolean` | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | -| defaultLocale | `string` | (Optional) locale to use if `dc.context.request.locale` not specified. Defaults to a value of `en-us`. | +| validator | `PromptValidator`.<`boolean`>,.<`O`> | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | +| defaultLocale | `string` | (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. | @@ -125,7 +163,7 @@ Creates a new instance of the prompt. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L15)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -139,7 +177,7 @@ ___ **● choices**: *`prompts.ConfirmChoices`* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L52)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L124)* @@ -147,10 +185,15 @@ Allows for the localization of the confirm prompts yes/no choices to other local **Example usage:** + const confirmPrompt = new ConfirmPrompt(); + // Configure yes/no choices for english and spanish (default) - ConfirmPrompt.choices['*'] = ['sí', 'no']; - ConfirmPrompt.choices['es'] = ['sí', 'no']; - ConfirmPrompt.choices['en-us'] = ['yes', 'no']; + confirmPrompt.choices['*'] = ['sí', 'no']; + confirmPrompt.choices['es'] = ['sí', 'no']; + confirmPrompt.choices['en-us'] = ['yes', 'no']; + + // Add to dialogs + dialogs.add('confirmPrompt', confirmPrompt); @@ -163,29 +206,40 @@ ___ ### begin -► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +Starts the control. Depending on the control, its possible for the control to finish immediately so it's advised to check the result object returned by `begin()` and ensure that the control is still active before continuing. + +**Usage Example:** + + const state = {}; + const result = await control.begin(context, state); + if (!result.active) { + const value = result.result; + } + + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | -| options | `O` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. | +| options | `O` | (Optional) additional options supported by the control. | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -201,7 +255,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:77](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L77)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:136](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L136)* @@ -212,7 +266,7 @@ Sets additional options passed to the `ChoiceFactory` and used to tweak the styl | Param | Type | Description | | ------ | ------ | ------ | -| options | `prompts.ChoiceFactoryOptions` | Additional options to set. | +| options | `prompts.ChoiceFactoryOptions` | Additional options to set. Defaults to `{ includeNumbers: false }` | @@ -230,28 +284,38 @@ ___ ### continue -► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:22](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L22)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* + + + +Passes a users reply to the control for further processing. The bot should keep calling `continue()` for future turns until the control returns a result with `Active == false`. To cancel or interrupt the prompt simply delete the `state` object being persisted. + +**Usage Example:** + const result = await control.continue(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that was previously initialized by a call to [begin()](#begin). | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -271,7 +335,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -306,7 +370,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L40)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -338,7 +402,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:83](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L83)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:142](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L142)* @@ -366,13 +430,13 @@ ___ ### «Protected» onRecognize -► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`boolean`⎮`undefined`> +► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`O`⎮`undefined`> *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:84](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L84)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:143](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L143)* @@ -387,7 +451,7 @@ ___ -**Returns:** `Promise`.<`boolean`⎮`undefined`> +**Returns:** `Promise`.<`O`⎮`undefined`> @@ -403,7 +467,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:82](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L82)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:141](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L141)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.control.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.control.md index 50ef1d3d61..1626d85f65 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.control.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.control.md @@ -4,10 +4,26 @@ # Class: Control + +:package: **botbuilder-dialogs** + +Base class for any dialog that wants to support being used as a dialog within a bots `DialogSet` or on its own as a control within a bot that uses an alternate conversation management system. + +The `Control` and `CompositeControl` classes are very similar in that they both add `begin()` and `continue()` methods which simplify consuming the control from a non-dialog based bot. The primary difference between the two classes is that the `CompositeControl` class is designed to bridge one `DialogSet` to another where the `Control` class assumes that the derived dialog can be used in complete isolation without the need for any other supporting dialogs. + ## Type parameters +#### C : `TurnContext` + +The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + #### R + +(Optional) type of result that's expected to be returned by the control. + #### O -#### C : `BotContext` + +(Optional) options that can be passed into the [begin()](#begin) method. + ## Hierarchy **Control** @@ -17,6 +33,11 @@ +↳ [OAuthPrompt](botbuilder_dialogs.oauthprompt.md) + + + + @@ -53,7 +74,7 @@ ### ⊕ **new Control**(defaultOptions?: *`O`*): [Control](botbuilder_dialogs.control.md) -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L15)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -64,7 +85,7 @@ Creates a new Control instance. | Param | Type | Description | | ------ | ------ | ------ | -| defaultOptions | `O` | (Optional) set of default options that should be passed to controls root dialog. These will be merged with arguments passed in by the caller. | +| defaultOptions | `O` | (Optional) set of default options that should be passed to controls `dialogBegin()` method. These will be merged with arguments passed in by the caller. | @@ -82,7 +103,7 @@ Creates a new Control instance. **● defaultOptions**: *`O`* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L15)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -100,17 +121,28 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* + + + +Starts the control. Depending on the control, its possible for the control to finish immediately so it's advised to check the result object returned by `begin()` and ensure that the control is still active before continuing. +**Usage Example:** + + const state = {}; + const result = await control.begin(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | -| options | `O` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. | +| options | `O` | (Optional) additional options supported by the control. | @@ -132,16 +164,26 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:22](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L22)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* + + + +Passes a users reply to the control for further processing. The bot should keep calling `continue()` for future turns until the control returns a result with `Active == false`. To cancel or interrupt the prompt simply delete the `state` object being persisted. + +**Usage Example:** + const result = await control.continue(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that was previously initialized by a call to [begin()](#begin). | @@ -165,7 +207,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogBegin](../interfaces/botbuilder_dialogs.dialog.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L23)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:69](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L69)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.datetimeprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.datetimeprompt.md index b287af02fe..b49ebb09b6 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.datetimeprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.datetimeprompt.md @@ -5,34 +5,78 @@ # Class: DatetimePrompt +:package: **botbuilder-dialogs** + Prompts a user to enter a datetime expression. By default the prompt will return to the calling dialog a `FoundDatetime[]` but this can be overridden using a custom `PromptValidator`. -**Example usage:** +The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a control if your bot is using some other conversation management system. + +### Dialog Usage + +When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to reply with a date and/or time. The recognized date/time will be passed as an argument to the callers next waterfall step: const { DialogSet, DatetimePrompt } = require('botbuilder-dialogs'); const dialogs = new DialogSet(); - dialogs.add('datetimePrompt', new DatetimePrompt()); + dialogs.add('datetimePrompt', new DatetimePrompt(AlarmTimeValidator)); - dialogs.add('datetimeDemo', [ - function (dc) { - return dc.prompt('datetimePrompt', `datetime: enter a datetime`); + dialogs.add('setAlarmTime', [ + async function (dc) { + return dc.prompt('datetimePrompt', `What time should I set your alarm for?`); }, - function (dc, values) { - dc.batch.reply(`Recognized values: ${JSON.stringify(values)}`); + async function (dc, time) { + await dc.context.sendActivity(`Alarm time set`); return dc.end(); } ]); + async function AlarmTimeValidator(context, values) { + try { + if (!Array.isArray(values) || values.length < 0) { throw new Error('missing time') } + if (values[0].type !== 'datetime') { throw new Error('unsupported type') } + const value = new Date(values[0].value); + if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } + return value; + } catch (err) { + await context.sendActivity(`Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); + return undefined; + } + } + +### Control Usage + +If your bot isn't dialog based you can still use the prompt on its own as a control. You will just need start the prompt from somewhere within your bots logic by calling the prompts `begin()` method: + + const state = {}; + const prompt = new DatetimePrompt(AlarmTimeValidator); + await prompt.begin(context, state, { prompt: `What time should I set your alarm for?` }); + +The prompt will populate the `state` object you passed in with information it needs to process the users response. You should save this off to your bots conversation state as you'll need to pass it to the prompts `continue()` method on the next turn of conversation with the user: + + const prompt = new ConfirmPrompt(); + const result = await prompt.continue(context, state); + if (!result.active) { + const time = result.result; + } + +The `continue()` method returns a `DialogResult` object which can be used to determine when the prompt is finished and then to access the results of the prompt. To interrupt or cancel the prompt simply delete the `state` object your bot is persisting. + ## Type parameters -#### C : `BotContext` +#### C : `TurnContext` + +The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + +#### O + +(Optional) output type returned by prompt. This defaults to a `FoundDatetime[]` but can be changed by a custom validator passed to the prompt. + +#### R #### O -#### C : `BotContext` ## Hierarchy -↳ [Prompt](botbuilder_dialogs.prompt.md)`C`, `prompts.FoundDatetime`[] +↳ [Prompt](botbuilder_dialogs.prompt.md)`C` **↳ DatetimePrompt** @@ -74,39 +118,24 @@ Prompts a user to enter a datetime expression. By default the prompt will return -### ⊕ **new DatetimePrompt**(validator?: *[PromptValidator](../#promptvalidator)`C`, `prompts.FoundDatetime`[]*, defaultLocale?: *`string`*): [DatetimePrompt](botbuilder_dialogs.datetimeprompt.md) +### ⊕ **new DatetimePrompt**(validator?: *`PromptValidator`.<`prompts.FoundDatetime`[]>,.<`O`>*, defaultLocale?: *`string`*): [DatetimePrompt](botbuilder_dialogs.datetimeprompt.md) *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L37)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:92](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L92)* -Creates a new instance of the prompt. - -**Example usage:** - - dialogs.add('timePrompt', new DatetimePrompt((dc, values) => { - try { - if (!Array.isArray(values) || values.length < 0) { throw new Error('missing time') } - if (values[0].type !== 'datetime') { throw new Error('unsupported type') } - const value = new Date(values[0].value); - if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } - return value; - } catch (err) { - dc.batch.reply(`Invalid time. Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); - return undefined; - } - })); +Creates a new `DatetimePrompt` instance. **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| validator | [PromptValidator](../#promptvalidator)`C`, `prompts.FoundDatetime`[] | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | -| defaultLocale | `string` | (Optional) locale to use if `dc.context.request.locale` not specified. Defaults to a value of `en-us`. | +| validator | `PromptValidator`.<`prompts.FoundDatetime`[]>,.<`O`> | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | +| defaultLocale | `string` | (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. | @@ -126,7 +155,7 @@ Creates a new instance of the prompt. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L15)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -140,29 +169,40 @@ ___ ### begin -► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* + + +Starts the control. Depending on the control, its possible for the control to finish immediately so it's advised to check the result object returned by `begin()` and ensure that the control is still active before continuing. + +**Usage Example:** + + const state = {}; + const result = await control.begin(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | -| options | `O` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. | +| options | `O` | (Optional) additional options supported by the control. | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -174,28 +214,38 @@ ___ ### continue -► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:22](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L22)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* + + + +Passes a users reply to the control for further processing. The bot should keep calling `continue()` for future turns until the control returns a result with `Active == false`. To cancel or interrupt the prompt simply delete the `state` object being persisted. + +**Usage Example:** + const result = await control.continue(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that was previously initialized by a call to [begin()](#begin). | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -215,7 +265,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -250,7 +300,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L40)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -282,7 +332,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:61](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L61)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:99](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L99)* @@ -310,13 +360,13 @@ ___ ### «Protected» onRecognize -► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`prompts.FoundDatetime`[]⎮`undefined`> +► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`O`⎮`undefined`> *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:62](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L62)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L100)* @@ -331,7 +381,7 @@ ___ -**Returns:** `Promise`.<`prompts.FoundDatetime`[]⎮`undefined`> +**Returns:** `Promise`.<`O`⎮`undefined`> diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogcontext.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogcontext.md index e9268ab5bb..974061c42e 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogcontext.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogcontext.md @@ -4,8 +4,14 @@ # Class: DialogContext + +:package: **botbuilder-dialogs** + ## Type parameters -#### C : `BotContext` +#### C : `TurnContext` + +The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + ## Index ### Constructors @@ -15,8 +21,8 @@ ### Properties -* [batch](botbuilder_dialogs.dialogcontext.md#batch) * [context](botbuilder_dialogs.dialogcontext.md#context) +* [dialogResult](botbuilder_dialogs.dialogcontext.md#dialogresult) * [dialogs](botbuilder_dialogs.dialogcontext.md#dialogs) * [instance](botbuilder_dialogs.dialogcontext.md#instance) * [stack](botbuilder_dialogs.dialogcontext.md#stack) @@ -41,7 +47,7 @@ ### ⊕ **new DialogContext**(dialogs: *[DialogSet](botbuilder_dialogs.dialogset.md)`C`*, context: *`C`*, stack: *[DialogInstance](../interfaces/botbuilder_dialogs.dialoginstance.md)[]*): [DialogContext](botbuilder_dialogs.dialogcontext.md) -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L40)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:43](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L43)* @@ -66,31 +72,31 @@ Creates a new DialogContext instance. ## Properties - + -### batch +### context -**● batch**: *`BatchOutput`* +**● context**: *`C`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L40)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:41](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L41)* -Allows for batch based responses from the bot. Optional to use but you should add `BatchOutput` to your adapters middleware stack if you do, otherwise you'll need to manually call `dc.batch.flush()` somewhere within your bots logic. +___ + -___ +### dialogResult - +**● dialogResult**: *[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`any`* -### context +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:57](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L57)* -**● context**: *`C`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:33](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L33)* +Returns a structure that indicates whether there is still an active dialog on the stack along with the result returned by a dialog that just ended. @@ -103,7 +109,7 @@ ___ **● dialogs**: *[DialogSet](botbuilder_dialogs.dialogset.md)`C`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:32](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L32)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L40)* @@ -117,7 +123,7 @@ ___ **● instance**: *[DialogInstance](../interfaces/botbuilder_dialogs.dialoginstance.md)⎮`undefined`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:49](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L49)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L52)* @@ -134,7 +140,7 @@ ___ **● stack**: *[DialogInstance](../interfaces/botbuilder_dialogs.dialoginstance.md)[]* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L34)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:42](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L42)* @@ -148,11 +154,11 @@ ___ ### begin -► **begin**(dialogId: *`string`*, dialogArgs?: *`any`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)> +► **begin**(dialogId: *`string`*, dialogArgs?: *`any`*): `Promise`.<`any`> -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:62](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L62)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:70](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L70)* @@ -175,7 +181,7 @@ Pushes a new dialog onto the dialog stack. -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)> +**Returns:** `Promise`.<`any`> @@ -187,11 +193,11 @@ ___ ### continue -► **continue**(): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)> +► **continue**(): `Promise`.<`any`> -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:94](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L94)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:103](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L103)* @@ -209,7 +215,7 @@ Continues execution of the active dialog, if there is one, by passing the contex -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)> +**Returns:** `Promise`.<`any`> @@ -221,11 +227,11 @@ ___ ### end -► **end**(result?: *`any`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)> +► **end**(result?: *`any`*): `Promise`.<`any`> -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:119](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L119)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:128](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L128)* @@ -255,7 +261,7 @@ The parent dialog will have its `Dialog.resume()` method invoked with any return -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)> +**Returns:** `Promise`.<`any`> @@ -271,7 +277,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:129](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L129)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:138](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L138)* @@ -296,11 +302,11 @@ ___ ### prompt -► **prompt**O(dialogId: *`string`*, prompt: *`string`⎮`Partial`.<`Activity`>*, choicesOrOptions?: *`O`⎮`any`[]*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)> +► **prompt**O(dialogId: *`string`*, prompt: *`string`⎮`Partial`.<`Activity`>*, choicesOrOptions?: *`O`⎮`any`[]*, options?: *`O`*): `Promise`.<`any`> -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:77](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L77)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:86](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L86)* @@ -324,13 +330,13 @@ Helper function to simplify formatting the options for calling a prompt dialog. | dialogId | `string` | ID of the prompt to start. | | prompt | `string`⎮`Partial`.<`Activity`> | Initial prompt to send the user. | | choicesOrOptions | `O`⎮`any`[] | (Optional) array of choices to prompt the user for or additional prompt options. | -| options | `O` | - | +| options | `O` | (Optional) additional prompt options. | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)> +**Returns:** `Promise`.<`any`> @@ -342,11 +348,11 @@ ___ ### replace -► **replace**(dialogId: *`string`*, dialogArgs?: *`any`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)> +► **replace**(dialogId: *`string`*, dialogArgs?: *`any`*): `Promise`.<`any`> -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:151](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L151)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:160](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L160)* @@ -377,7 +383,7 @@ Ends the active dialog and starts a new dialog in its place. This is particularl -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)> +**Returns:** `Promise`.<`any`> diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogset.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogset.md index 73b3e3a685..5173047bb9 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogset.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogset.md @@ -5,38 +5,69 @@ # Class: DialogSet +:package: **botbuilder-dialogs** + A related set of dialogs that can all call each other. -**Example usage:** +### Overview - const { Bot, MemoryStorage, BotStateManager } = require('botbuilder'); - const { ConsoleAdapter } = require('botbuilder-node'); - const { DialogSet } = require('botbuilder-dialogs'); +The dialogs library uses a stack based metaphor to manage a bot conversation with a user. In this model the bt begins dialogs to prompt the user for information. Those dialogs will typically call prompts to actually ask the user for information. A variety of typed prompts are provided and are themselves just other dialogs. When a prompt recognizes a users input as being valid, it will end itself and return the users input to the dialog that started it. That dialog is then free to either process the users input or ask the user for more information by pushing other dialogs/prompts onto the stack. Below is a simple `Waterfall` dialog that asks the user for their name and phone number: + + const { DialogSet, TextPrompt } = require('botbuilder-dialogs'); const dialogs = new DialogSet(); - dialogs.add('greeting', [ - function (context) { - context.reply(`Hello... I'm a bot :)`); - return dialogs.end(context); - } + dialogs.add('fillProfile', [ + async function (dc, options) { + dc.instance.state = {}; + return dc.prompt('textPrompt', `What's your name?`); + }, + async function (dc, name) { + dc.instance.state.name = name; + return dc.prompt('textPrompt', `What's your phone number?`); + }, + async function (dc, phone) { + dc.instance.state.phone = phone; + + // Return completed profile + return dc.end(dc.instance.state); + } ]); - const adapter = new ConsoleAdapter().listen(); - const bot = new Bot(adapter) - .use(new MemoryStorage()) - .use(new BotStateManager()) - .onReceive((context) => { - return dialogs.continue(context).then(() => { - // If nothing has responded start greeting dialog - if (!context.responded) { - return dialogs.begin(context, 'greeting'); - } - }); - }); + dialogs.add('textPrompt', new TextPrompt()); + +At first glance it probably looks like we're making this simple task of asking the user two questions way harder then it needs to be. It turns out though that asking a user even one question is a really hard problem. The primary issues coming from the fact that a) your bot will likely be running across multiple compute nodes and the node that asked the user a question may not be the one that receives their answer. and b) it could be minutes, hours, days, or even weeks before the user replies to the bot. Your bots compute process could have been restarted or updated any number of times before the user replies to the last question. + +The dialogs library addresses both of those issues by having you statically define and explicitly name all of your bots dialogs on startups. It then uses a persisted dialog stack to essentially maintain a program pointer so that any time a message is received from a user it can identify the function it should run to process that message in a deterministic way. + +### Routing Requests + +To run the 'fillProfile' dialog above we need to add a bit of fairly boilerplate code to our bots routing logic: + + server.post('/api/messages', (req, res) => { + adapter.processActivity(req, res, async (context) => { + // Continue execution if there's a "current" dialog + const state = conversationState.get(context); + const dc = dialogs.createContext(context, state); + await dc.continue(); + if (!context.responded && context.activity.type === ActivityType.Message) { + // No active dialogs so start 'fillProfile' dialog + await dc.begin('fillProfile'); + } + }); + }); + +This code results in a bot that loops over prompting the user to fill out their profile so while not overly useful it does serve as a good starting point for understanding how to route request to your bots dialogs. + +The code first creates a `DialogContext` and then calls `dc.continue()` which will route the request to the "current" dialog on the top of the stack, if there is one. It's using `context.responded` to determine if anything processed the request which is reasonable given that as a best practice your bot should always reply to any message received from the user. So if nothing has responded and we've received a `message` activity we'll start the 'fillProfile' by calling `dc.begin()`. + +### Detecting Interruptions ## Type parameters -#### C : `BotContext` +#### C : `TurnContext` + +The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + ## Index ### Methods @@ -59,7 +90,7 @@ A related set of dialogs that can all call each other. -*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:64](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L64)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:121](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L121)* @@ -68,9 +99,9 @@ Adds a new dialog to the set and returns the added dialog. **Example usage:** dialogs.add('greeting', [ - function (context, user) { - context.reply(`Hello ${user.name}... I'm a bot :)`); - return dialogs.end(context); + async function (dc) { + await dc.context.sendActivity(`Hello world!`); + return dc.end(); } ]); @@ -90,7 +121,7 @@ Adds a new dialog to the set and returns the added dialog. -*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:65](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L65)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:122](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L122)* @@ -121,7 +152,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:66](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L66)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:123](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L123)* @@ -152,7 +183,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:78](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L78)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:135](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L135)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.numberprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.numberprompt.md index 5b882d0803..1f594f28e9 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.numberprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.numberprompt.md @@ -5,34 +5,85 @@ # Class: NumberPrompt +:package: **botbuilder-dialogs** + Prompts a user to enter a number. By default the prompt will return to the calling dialog a `number` representing the users input. -**Example usage:** +The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a control if your bot is using some other conversation management system. + +### Dialog Usage + +When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to reply with a number which will be passed as an argument to the callers next waterfall step: const { DialogSet, NumberPrompt } = require('botbuilder-dialogs'); const dialogs = new DialogSet(); - dialogs.add('numberPrompt', new NumberPrompt()); + dialogs.add('agePrompt', new NumberPrompt()); - dialogs.add('numberDemo', [ - function (dc) { - return dc.prompt('numberPrompt', `number: enter a number`); + dialogs.add('askAge', [ + async function (dc) { + return dc.prompt('agePrompt', `How old are you?`); }, - function (dc, value) { - dc.batch.reply(`Recognized value: ${value}`); + async function (dc, age) { + if (age < 40) { + await dc.context.sendActivity(`So young :)`); + } else { + await dc.context.sendActivity(`I hear ${age} is the new ${age - 10} :)`); + } return dc.end(); } ]); +The prompt can be configured with a custom validator to perform additional checks like ensuring that the user responds with a valid age and that only whole numbers are returned: + + dialogs.add('agePrompt', new NumberPrompt(async (context, value) => { + if (typeof value == 'number') { + if (value >= 1 && value < 111) { + // Return age rounded down to nearest whole number. + return Math.floor(value); + } + } + await context.sendActivity(`Please enter a number between 1 and 110 or say "cancel".`); + return undefined; + })); + +### Control Usage + +If your bot isn't dialog based you can still use the prompt on its own as a control. You will just need start the prompt from somewhere within your bots logic by calling the prompts `begin()` method: + + const state = {}; + const prompt = new NumberPrompt(); + await prompt.begin(context, state, { + prompt: `How old are you?`, + retryPrompt: `Please reply with a valid number like "23".` + }); + +The prompt will populate the `state` object you passed in with information it needs to process the users response. You should save this off to your bots conversation state as you'll need to pass it to the prompts `continue()` method on the next turn of conversation with the user: + + const prompt = new ConfirmPrompt(); + const result = await prompt.continue(context, state); + if (!result.active) { + const age = result.result; + } + +The `continue()` method returns a `DialogResult` object which can be used to determine when the prompt is finished and then to access the results of the prompt. To interrupt or cancel the prompt simply delete the `state` object your bot is persisting. + ## Type parameters -#### C : `BotContext` +#### C : `TurnContext` + +The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + +#### O + +(Optional) output type returned by prompt. This defaults to a `number` but can be changed by a custom validator passed to the prompt. + +#### R #### O -#### C : `BotContext` ## Hierarchy -↳ [Prompt](botbuilder_dialogs.prompt.md)`C`, `number` +↳ [Prompt](botbuilder_dialogs.prompt.md)`C` **↳ NumberPrompt** @@ -74,35 +125,24 @@ Prompts a user to enter a number. By default the prompt will return to the calli -### ⊕ **new NumberPrompt**(validator?: *[PromptValidator](../#promptvalidator)`C`, `number`*, defaultLocale?: *`string`*): [NumberPrompt](botbuilder_dialogs.numberprompt.md) +### ⊕ **new NumberPrompt**(validator?: *`PromptValidator`.<`number`>,.<`O`>*, defaultLocale?: *`string`*): [NumberPrompt](botbuilder_dialogs.numberprompt.md) *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L36)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L100)* -Creates a new instance of the prompt. - -**Example usage:** - - dialogs.add('agePrompt', new NumberPrompt((dc, value) => { - if (value === undefined || value < 1 || value > 110) { - dc.batch.reply(`Invalid age. Only ages between 1 and 110 are allowed.`); - return undefined; - } else { - return value; - } - })); +Creates a new `NumberPrompt` instance. **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| validator | [PromptValidator](../#promptvalidator)`C`, `number` | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | -| defaultLocale | `string` | (Optional) locale to use if `dc.context.request.locale` not specified. Defaults to a value of `en-us`. | +| validator | `PromptValidator`.<`number`>,.<`O`> | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | +| defaultLocale | `string` | (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. | @@ -122,7 +162,7 @@ Creates a new instance of the prompt. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L15)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -136,29 +176,40 @@ ___ ### begin -► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* + +Starts the control. Depending on the control, its possible for the control to finish immediately so it's advised to check the result object returned by `begin()` and ensure that the control is still active before continuing. + +**Usage Example:** + + const state = {}; + const result = await control.begin(context, state); + if (!result.active) { + const value = result.result; + } + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | -| options | `O` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. | +| options | `O` | (Optional) additional options supported by the control. | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -170,28 +221,38 @@ ___ ### continue -► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:22](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L22)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* + + + +Passes a users reply to the control for further processing. The bot should keep calling `continue()` for future turns until the control returns a result with `Active == false`. To cancel or interrupt the prompt simply delete the `state` object being persisted. + +**Usage Example:** + const result = await control.continue(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that was previously initialized by a call to [begin()](#begin). | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -211,7 +272,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -246,7 +307,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L40)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -278,7 +339,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:56](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L56)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:107](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L107)* @@ -306,13 +367,13 @@ ___ ### «Protected» onRecognize -► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`number`⎮`undefined`> +► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`O`⎮`undefined`> *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:57](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L57)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:108](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L108)* @@ -327,7 +388,7 @@ ___ -**Returns:** `Promise`.<`number`⎮`undefined`> +**Returns:** `Promise`.<`O`⎮`undefined`> diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.oauthprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.oauthprompt.md new file mode 100644 index 0000000000..3f0f7c9baa --- /dev/null +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.oauthprompt.md @@ -0,0 +1,371 @@ +[Bot Builder SDK - Dialogs](../README.md) > [OAuthPrompt](../classes/botbuilder_dialogs.oauthprompt.md) + + + +# Class: OAuthPrompt + + +:package: **botbuilder-dialogs** + +Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) service. The prompt will attempt to retrieve the users current token and if the user isn't signed in, it will send them an `OAuthCard` containing a button they can press to signin. Depending on the channel, the user will be sent through one of two possible signin flows: + +* The automatic signin flow where once the user signs in and the SSO service will forward the bot the users access token using either an `event` or `invoke` activity. +* The "magic code" flow where where once the user signs in they will be prompted by the SSO service to send the bot a six digit code confirming their identity. This code will be sent as a standard `message` activity. + +Both flows are automatically supported by the `OAuthPrompt` and the only thing you need to be careful of is that you don't block the `event` and `invoke` activities that the prompt might be waiting on. + +Like other prompts, the `OAuthPrompt` can be used either as a dialog added to your bots `DialogSet` or on its own as a control if your bot is using some other conversation management system. + +### Dialog Usage + +When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to signin as needed and their access token will be passed as an argument to the callers next waterfall step: + + const { DialogSet, OAuthPrompt } = require('botbuilder-dialogs'); + + const dialogs = new DialogSet(); + + dialogs.add('loginPrompt', new OAuthPrompt({ + connectionName: 'GitConnection', + title: 'Login To GitHub', + timeout: 300000 // User has 5 minutes to login + })); + + dialogs.add('taskNeedingLogin', [ + async function (dc) { + return dc.begin('loginPrompt'); + }, + async function (dc, token) { + if (token) { + // Continue with task needing access token + } else { + await dc.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`); + return dc.end(); + } + } + ]); + +### Control Usage + +If your bot isn't dialog based you can still use the prompt on its own as a control. You will just need start the prompt from somewhere within your bots logic by calling the prompts `begin()` method: + + const state = {}; + const prompt = new OAuthPrompt({ + connectionName: 'GitConnection', + title: 'Login To GitHub' + }); + const result = await prompt.begin(context, state); + if (!result.active) { + const token = result.result; + } + +If the user is already signed into the service we will get a token back immediately. We therefore need to check to see if the prompt is still active after the call to `begin()`. + +If the prompt is still active that means the user was sent an `OAuthCard` prompting the user to signin and we need to pass any additional activities we receive to the `continue()` method. We can't be certain which auth flow is being used so it's best to route _all_ activities, regardless of type, to the `continue()` method for processing. + + const prompt = new OAuthPrompt({ + connectionName: 'GitConnection', + title: 'Login To GitHub' + }); + const result = await prompt.continue(context, state); + if (!result.active) { + const token = result.result; + if (token) { + // User has successfully signed in + } else { + // The signin has timed out + } + } + +## Type parameters +#### C : `TurnContext` + +The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + +#### R +#### O +## Hierarchy + + + [Control](botbuilder_dialogs.control.md)`C` + +**↳ OAuthPrompt** + + + + + + + +## Implements + +* [Dialog](../interfaces/botbuilder_dialogs.dialog.md)`C` + +## Index + +### Constructors + +* [constructor](botbuilder_dialogs.oauthprompt.md#constructor) + + +### Properties + +* [defaultOptions](botbuilder_dialogs.oauthprompt.md#defaultoptions) + + +### Methods + +* [begin](botbuilder_dialogs.oauthprompt.md#begin) +* [continue](botbuilder_dialogs.oauthprompt.md#continue) +* [dialogBegin](botbuilder_dialogs.oauthprompt.md#dialogbegin) +* [dialogContinue](botbuilder_dialogs.oauthprompt.md#dialogcontinue) +* [signOutUser](botbuilder_dialogs.oauthprompt.md#signoutuser) + + + +--- +## Constructors + + + +### ⊕ **new OAuthPrompt**(settings: *[OAuthPromptSettingsWithTimeout](../interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md)*, validator?: *`prompts.PromptValidator`.<`any`>,.<`any`>*): [OAuthPrompt](botbuilder_dialogs.oauthprompt.md) + + +*Overrides [Control](botbuilder_dialogs.control.md).[constructor](botbuilder_dialogs.control.md#constructor)* + +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L126)* + + + +Creates a new `OAuthPrompt` instance. + + +**Parameters:** + +| Param | Type | Description | +| ------ | ------ | ------ | +| settings | [OAuthPromptSettingsWithTimeout](../interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md) | Settings used to configure the prompt. | +| validator | `prompts.PromptValidator`.<`any`>,.<`any`> | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | + + + + + +**Returns:** [OAuthPrompt](botbuilder_dialogs.oauthprompt.md) + +--- + + +## Properties + + +### «Protected» defaultOptions + +**● defaultOptions**: *`O`* + +*Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* + +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* + + + + + +___ + + +## Methods + + +### begin + +► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> + + + +*Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* + +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* + + + +Starts the control. Depending on the control, its possible for the control to finish immediately so it's advised to check the result object returned by `begin()` and ensure that the control is still active before continuing. + +**Usage Example:** + + const state = {}; + const result = await control.begin(context, state); + if (!result.active) { + const value = result.result; + } + + +**Parameters:** + +| Param | Type | Description | +| ------ | ------ | ------ | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. | +| options | `O` | (Optional) additional options supported by the control. | + + + + + +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> + + + + + +___ + + + +### continue + +► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> + + + +*Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* + +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* + + + +Passes a users reply to the control for further processing. The bot should keep calling `continue()` for future turns until the control returns a result with `Active == false`. To cancel or interrupt the prompt simply delete the `state` object being persisted. + +**Usage Example:** + + const result = await control.continue(context, state); + if (!result.active) { + const value = result.result; + } + + +**Parameters:** + +| Param | Type | Description | +| ------ | ------ | ------ | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that was previously initialized by a call to [begin()](#begin). | + + + + + +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> + + + + + +___ + + + +### dialogBegin + +► **dialogBegin**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`any`> + + + +*Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* + +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:133](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L133)* + + + +**Parameters:** + +| Param | Type | Description | +| ------ | ------ | ------ | +| dc | [DialogContext](botbuilder_dialogs.dialogcontext.md)`C` | - | +| options | [PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md) | - | + + + + + +**Returns:** `Promise`.<`any`> + + + + + +___ + + + +### dialogContinue + +► **dialogContinue**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*): `Promise`.<`any`> + + + +*Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogContinue](../interfaces/botbuilder_dialogs.dialog.md#dialogcontinue)* + +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:134](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L134)* + + + +**Parameters:** + +| Param | Type | Description | +| ------ | ------ | ------ | +| dc | [DialogContext](botbuilder_dialogs.dialogcontext.md)`C` | - | + + + + + +**Returns:** `Promise`.<`any`> + + + + + +___ + + + +### signOutUser + +► **signOutUser**(context: *`TurnContext`*): `Promise`.<`void`> + + + +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:149](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L149)* + + + +Signs the user out of the service. + +**Usage Example:** + + const prompt = new OAuthPrompt({ + connectionName: 'GitConnection', + title: 'Login To GitHub' + }); + await prompt.signOutUser(context); + + +**Parameters:** + +| Param | Type | Description | +| ------ | ------ | ------ | +| context | `TurnContext` | - | + + + + + +**Returns:** `Promise`.<`void`> + + + + + +___ + + diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.prompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.prompt.md index bde6fc4c85..b010cafc07 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.prompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.prompt.md @@ -4,11 +4,18 @@ # Class: Prompt + +:package: **botbuilder-dialogs** + +Base class for all prompts. + ## Type parameters -#### C : `BotContext` -#### T +#### C : `TurnContext` + +The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + +#### R #### O -#### C : `BotContext` ## Hierarchy @@ -84,12 +91,12 @@ -### ⊕ **new Prompt**(validator?: *[PromptValidator](../#promptvalidator)`C`, `T`*): [Prompt](botbuilder_dialogs.prompt.md) +### ⊕ **new Prompt**(validator?: *`PromptValidator`.<`any`>,.<`any`>*): [Prompt](botbuilder_dialogs.prompt.md) *Overrides [Control](botbuilder_dialogs.control.md).[constructor](botbuilder_dialogs.control.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:35](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L35)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L34)* @@ -97,7 +104,7 @@ | Param | Type | Description | | ------ | ------ | ------ | -| validator | [PromptValidator](../#promptvalidator)`C`, `T` | - | +| validator | `PromptValidator`.<`any`>,.<`any`> | - | @@ -117,7 +124,7 @@ *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L15)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -131,29 +138,40 @@ ___ ### begin -► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* + + +Starts the control. Depending on the control, its possible for the control to finish immediately so it's advised to check the result object returned by `begin()` and ensure that the control is still active before continuing. + +**Usage Example:** + + const state = {}; + const result = await control.begin(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | -| options | `O` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. | +| options | `O` | (Optional) additional options supported by the control. | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -165,28 +183,38 @@ ___ ### continue -► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:22](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L22)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* + + + +Passes a users reply to the control for further processing. The bot should keep calling `continue()` for future turns until the control returns a result with `Active == false`. To cancel or interrupt the prompt simply delete the `state` object being persisted. + +**Usage Example:** + const result = await control.continue(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that was previously initialized by a call to [begin()](#begin). | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -204,7 +232,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -237,7 +265,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogContinue](../interfaces/botbuilder_dialogs.dialog.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L40)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -267,7 +295,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L37)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L36)* @@ -295,11 +323,11 @@ ___ ### «Protected» onRecognize -► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`T`⎮`undefined`> +► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`any`⎮`undefined`> -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L37)* @@ -314,7 +342,7 @@ ___ -**Returns:** `Promise`.<`T`⎮`undefined`> +**Returns:** `Promise`.<`any`⎮`undefined`> diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.textprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.textprompt.md index 27af88cb08..ddc9712660 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.textprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.textprompt.md @@ -5,34 +5,75 @@ # Class: TextPrompt +:package: **botbuilder-dialogs** + Prompts a user to enter some text. By default the prompt will return to the calling dialog a `string` representing the users reply. -**Example usage:** +The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a control if your bot is using some other conversation management system. + +### Dialog Usage + +When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted with a question and the response will be passed as an argument to the callers next waterfall step: const { DialogSet, TextPrompt } = require('botbuilder-dialogs'); const dialogs = new DialogSet(); - dialogs.add('textPrompt', new TextPrompt()); + dialogs.add('namePrompt', new TextPrompt()); - dialogs.add('textDemo', [ - function (dc) { - return dc.prompt('textPrompt', `text: enter some text`); + dialogs.add('askName', [ + async function (dc) { + return dc.prompt('namePrompt', `What's your name?`); }, - function (dc, value) { - dc.batch.reply(`Recognized value: ${value}`); + async function (dc, name) { + await dc.context.sendActivity(`Hi ${name}!`); return dc.end(); } ]); +The prompt can be configured with a custom validator to perform additional checks like ensuring that the user responds with a valid age and that only whole numbers are returned: + + dialogs.add('namePrompt', new TextPrompt(async (context, value) => { + if (value && value.length >= 3) { + return value; + } + await context.sendActivity(`Your entry must be at least 3 characters in length.`); + return undefined; + })); + +### Control Usage + +If your bot isn't dialog based you can still use the prompt on its own as a control. You will just need start the prompt from somewhere within your bots logic by calling the prompts `begin()` method: + + const state = {}; + const prompt = new TextPrompt(); + await prompt.begin(context, state, { prompt: `What's your name?` }); + +The prompt will populate the `state` object you passed in with information it needs to process the users response. You should save this off to your bots conversation state as you'll need to pass it to the prompts `continue()` method on the next turn of conversation with the user: + + const prompt = new TextPrompt(); + const result = await prompt.continue(context, state); + if (!result.active) { + const name = result.result; + } + +The `continue()` method returns a `DialogResult` object which can be used to determine when the prompt is finished and then to access the results of the prompt. To interrupt or cancel the prompt simply delete the `state` object your bot is persisting. + ## Type parameters -#### C : `BotContext` +#### C : `TurnContext` + +The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + +#### O + +(Optional) output type returned by prompt. This defaults to a `string` but can be changed by a custom validator passed to the prompt. + +#### R #### O -#### C : `BotContext` ## Hierarchy -↳ [Prompt](botbuilder_dialogs.prompt.md)`C`, `string` +↳ [Prompt](botbuilder_dialogs.prompt.md)`C` **↳ TextPrompt** @@ -74,34 +115,23 @@ Prompts a user to enter some text. By default the prompt will return to the call -### ⊕ **new TextPrompt**(validator?: *[PromptValidator](../#promptvalidator)`C`, `string`*): [TextPrompt](botbuilder_dialogs.textprompt.md) +### ⊕ **new TextPrompt**(validator?: *`PromptValidator`.<`string`>,.<`O`>*): [TextPrompt](botbuilder_dialogs.textprompt.md) *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L36)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:89](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L89)* -Creates a new instance of the prompt. - -**Example usage:** - - dialogs.add('titlePrompt', new TextPrompt((dc, value) => { - if (!value || value.length < 3) { - dc.batch.reply(`Title should be at least 3 characters long.`); - return undefined; - } else { - return value.trim(); - } - })); +Creates a new `TextPrompt` instance. **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| validator | [PromptValidator](../#promptvalidator)`C`, `string` | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | +| validator | `PromptValidator`.<`string`>,.<`O`> | (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. | @@ -121,7 +151,7 @@ Creates a new instance of the prompt. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L15)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -135,29 +165,40 @@ ___ ### begin -► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* + +Starts the control. Depending on the control, its possible for the control to finish immediately so it's advised to check the result object returned by `begin()` and ensure that the control is still active before continuing. + +**Usage Example:** + + const state = {}; + const result = await control.begin(context, state); + if (!result.active) { + const value = result.result; + } + **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | -| options | `O` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. | +| options | `O` | (Optional) additional options supported by the control. | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -169,28 +210,38 @@ ___ ### continue -► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:22](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/control.d.ts#L22)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* + + + +Passes a users reply to the control for further processing. The bot should keep calling `continue()` for future turns until the control returns a result with `Active == false`. To cancel or interrupt the prompt simply delete the `state` object being persisted. + +**Usage Example:** + const result = await control.continue(context, state); + if (!result.active) { + const value = result.result; + } **Parameters:** | Param | Type | Description | | ------ | ------ | ------ | -| context | `C` | - | -| state | `object` | - | +| context | `C` | Context for the current turn of the conversation with the user. | +| state | `object` | A state object that was previously initialized by a call to [begin()](#begin). | -**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`C`> +**Returns:** `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> @@ -210,7 +261,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -245,7 +296,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L40)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -277,7 +328,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L55)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:95](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L95)* @@ -305,13 +356,13 @@ ___ ### «Protected» onRecognize -► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`string`⎮`undefined`> +► **onRecognize**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, options: *[PromptOptions](../interfaces/botbuilder_dialogs.promptoptions.md)*): `Promise`.<`O`⎮`undefined`> *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:56](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L56)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:96](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L96)* @@ -326,7 +377,7 @@ ___ -**Returns:** `Promise`.<`string`⎮`undefined`> +**Returns:** `Promise`.<`O`⎮`undefined`> diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.waterfall.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.waterfall.md index e7f8cd5fc8..13ecc5b400 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.waterfall.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.waterfall.md @@ -5,6 +5,8 @@ # Class: Waterfall +:package: **botbuilder-dialogs** + Dialog optimized for prompting a user with a series of questions. Waterfalls accept a stack of functions which will be executed in sequence. Each waterfall step can ask a question of the user and the users response will be passed as an argument to the next waterfall step. For simple text questions you can send the user a message and then process their answer in the next step: @@ -61,7 +63,7 @@ The example builds on the previous `namePrompt` sample and shows how you can cal You should generally call `dc.end()` or `dc.replace()` from your last waterfall step but if you fail to do that the dialog will be automatically ended for you on the users next reply. The users response will be passed to the calling dialogs next waterfall step if there is one. ## Type parameters -#### C : `BotContext` +#### C : `TurnContext` ## Implements * [Dialog](../interfaces/botbuilder_dialogs.dialog.md)`C` @@ -89,7 +91,7 @@ You should generally call `dc.end()` or `dc.replace()` from your last waterfall ### ⊕ **new Waterfall**(steps: *[WaterfallStep](../#waterfallstep)`C`[]*): [Waterfall](botbuilder_dialogs.waterfall.md) -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:125](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L125)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:131](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L131)* @@ -122,7 +124,7 @@ Creates a new waterfall dialog containing the given array of steps. *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogBegin](../interfaces/botbuilder_dialogs.dialog.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:131](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L131)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:137](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L137)* @@ -155,7 +157,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogContinue](../interfaces/botbuilder_dialogs.dialog.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:132](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L132)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:138](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L138)* @@ -187,7 +189,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogResume](../interfaces/botbuilder_dialogs.dialog.md#dialogresume)* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:133](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L133)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:139](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L139)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.choicepromptoptions.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.choicepromptoptions.md index 00995422da..2248012761 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.choicepromptoptions.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.choicepromptoptions.md @@ -5,6 +5,8 @@ # Interface: ChoicePromptOptions +:package: **botbuilder-dialogs** + Additional options that can be used to configure a `ChoicePrompt`. ## Hierarchy @@ -28,7 +30,7 @@ Additional options that can be used to configure a `ChoicePrompt`. **● choices**: *`any`[]* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:15](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L15)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L20)* @@ -47,7 +49,7 @@ ___ *Inherited from [PromptOptions](botbuilder_dialogs.promptoptions.md).[prompt](botbuilder_dialogs.promptoptions.md#prompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:14](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L14)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L19)* @@ -66,7 +68,7 @@ ___ *Inherited from [PromptOptions](botbuilder_dialogs.promptoptions.md).[retryPrompt](botbuilder_dialogs.promptoptions.md#retryprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:18](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L18)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L23)* @@ -85,7 +87,7 @@ ___ *Inherited from [PromptOptions](botbuilder_dialogs.promptoptions.md).[retrySpeak](botbuilder_dialogs.promptoptions.md#retryspeak)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L20)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L25)* @@ -104,7 +106,7 @@ ___ *Inherited from [PromptOptions](botbuilder_dialogs.promptoptions.md).[speak](botbuilder_dialogs.promptoptions.md#speak)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:16](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L16)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L21)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialog.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialog.md index 3d84a8beec..f29e7f24bd 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialog.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialog.md @@ -5,10 +5,15 @@ # Interface: Dialog +:package: **botbuilder-dialogs** + Interface of Dialog objects that can be added to a `DialogSet`. The dialog should generally be a singleton and added to a dialog set using `DialogSet.add()` at which point it will be assigned a unique ID. ## Type parameters -#### C : `BotContext` +#### C : `TurnContext` + +The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + ## Implemented by * [AttachmentPrompt](../classes/botbuilder_dialogs.attachmentprompt.md) @@ -18,6 +23,7 @@ Interface of Dialog objects that can be added to a `DialogSet`. The dialog shoul * [Control](../classes/botbuilder_dialogs.control.md) * [DatetimePrompt](../classes/botbuilder_dialogs.datetimeprompt.md) * [NumberPrompt](../classes/botbuilder_dialogs.numberprompt.md) +* [OAuthPrompt](../classes/botbuilder_dialogs.oauthprompt.md) * [Prompt](../classes/botbuilder_dialogs.prompt.md) * [TextPrompt](../classes/botbuilder_dialogs.textprompt.md) * [Waterfall](../classes/botbuilder_dialogs.waterfall.md) @@ -32,7 +38,7 @@ Interface of Dialog objects that can be added to a `DialogSet`. The dialog shoul -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialog.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialog.d.ts#L24)* @@ -66,7 +72,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:31](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialog.d.ts#L31)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialog.d.ts#L34)* @@ -101,7 +107,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:42](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialog.d.ts#L42)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:45](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialog.d.ts#L45)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialoginstance.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialoginstance.md index 642dc480e0..8af19b1add 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialoginstance.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialoginstance.md @@ -10,6 +10,9 @@ Tracking information for a dialog on the stack. ## Type parameters #### T : `any` +(Optional) type of state being persisted for dialog. + + ## Properties @@ -17,7 +20,7 @@ Tracking information for a dialog on the stack. **● id**: *`string`* -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:49](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialog.d.ts#L49)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:53](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialog.d.ts#L53)* @@ -34,7 +37,7 @@ ___ **● state**: *`T`* -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialog.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialog.d.ts#L55)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialogresult.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialogresult.md index 0e6657307a..326f8398a1 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialogresult.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialogresult.md @@ -5,6 +5,8 @@ # Interface: DialogResult +:package: **botbuilder-dialogs** + Result returned to the caller of one of the various stack manipulation methods and used to return the result from a final call to `DialogContext.end()` to the bots logic. ## Type parameters @@ -17,7 +19,7 @@ Result returned to the caller of one of the various stack manipulation methods a **● active**: *`boolean`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L19)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L21)* @@ -30,11 +32,11 @@ ___ -### «Optional» result +### result -**● result**: *`T`* +**● result**: *`T`⎮`undefined`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:29](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L29)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:31](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L31)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md new file mode 100644 index 0000000000..7b31cc7055 --- /dev/null +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md @@ -0,0 +1,44 @@ +[Bot Builder SDK - Dialogs](../README.md) > [OAuthPromptSettingsWithTimeout](../interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md) + + + +# Interface: OAuthPromptSettingsWithTimeout + + +:package: **botbuilder-dialogs** + +Settings used to configure an `OAuthPrompt` instance. Includes the ability to adjust the prompts timeout settings. + +## Hierarchy + + + `any` + +**↳ OAuthPromptSettingsWithTimeout** + + + + + + + + +## Properties + + +### «Optional» timeout + +**● timeout**: *`number`* + +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L24)* + + + +(Optional) number of milliseconds the prompt will wait for the user to authenticate. Defaults to a value `54,000,000` (15 minutes.) + + + + +___ + + diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.promptoptions.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.promptoptions.md index 5c44cb24cd..6e09474ad0 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.promptoptions.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.promptoptions.md @@ -5,6 +5,8 @@ # Interface: PromptOptions +:package: **botbuilder-dialogs** + Basic configuration options supported by all prompts. ## Hierarchy @@ -28,7 +30,7 @@ Basic configuration options supported by all prompts. **● prompt**: *`string`⎮`Partial`.<`Activity`>* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:14](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L14)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L19)* @@ -45,7 +47,7 @@ ___ **● retryPrompt**: *`string`⎮`Partial`.<`Activity`>* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:18](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L18)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L23)* @@ -62,7 +64,7 @@ ___ **● retrySpeak**: *`string`* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L20)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L25)* @@ -79,7 +81,7 @@ ___ **● speak**: *`string`* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:16](https://github.com/Microsoft/botbuilder-js/blob/f596b7c/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L16)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L21)* diff --git a/doc/botbuilder-prompts/README.md b/doc/botbuilder-prompts/README.md index bd435aef59..87908688bf 100644 --- a/doc/botbuilder-prompts/README.md +++ b/doc/botbuilder-prompts/README.md @@ -50,7 +50,7 @@ **Τ PromptValidator**: *`function`* -*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:66](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L66)* +*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:66](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L66)* @@ -97,7 +97,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts:84](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts#L84)* +*Defined in [libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts:84](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts#L84)* @@ -105,7 +105,7 @@ ___ Creates a new prompt that asks the user to upload one or more attachments. -**Usage Example** +**Usage Example:** const { createAttachmentPrompt } = require('botbuilder-prompts'); @@ -156,7 +156,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:119](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L119)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:119](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L119)* @@ -164,7 +164,7 @@ ___ Creates a new prompt that asks the user to select from a list of choices. -**Usage Example** +**Usage Example:** const { createChoicePrompt } = require('botbuilder-prompts'); @@ -209,7 +209,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:134](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L134)* +*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:134](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L134)* @@ -217,7 +217,7 @@ ___ Creates a new prompt that asks the user to answer a yes/no question. -**Usage Example** +**Usage Example:** const { createConfirmPrompt } = require('botbuilder-prompts'); @@ -262,7 +262,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:114](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L114)* +*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:114](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L114)* @@ -270,7 +270,7 @@ ___ Creates a new prompt that asks the user to reply with a date or time. -**Usage Example** +**Usage Example:** const { createDatetimePrompt } = require('botbuilder-prompts'); @@ -282,7 +282,7 @@ Creates a new prompt that asks the user to reply with a date or time. if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } return value; } catch (err) { - await context.sendActivity(`Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); + await timePrompt.prompt(context, `Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); return undefined; } }); @@ -321,7 +321,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/numberPrompt.d.ts:82](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/numberPrompt.d.ts#L82)* +*Defined in [libraries/botbuilder-prompts/lib/numberPrompt.d.ts:82](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/numberPrompt.d.ts#L82)* @@ -329,7 +329,7 @@ ___ Creates a new prompt that asks the user to reply with a number. -**Usage Example** +**Usage Example:** const { createNumberPrompt } = require('botbuilder-prompts'); @@ -378,7 +378,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:154](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L154)* +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:154](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L154)* @@ -386,7 +386,7 @@ ___ Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) service. -**Usage Example** +**Usage Example:** async function ensureLogin(context, state, botLogic) { const now = new Date().getTime(); @@ -449,7 +449,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:88](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L88)* +*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:88](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L88)* @@ -457,7 +457,7 @@ ___ Creates a new prompt that asks the user to enter some text. -**Usage Example** +**Usage Example:** const { createTextPrompt } = require('botbuilder-prompts'); diff --git a/doc/botbuilder-prompts/enums/botbuilder_prompts.liststyle.md b/doc/botbuilder-prompts/enums/botbuilder_prompts.liststyle.md index 4708acb4f6..8d6e4e20c6 100644 --- a/doc/botbuilder-prompts/enums/botbuilder_prompts.liststyle.md +++ b/doc/botbuilder-prompts/enums/botbuilder_prompts.liststyle.md @@ -29,7 +29,7 @@ Controls the way that choices for a `ChoicePrompt` or yes/no options for a `Conf ** auto**: = 1 -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L21)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L21)* @@ -46,7 +46,7 @@ ___ ** inline**: = 2 -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L23)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L23)* @@ -63,7 +63,7 @@ ___ ** list**: = 3 -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L25)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L25)* @@ -80,7 +80,7 @@ ___ ** none**: = 0 -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L19)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L19)* @@ -97,7 +97,7 @@ ___ ** suggestedAction**: = 4 -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L27)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L27)* diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.attachmentprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.attachmentprompt.md index 8b628c3506..07453800ef 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.attachmentprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.attachmentprompt.md @@ -9,7 +9,7 @@ Prompts the user to upload one or more attachments. -**Usage Example** +**Usage Example:** const { createAttachmentPrompt } = require('botbuilder-prompts'); @@ -30,13 +30,13 @@ Prompts the user to upload one or more attachments. -*Defined in [libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts#L37)* +*Defined in [libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts#L37)* Sends a formated prompt to the user. -**Usage Example** +**Usage Example:** await imagePrompt.prompt(context, `Upload an image(s).`); @@ -69,7 +69,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts#L55)* +*Defined in [libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts#L55)* @@ -77,7 +77,7 @@ Recognizes and validates the users reply. The result of the call will either be The recognize() method will not automatically re-prompt the user so either the caller or the prompts custom validator will need to implement re-prompting logic. -**Usage Example** +**Usage Example:** const images = await imagePrompt.recognize(context); if (images) { diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.choiceprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.choiceprompt.md index f42b1b03f1..e0b0ebd129 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.choiceprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.choiceprompt.md @@ -9,7 +9,7 @@ Prompts the user to select from a list of choices. -**Usage Example** +**Usage Example:** const { createChoicePrompt } = require('botbuilder-prompts'); @@ -28,7 +28,7 @@ Prompts the user to select from a list of choices. **● choiceOptions**: *[ChoiceFactoryOptions]()* -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:50](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L50)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:50](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L50)* @@ -45,7 +45,7 @@ ___ **● recognizerOptions**: *[FindChoicesOptions]()* -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L52)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L52)* @@ -62,7 +62,7 @@ ___ **● style**: *[ListStyle](../enums/botbuilder_prompts.liststyle.md)* -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:48](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L48)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:48](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L48)* @@ -83,7 +83,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:74](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L74)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:74](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L74)* @@ -93,7 +93,7 @@ By default, this will attempt to send the provided list of choices as buttons us Further tweaks can be made to the rendering of choices using the [choiceOptions](#choiceoptions) property. -**Usage Example** +**Usage Example:** await colorPrompt.prompt(context, ['red', 'green', 'blue'], `Pick a color.`); @@ -127,7 +127,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:96](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L96)* +*Defined in [libraries/botbuilder-prompts/lib/choicePrompt.d.ts:96](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/choicePrompt.d.ts#L96)* @@ -137,7 +137,7 @@ The recognize() method will not automatically re-prompt the user so either the c The search options for the underlying choice recognizer can be tweaked using the prompts [recognizerOptions](#recognizeroptions) property. -**Usage Example** +**Usage Example:** const choice = await colorPrompt.recognize(context, ['red', 'green', 'blue']); if (choice) { diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.confirmprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.confirmprompt.md index ac4b4ff31f..61526253c8 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.confirmprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.confirmprompt.md @@ -11,7 +11,7 @@ Prompts the user to answer a yes/no question. The [prompt()](#prompt) method will attempt to send a set of buttons yes/no buttons for the user to click. By default, the text of the titles for these buttons will always be in English but you can easily add support for other languages using the prompts [choices](#choices) property. -**Usage Example** +**Usage Example:** const { createConfirmPrompt } = require('botbuilder-prompts'); @@ -30,7 +30,7 @@ The [prompt()](#prompt) method will attempt to send a set of buttons yes/no butt **● choiceOptions**: *[ChoiceFactoryOptions]()* -*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L68)* +*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L68)* @@ -47,7 +47,7 @@ ___ **● choices**: *[ConfirmChoices](botbuilder_prompts.confirmchoices.md)* -*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:58](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L58)* +*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:58](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L58)* @@ -75,7 +75,7 @@ ___ **● style**: *[ListStyle](../enums/botbuilder_prompts.liststyle.md)* -*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:63](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L63)* +*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:63](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L63)* @@ -96,7 +96,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:89](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L89)* +*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:89](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L89)* @@ -106,7 +106,7 @@ By default, this will attempt to send the user yes & no choices as buttons using Further tweaks can be made to the rendering of the yes/no choices using the [choiceOptions](#choiceoptions) property. -**Usage Example** +**Usage Example:** await confirmPrompt.prompt(context, `This will cancel your order. Are you sure?`); @@ -139,7 +139,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:111](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L111)* +*Defined in [libraries/botbuilder-prompts/lib/confirmPrompt.d.ts:111](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts#L111)* @@ -147,7 +147,7 @@ Recognizes and validates the users reply. The result of the call will either be The recognize() method will not automatically re-prompt the user so either the caller or the prompts custom validator will need to implement re-prompting logic. -**Usage Example** +**Usage Example:** const confirmed = await confirmPrompt.recognize(context); if (typeof confirmed == 'boolean') { diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.datetimeprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.datetimeprompt.md index 3ea4c7b51c..fbe203095b 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.datetimeprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.datetimeprompt.md @@ -9,7 +9,7 @@ Prompts the user to reply with a date and/or time. The user can use natural language utterances like "tomorrow at 9am". -**Usage Example** +**Usage Example:** const { createDatetimePrompt } = require('botbuilder-prompts'); @@ -30,13 +30,13 @@ Prompts the user to reply with a date and/or time. The user can use natural lang -*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:60](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L60)* +*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:60](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L60)* Sends a formated prompt to the user. -**Usage Example** +**Usage Example:** await timePrompt.prompt(context, `What time should I set your alarm for?`); @@ -69,7 +69,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:85](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L85)* +*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:85](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L85)* @@ -77,7 +77,7 @@ Recognizes and validates the users reply. The result of the call will either be The recognize() method will not automatically re-prompt the user so either the caller or the prompts custom validator will need to implement re-prompting logic. -**Usage Example** +**Usage Example:** const values = await timePrompt.recognize(context); if (values && values.length > 0) { diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.founddatetime.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.founddatetime.md index 477bc45ffc..d07b44eba3 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.founddatetime.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.founddatetime.md @@ -17,7 +17,7 @@ Datetime result returned by `DatetimePrompt`. For more details see the LUIS docs **● timex**: *`string`* -*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L20)* +*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L20)* @@ -34,7 +34,7 @@ ___ **● type**: *`string`* -*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L25)* +*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L25)* @@ -51,7 +51,7 @@ ___ **● value**: *`string`* -*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:30](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L30)* +*Defined in [libraries/botbuilder-prompts/lib/datetimePrompt.d.ts:30](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts#L30)* diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.numberprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.numberprompt.md index 0834e85e60..399a9670df 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.numberprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.numberprompt.md @@ -9,7 +9,7 @@ Prompts the user to reply with a number. -**Usage Example** +**Usage Example:** const { createNumberPrompt } = require('botbuilder-prompts'); @@ -30,13 +30,13 @@ Prompts the user to reply with a number. -*Defined in [libraries/botbuilder-prompts/lib/numberPrompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/numberPrompt.d.ts#L37)* +*Defined in [libraries/botbuilder-prompts/lib/numberPrompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/numberPrompt.d.ts#L37)* Sends a formated prompt to the user. -**Usage Example** +**Usage Example:** await agePrompt.prompt(context, `How old are you?`); @@ -69,7 +69,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/numberPrompt.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/numberPrompt.d.ts#L55)* +*Defined in [libraries/botbuilder-prompts/lib/numberPrompt.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/numberPrompt.d.ts#L55)* @@ -77,7 +77,7 @@ Recognizes and validates the users reply. The result of the call will either be The recognize() method will not automatically re-prompt the user so either the caller or the prompts custom validator will need to implement re-prompting logic. -**Usage Example** +**Usage Example:** const age = await agePrompt.recognize(context); if (typeof age == 'number') { diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthprompt.md index d68176bca9..7090f032cd 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthprompt.md @@ -9,7 +9,7 @@ Prompts the user to sign in using the Bot Frameworks Single Sign On (SSO) service. -**Usage Example** +**Usage Example:** const { createOAuthPrompt } = require('botbuilder-prompts'); @@ -33,13 +33,13 @@ Prompts the user to sign in using the Bot Frameworks Single Sign On (SSO) servic -*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:101](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L101)* +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:101](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L101)* Attempts to retrieve the cached token for a signed in user. You will generally want to call this before calling [prompt()](#prompt) to send the user a signin card. -**Usage Example** +**Usage Example:** const token = await loginPrompt.getUserToken(context); if (!token) { @@ -73,7 +73,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:57](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L57)* +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:57](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L57)* @@ -81,7 +81,7 @@ Sends a formated prompt to the user. An `OAuthCard` will be automatically created and sent to the user requesting them to signin. If you need to localize the card or customize the message sent to the user for any reason you can pass in the `Activity` to send. This should just be an activity of type `message` and contain at least one attachment that's an `OAuthCard`. -**Usage Example** +**Usage Example:** await loginPrompt.prompt(context); @@ -113,7 +113,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:86](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L86)* +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:86](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L86)* @@ -126,7 +126,7 @@ The `recognize()` method automatically handles both flows for the bot but you sh You should also be prepared for the case where the user fails to enter the correct "magic code" or simply decides they don't want to click the signin button. -**Usage Example** +**Usage Example:** const token = await loginPrompt.recognize(context); if (token) { @@ -160,13 +160,13 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:112](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L112)* +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:112](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L112)* Signs the user out of the service. -**Usage Example** +**Usage Example:** await loginPrompt.signOutUser(context); diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthpromptsettings.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthpromptsettings.md index 98d435f812..af7d12ba50 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthpromptsettings.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.oauthpromptsettings.md @@ -17,7 +17,7 @@ Defines settings for an OAuthPrompt. **● connectionName**: *`string`* -*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:17](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L17)* +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:17](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L17)* @@ -34,7 +34,7 @@ ___ **● text**: *`undefined`⎮`string`* -*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L21)* +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L21)* @@ -51,7 +51,7 @@ ___ **● title**: *`string`* -*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L19)* +*Defined in [libraries/botbuilder-prompts/lib/oauthPrompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts#L19)* diff --git a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.textprompt.md b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.textprompt.md index 230c6b7c06..b355b531b7 100644 --- a/doc/botbuilder-prompts/interfaces/botbuilder_prompts.textprompt.md +++ b/doc/botbuilder-prompts/interfaces/botbuilder_prompts.textprompt.md @@ -9,7 +9,7 @@ Prompts the user to reply with some text. -**Usage Example** +**Usage Example:** const { createTextPrompt } = require('botbuilder-prompts'); @@ -30,15 +30,15 @@ Prompts the user to reply with some text. -*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L36)* +*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L36)* Sends a formated prompt to the user. -**Usage Example** +**Usage Example:** - await namePrompt.prompt(context, `What's name?`); + await namePrompt.prompt(context, `What's your name?`); **Parameters:** @@ -69,7 +69,7 @@ ___ -*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:54](https://github.com/Microsoft/botbuilder-js/blob/e54b802/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L54)* +*Defined in [libraries/botbuilder-prompts/lib/textPrompt.d.ts:54](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-prompts/lib/textPrompt.d.ts#L54)* @@ -77,7 +77,7 @@ Recognizes and validates the users reply. The result of the call will either be The recognize() method will not automatically re-prompt the user so either the caller or the prompts custom validator will need to implement re-prompting logic. -**Usage Example** +**Usage Example:** const name = await namePrompt.recognize(context); if (name) { diff --git a/libraries/botbuilder-dialogs/lib/compositeControl.d.ts b/libraries/botbuilder-dialogs/lib/compositeControl.d.ts index a946d4fd59..9d05e17d41 100644 --- a/libraries/botbuilder-dialogs/lib/compositeControl.d.ts +++ b/libraries/botbuilder-dialogs/lib/compositeControl.d.ts @@ -10,21 +10,163 @@ import { Dialog } from './dialog'; import { DialogContext, DialogResult } from './dialogContext'; import { DialogSet } from './dialogSet'; /** + * :package: **botbuilder-dialogs** * + * A `CompositeControl` makes it easy to take an existing set of dialogs and package them up as a + * control that can be used within another bot. The control can be used either as a dialog added + * to the other bots `DialogSet` or on its own for bots that are using some other conversation + * management system. + * + * ### Control Packaging + * + * You'll typically want to package your control as a new class derived from `CompositeControl`. + * Within your controls constructor you'll pass the `DialogSet` containing your controls dialogs + * and the `ID` of the initial dialog that should be started anytime a caller calls the dialog. + * + * If your control needs to be configured then you can pass through the configuration settings as + * a set of `defaultOptions` which will be merged with any options passed in by the caller when + * they call `begin()`. These will then be passed as arguments to the initial dialog that gets + * started. + * + * Here's a fairly simple example of a `ProfileControl` that's designed to prompt the user to + * enter their name and phone number which it will return as a JSON object to the caller: + * + * ```JavaScript + * const { CompositeControl, DialogSet, TextPrompt } = require('botbuilder-dialogs'); + * + * const dialogs = new DialogSet(); + * + * class ProfileControl extends CompositeControl { + * constructor() { + * super(dialogs, 'fillProfile'); + * } + * } + * module.exports.ProfileControl = ProfileControl; + * + * dialogs.add('fillProfile', [ + * async function (dc, options) { + * dc.instance.state = {}; + * return dc.prompt('textPrompt', `What's your name?`); + * }, + * async function (dc, name) { + * dc.instance.state.name = name; + * return dc.prompt('textPrompt', `What's your phone number?`); + * }, + * async function (dc, phone) { + * dc.instance.state.phone = phone; + * + * // Return completed profile + * return dc.end(dc.instance.state); + * } + * ]); + * + * dialogs.add('textPrompt', new TextPrompt()); + * ``` + * + * ### Consume as Dialog + * + * On the consumption side the control we created can be used by a bot in much the same way they + * would use any other prompt. They can add a new instance of the control as a named dialog to + * their bots `DialogSet` and then start it using a call to `DialogContext.begin()`. If the + * control accepts options these can be passed in to the `begin()` call as well. + * + * ```JavaScript + * const { DialogSet } = require('botbuilder-dialogs'); + * const { ProfileControl } = require('./profileControl'); + * + * const dialogs = new DialogSet(); + * + * dialogs.add('getProfile', new ProfileControl()); + * + * dialogs.add('firstrun', [ + * async function (dc) { + * await dc.context.sendActivity(`Welcome! We need to ask a few questions to get started.`); + * return dc.begin('getProfile'); + * }, + * async function (dc, profile) { + * await dc.context.sendActivity(`Thanks ${profile.name}!`); + * return dc.end(); + * } + * ]); + * ``` + * + * ### Control Usage + * + * If the consuming bot isn't dialog based they can still use your control. They will just need + * start the control from somewhere within their bots logic by calling the controls `begin()` + * method: + * + * ```JavaScript + * const state = {}; + * const control = new ProfileControl(); + * await prompt.begin(context, state); + * ``` + * + * The control will populate the `state` object passed in with information it needs to process + * the users response. This should be saved off with the bots conversation state as it needs to be + * passed into the controls `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const control = new ProfileControl(); + * const result = await control.continue(context, state); + * if (!result.active) { + * const profile = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the control is finished and then to access any results it might have returned. To interrupt or + * cancel the control simply delete the `state` object the bot has been persisting. + * @param R (Optional) type of result that's expected to be returned by the control. + * @param O (Optional) options that can be passed into the [begin()](#begin) method. */ -export declare class CompositeControl implements Dialog { - protected dialogs: DialogSet; +export declare class CompositeControl implements Dialog { + protected dialogs: DialogSet; protected dialogId: string; protected defaultOptions: O; /** - * Creates a new CompositeControl instance. + * Creates a new `CompositeControl` instance. * @param dialogs Controls dialog set. * @param dialogId ID of the root dialog that should be started anytime the control is started. * @param defaultOptions (Optional) set of default options that should be passed to controls root dialog. These will be merged with arguments passed in by the caller. */ - constructor(dialogs: DialogSet, dialogId: string, defaultOptions?: O); - begin(context: C, state: object, options?: O): Promise>; - continue(context: C, state: object): Promise>; - dialogBegin(dc: DialogContext, dialogArgs?: any): Promise; - dialogContinue(dc: DialogContext): Promise; + constructor(dialogs: DialogSet, dialogId: string, defaultOptions?: O); + /** + * Starts the control. Depending on the control, its possible for the control to finish + * immediately so it's advised to check the result object returned by `begin()` and ensure that + * the control is still active before continuing. + * + * **Usage Example:** + * + * ```JavaScript + * const state = {}; + * const result = await control.begin(context, state); + * if (!result.active) { + * const value = result.result; + * } + * ``` + * @param context Context for the current turn of the conversation with the user. + * @param state A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. + * @param options (Optional) additional options supported by the control. + */ + begin(context: TurnContext, state: object, options?: O): Promise>; + /** + * Passes a users reply to the control for further processing. The bot should keep calling + * `continue()` for future turns until the control returns a result with `Active == false`. + * To cancel or interrupt the prompt simply delete the `state` object being persisted. + * + * **Usage Example:** + * + * ```JavaScript + * const result = await control.continue(context, state); + * if (!result.active) { + * const value = result.result; + * } + * ``` + * @param context Context for the current turn of the conversation with the user. + * @param state A state object that was previously initialized by a call to [begin()](#begin). + */ + continue(context: TurnContext, state: object): Promise>; + dialogBegin(dc: DialogContext, dialogArgs?: any): Promise; + dialogContinue(dc: DialogContext): Promise; } diff --git a/libraries/botbuilder-dialogs/lib/compositeControl.js b/libraries/botbuilder-dialogs/lib/compositeControl.js index abdb3aab8b..866aabf09f 100644 --- a/libraries/botbuilder-dialogs/lib/compositeControl.js +++ b/libraries/botbuilder-dialogs/lib/compositeControl.js @@ -1,11 +1,119 @@ "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); /** + * :package: **botbuilder-dialogs** * + * A `CompositeControl` makes it easy to take an existing set of dialogs and package them up as a + * control that can be used within another bot. The control can be used either as a dialog added + * to the other bots `DialogSet` or on its own for bots that are using some other conversation + * management system. + * + * ### Control Packaging + * + * You'll typically want to package your control as a new class derived from `CompositeControl`. + * Within your controls constructor you'll pass the `DialogSet` containing your controls dialogs + * and the `ID` of the initial dialog that should be started anytime a caller calls the dialog. + * + * If your control needs to be configured then you can pass through the configuration settings as + * a set of `defaultOptions` which will be merged with any options passed in by the caller when + * they call `begin()`. These will then be passed as arguments to the initial dialog that gets + * started. + * + * Here's a fairly simple example of a `ProfileControl` that's designed to prompt the user to + * enter their name and phone number which it will return as a JSON object to the caller: + * + * ```JavaScript + * const { CompositeControl, DialogSet, TextPrompt } = require('botbuilder-dialogs'); + * + * const dialogs = new DialogSet(); + * + * class ProfileControl extends CompositeControl { + * constructor() { + * super(dialogs, 'fillProfile'); + * } + * } + * module.exports.ProfileControl = ProfileControl; + * + * dialogs.add('fillProfile', [ + * async function (dc, options) { + * dc.instance.state = {}; + * return dc.prompt('textPrompt', `What's your name?`); + * }, + * async function (dc, name) { + * dc.instance.state.name = name; + * return dc.prompt('textPrompt', `What's your phone number?`); + * }, + * async function (dc, phone) { + * dc.instance.state.phone = phone; + * + * // Return completed profile + * return dc.end(dc.instance.state); + * } + * ]); + * + * dialogs.add('textPrompt', new TextPrompt()); + * ``` + * + * ### Consume as Dialog + * + * On the consumption side the control we created can be used by a bot in much the same way they + * would use any other prompt. They can add a new instance of the control as a named dialog to + * their bots `DialogSet` and then start it using a call to `DialogContext.begin()`. If the + * control accepts options these can be passed in to the `begin()` call as well. + * + * ```JavaScript + * const { DialogSet } = require('botbuilder-dialogs'); + * const { ProfileControl } = require('./profileControl'); + * + * const dialogs = new DialogSet(); + * + * dialogs.add('getProfile', new ProfileControl()); + * + * dialogs.add('firstrun', [ + * async function (dc) { + * await dc.context.sendActivity(`Welcome! We need to ask a few questions to get started.`); + * return dc.begin('getProfile'); + * }, + * async function (dc, profile) { + * await dc.context.sendActivity(`Thanks ${profile.name}!`); + * return dc.end(); + * } + * ]); + * ``` + * + * ### Control Usage + * + * If the consuming bot isn't dialog based they can still use your control. They will just need + * start the control from somewhere within their bots logic by calling the controls `begin()` + * method: + * + * ```JavaScript + * const state = {}; + * const control = new ProfileControl(); + * await prompt.begin(context, state); + * ``` + * + * The control will populate the `state` object passed in with information it needs to process + * the users response. This should be saved off with the bots conversation state as it needs to be + * passed into the controls `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const control = new ProfileControl(); + * const result = await control.continue(context, state); + * if (!result.active) { + * const profile = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the control is finished and then to access any results it might have returned. To interrupt or + * cancel the control simply delete the `state` object the bot has been persisting. + * @param R (Optional) type of result that's expected to be returned by the control. + * @param O (Optional) options that can be passed into the [begin()](#begin) method. */ class CompositeControl { /** - * Creates a new CompositeControl instance. + * Creates a new `CompositeControl` instance. * @param dialogs Controls dialog set. * @param dialogId ID of the root dialog that should be started anytime the control is started. * @param defaultOptions (Optional) set of default options that should be passed to controls root dialog. These will be merged with arguments passed in by the caller. @@ -15,11 +123,45 @@ class CompositeControl { this.dialogId = dialogId; this.defaultOptions = defaultOptions; } + /** + * Starts the control. Depending on the control, its possible for the control to finish + * immediately so it's advised to check the result object returned by `begin()` and ensure that + * the control is still active before continuing. + * + * **Usage Example:** + * + * ```JavaScript + * const state = {}; + * const result = await control.begin(context, state); + * if (!result.active) { + * const value = result.result; + * } + * ``` + * @param context Context for the current turn of the conversation with the user. + * @param state A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. + * @param options (Optional) additional options supported by the control. + */ begin(context, state, options) { const cdc = this.dialogs.createContext(context, state); return cdc.begin(this.dialogId, Object.assign({}, this.defaultOptions, options)) .then(() => cdc.dialogResult); } + /** + * Passes a users reply to the control for further processing. The bot should keep calling + * `continue()` for future turns until the control returns a result with `Active == false`. + * To cancel or interrupt the prompt simply delete the `state` object being persisted. + * + * **Usage Example:** + * + * ```JavaScript + * const result = await control.continue(context, state); + * if (!result.active) { + * const value = result.result; + * } + * ``` + * @param context Context for the current turn of the conversation with the user. + * @param state A state object that was previously initialized by a call to [begin()](#begin). + */ continue(context, state) { const cdc = this.dialogs.createContext(context, state); return cdc.continue() diff --git a/libraries/botbuilder-dialogs/lib/compositeControl.js.map b/libraries/botbuilder-dialogs/lib/compositeControl.js.map index 130340f92f..a02ab1dc95 100644 --- a/libraries/botbuilder-dialogs/lib/compositeControl.js.map +++ b/libraries/botbuilder-dialogs/lib/compositeControl.js.map @@ -1 +1 @@ -{"version":3,"file":"compositeControl.js","sourceRoot":"","sources":["../src/compositeControl.ts"],"names":[],"mappings":";;AAaA;;GAEG;AACH;IAEI;;;;;OAKG;IACH,YAAsB,OAAqB,EAAY,QAAgB,EAAY,cAAkB;QAA/E,YAAO,GAAP,OAAO,CAAc;QAAY,aAAQ,GAAR,QAAQ,CAAQ;QAAY,mBAAc,GAAd,cAAc,CAAI;IAAI,CAAC;IAEnG,KAAK,CAAC,OAAU,EAAE,KAAa,EAAE,OAAW;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACvD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;aACrE,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;IAEM,QAAQ,CAAC,OAAU,EAAE,KAAa;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACvD,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE;aACV,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;IAEM,WAAW,CAAC,EAAoB,EAAE,UAAgB;QACrD,0CAA0C;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;YAC1F,mCAAmC;YACnC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3B,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;IAEM,cAAc,CAAC,EAAoB;QACtC,kCAAkC;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;YAC5B,mCAAmC;YACnC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3B,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;CACJ;AA3CD,4CA2CC"} \ No newline at end of file +{"version":3,"file":"compositeControl.js","sourceRoot":"","sources":["../src/compositeControl.ts"],"names":[],"mappings":";;AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8GG;AACH;IAEI;;;;;OAKG;IACH,YAAsB,OAA+B,EAAY,QAAgB,EAAY,cAAkB;QAAzF,YAAO,GAAP,OAAO,CAAwB;QAAY,aAAQ,GAAR,QAAQ,CAAQ;QAAY,mBAAc,GAAd,cAAc,CAAI;IAAI,CAAC;IAEpH;;;;;;;;;;;;;;;;;OAiBG;IACI,KAAK,CAAC,OAAoB,EAAE,KAAa,EAAE,OAAW;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACvD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;aACrE,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACI,QAAQ,CAAC,OAAoB,EAAE,KAAa;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACvD,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE;aACV,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;IAEM,WAAW,CAAC,EAA8B,EAAE,UAAgB;QAC/D,0CAA0C;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;YAC1F,mCAAmC;YACnC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3B,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;IAEM,cAAc,CAAC,EAA8B;QAChD,kCAAkC;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;YAC5B,mCAAmC;YACnC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3B,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;CACJ;AA7ED,4CA6EC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/control.d.ts b/libraries/botbuilder-dialogs/lib/control.d.ts index 8217d595c7..48c8e1c03e 100644 --- a/libraries/botbuilder-dialogs/lib/control.d.ts +++ b/libraries/botbuilder-dialogs/lib/control.d.ts @@ -9,16 +9,62 @@ import { TurnContext } from 'botbuilder'; import { Dialog } from './dialog'; import { DialogContext, DialogResult } from './dialogContext'; /** + * :package: **botbuilder-dialogs** * + * Base class for any dialog that wants to support being used as a dialog within a bots `DialogSet` + * or on its own as a control within a bot that uses an alternate conversation management system. + * + * The `Control` and `CompositeControl` classes are very similar in that they both add `begin()` + * and `continue()` methods which simplify consuming the control from a non-dialog based bot. The + * primary difference between the two classes is that the `CompositeControl` class is designed to + * bridge one `DialogSet` to another where the `Control` class assumes that the derived dialog can + * be used in complete isolation without the need for any other supporting dialogs. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param R (Optional) type of result that's expected to be returned by the control. + * @param O (Optional) options that can be passed into the [begin()](#begin) method. */ -export declare abstract class Control implements Dialog { +export declare abstract class Control implements Dialog { protected defaultOptions: O; /** * Creates a new Control instance. - * @param defaultOptions (Optional) set of default options that should be passed to controls root dialog. These will be merged with arguments passed in by the caller. + * @param defaultOptions (Optional) set of default options that should be passed to controls `dialogBegin()` method. These will be merged with arguments passed in by the caller. */ constructor(defaultOptions?: O); + /** + * Starts the control. Depending on the control, its possible for the control to finish + * immediately so it's advised to check the result object returned by `begin()` and ensure that + * the control is still active before continuing. + * + * **Usage Example:** + * + * ```JavaScript + * const state = {}; + * const result = await control.begin(context, state); + * if (!result.active) { + * const value = result.result; + * } + * ``` + * @param context Context for the current turn of the conversation with the user. + * @param state A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. + * @param options (Optional) additional options supported by the control. + */ begin(context: C, state: object, options?: O): Promise>; + /** + * Passes a users reply to the control for further processing. The bot should keep calling + * `continue()` for future turns until the control returns a result with `Active == false`. + * To cancel or interrupt the prompt simply delete the `state` object being persisted. + * + * **Usage Example:** + * + * ```JavaScript + * const result = await control.continue(context, state); + * if (!result.active) { + * const value = result.result; + * } + * ``` + * @param context Context for the current turn of the conversation with the user. + * @param state A state object that was previously initialized by a call to [begin()](#begin). + */ continue(context: C, state: object): Promise>; abstract dialogBegin(dc: DialogContext, dialogArgs?: any): Promise; } diff --git a/libraries/botbuilder-dialogs/lib/control.js b/libraries/botbuilder-dialogs/lib/control.js index 5f1d729404..d461411b02 100644 --- a/libraries/botbuilder-dialogs/lib/control.js +++ b/libraries/botbuilder-dialogs/lib/control.js @@ -2,16 +2,46 @@ Object.defineProperty(exports, "__esModule", { value: true }); const dialogSet_1 = require("./dialogSet"); /** + * :package: **botbuilder-dialogs** * + * Base class for any dialog that wants to support being used as a dialog within a bots `DialogSet` + * or on its own as a control within a bot that uses an alternate conversation management system. + * + * The `Control` and `CompositeControl` classes are very similar in that they both add `begin()` + * and `continue()` methods which simplify consuming the control from a non-dialog based bot. The + * primary difference between the two classes is that the `CompositeControl` class is designed to + * bridge one `DialogSet` to another where the `Control` class assumes that the derived dialog can + * be used in complete isolation without the need for any other supporting dialogs. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param R (Optional) type of result that's expected to be returned by the control. + * @param O (Optional) options that can be passed into the [begin()](#begin) method. */ class Control { /** * Creates a new Control instance. - * @param defaultOptions (Optional) set of default options that should be passed to controls root dialog. These will be merged with arguments passed in by the caller. + * @param defaultOptions (Optional) set of default options that should be passed to controls `dialogBegin()` method. These will be merged with arguments passed in by the caller. */ constructor(defaultOptions) { this.defaultOptions = defaultOptions; } + /** + * Starts the control. Depending on the control, its possible for the control to finish + * immediately so it's advised to check the result object returned by `begin()` and ensure that + * the control is still active before continuing. + * + * **Usage Example:** + * + * ```JavaScript + * const state = {}; + * const result = await control.begin(context, state); + * if (!result.active) { + * const value = result.result; + * } + * ``` + * @param context Context for the current turn of the conversation with the user. + * @param state A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. + * @param options (Optional) additional options supported by the control. + */ begin(context, state, options) { // Create empty dialog set and ourselves to it const dialogs = new dialogSet_1.DialogSet(); @@ -21,6 +51,22 @@ class Control { return cdc.begin('control', Object.assign({}, this.defaultOptions, options)) .then(() => cdc.dialogResult); } + /** + * Passes a users reply to the control for further processing. The bot should keep calling + * `continue()` for future turns until the control returns a result with `Active == false`. + * To cancel or interrupt the prompt simply delete the `state` object being persisted. + * + * **Usage Example:** + * + * ```JavaScript + * const result = await control.continue(context, state); + * if (!result.active) { + * const value = result.result; + * } + * ``` + * @param context Context for the current turn of the conversation with the user. + * @param state A state object that was previously initialized by a call to [begin()](#begin). + */ continue(context, state) { // Create empty dialog set and ourselves to it const dialogs = new dialogSet_1.DialogSet(); diff --git a/libraries/botbuilder-dialogs/lib/control.js.map b/libraries/botbuilder-dialogs/lib/control.js.map index 5d4fdb4f4b..64a8c98d8a 100644 --- a/libraries/botbuilder-dialogs/lib/control.js.map +++ b/libraries/botbuilder-dialogs/lib/control.js.map @@ -1 +1 @@ -{"version":3,"file":"control.js","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":";;AAUA,2CAAwC;AAExC;;GAEG;AACH;IAEI;;;OAGG;IACH,YAAsB,cAAkB;QAAlB,mBAAc,GAAd,cAAc,CAAI;IAAI,CAAC;IAEtC,KAAK,CAAC,OAAU,EAAE,KAAa,EAAE,OAAW;QAC/C,8CAA8C;QAC9C,MAAM,OAAO,GAAG,IAAI,qBAAS,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAE7B,oBAAoB;QACpB,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;aACjE,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;IAEM,QAAQ,CAAC,OAAU,EAAE,KAAa;QACrC,8CAA8C;QAC9C,MAAM,OAAO,GAAG,IAAI,qBAAS,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAE7B,uBAAuB;QACvB,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE;aACV,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;CAGJ;AA/BD,0BA+BC"} \ No newline at end of file +{"version":3,"file":"control.js","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":";;AAUA,2CAAwC;AAExC;;;;;;;;;;;;;;GAcG;AACH;IAEI;;;OAGG;IACH,YAAsB,cAAkB;QAAlB,mBAAc,GAAd,cAAc,CAAI;IAAI,CAAC;IAE7C;;;;;;;;;;;;;;;;;OAiBG;IACI,KAAK,CAAC,OAAU,EAAE,KAAa,EAAE,OAAW;QAC/C,8CAA8C;QAC9C,MAAM,OAAO,GAAG,IAAI,qBAAS,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAE7B,oBAAoB;QACpB,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;aACjE,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACI,QAAQ,CAAC,OAAU,EAAE,KAAa;QACrC,8CAA8C;QAC9C,MAAM,OAAO,GAAG,IAAI,qBAAS,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAE7B,uBAAuB;QACvB,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE;aACV,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;CAGJ;AAjED,0BAiEC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/dialog.d.ts b/libraries/botbuilder-dialogs/lib/dialog.d.ts index fa4242538f..a467df44b2 100644 --- a/libraries/botbuilder-dialogs/lib/dialog.d.ts +++ b/libraries/botbuilder-dialogs/lib/dialog.d.ts @@ -8,9 +8,12 @@ import { TurnContext, Promiseable } from 'botbuilder'; import { DialogContext } from './dialogContext'; /** + * :package: **botbuilder-dialogs** + * * Interface of Dialog objects that can be added to a `DialogSet`. The dialog should generally * be a singleton and added to a dialog set using `DialogSet.add()` at which point it will be * assigned a unique ID. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. */ export interface Dialog { /** @@ -43,6 +46,7 @@ export interface Dialog { } /** * Tracking information for a dialog on the stack. + * @param T (Optional) type of state being persisted for dialog. */ export interface DialogInstance { /** ID of the dialog this instance is for. */ diff --git a/libraries/botbuilder-dialogs/lib/dialogContext.d.ts b/libraries/botbuilder-dialogs/lib/dialogContext.d.ts index 6bb339c1aa..e4868b00b9 100644 --- a/libraries/botbuilder-dialogs/lib/dialogContext.d.ts +++ b/libraries/botbuilder-dialogs/lib/dialogContext.d.ts @@ -11,6 +11,8 @@ import { DialogSet } from './dialogSet'; import { PromptOptions } from './prompts/index'; import { Choice } from 'botbuilder-prompts'; /** + * :package: **botbuilder-dialogs** + * * Result returned to the caller of one of the various stack manipulation methods and used to * return the result from a final call to `DialogContext.end()` to the bots logic. */ @@ -28,6 +30,12 @@ export interface DialogResult { */ result: T | undefined; } +/** + * :package: **botbuilder-dialogs** + * + * + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + */ export declare class DialogContext { readonly dialogs: DialogSet; readonly context: C; diff --git a/libraries/botbuilder-dialogs/lib/dialogContext.js b/libraries/botbuilder-dialogs/lib/dialogContext.js index 0bdcc38d49..40db5456e7 100644 --- a/libraries/botbuilder-dialogs/lib/dialogContext.js +++ b/libraries/botbuilder-dialogs/lib/dialogContext.js @@ -1,5 +1,11 @@ "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); +/** + * :package: **botbuilder-dialogs** + * + * + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + */ class DialogContext { /** * Creates a new DialogContext instance. diff --git a/libraries/botbuilder-dialogs/lib/dialogContext.js.map b/libraries/botbuilder-dialogs/lib/dialogContext.js.map index dd03011b1d..3ea73c1c2d 100644 --- a/libraries/botbuilder-dialogs/lib/dialogContext.js.map +++ b/libraries/botbuilder-dialogs/lib/dialogContext.js.map @@ -1 +1 @@ -{"version":3,"file":"dialogContext.js","sourceRoot":"","sources":["../src/dialogContext.ts"],"names":[],"mappings":"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"} \ No newline at end of file +{"version":3,"file":"dialogContext.js","sourceRoot":"","sources":["../src/dialogContext.ts"],"names":[],"mappings":";;AAmCA;;;;;GAKG;AACH;IAGK;;;;;OAKG;IACJ,YAA4B,OAAqB,EAAkB,OAAU,EAAkB,KAAuB;QAA1F,YAAO,GAAP,OAAO,CAAc;QAAkB,YAAO,GAAP,OAAO,CAAG;QAAkB,UAAK,GAAL,KAAK,CAAkB;QAR9G,gBAAW,GAAQ,SAAS,CAAC;IAQqF,CAAC;IAE3H,qHAAqH;IACrH,IAAW,QAAQ;QACf,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACjF,CAAC;IAED;;;OAGG;IACH,IAAW,YAAY;QACnB,MAAM,CAAC;YACH,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;YAC7B,MAAM,EAAE,IAAI,CAAC,WAAW;SAC3B,CAAC;IACN,CAAC;IAED;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,QAAgB,EAAE,UAAgB;QAC3C,IAAI,CAAC;YACD,gBAAgB;YAChB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC3C,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;gBAAC,MAAM,IAAI,KAAK,CAAC,kDAAkD,QAAQ,iBAAiB,CAAC,CAAA;YAAC,CAAC;YAE7G,iCAAiC;YACjC,MAAM,QAAQ,GAAwB;gBAClC,EAAE,EAAE,QAAQ;gBACZ,KAAK,EAAE,EAAE;aACZ,CAAC;YACF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAE1B,+BAA+B;YAC/B,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;QACjE,CAAC;QAAC,KAAK,CAAA,CAAC,GAAG,CAAC,CAAC,CAAC;YACV,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACI,MAAM,CAA0C,QAAgB,EAAE,MAAgC,EAAE,gBAAsC,EAAE,OAAW;QAC1J,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,gBAAgB,EAAE,OAAO,CAAM,CAAC;QACjI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;YAAC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QAAC,CAAC;QACpC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACI,QAAQ;QACX,IAAI,CAAC;YACD,kCAAkC;YAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC/B,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAEX,gBAAgB;gBAChB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;gBAC9C,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;oBAAC,MAAM,IAAI,KAAK,CAAC,wEAAwE,QAAQ,CAAC,EAAE,iBAAiB,CAAC,CAAA;gBAAC,CAAC;gBAEtI,6CAA6C;gBAC7C,EAAE,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;oBACxB,+BAA+B;oBAC/B,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;gBACxD,CAAC;gBAAC,IAAI,CAAC,CAAC;oBACJ,sBAAsB;oBACtB,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;gBACtB,CAAC;YACL,CAAC;YAAC,IAAI,CAAC,CAAC;gBACJ,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAC7B,CAAC;QACL,CAAC;QAAC,KAAK,CAAA,CAAC,GAAG,CAAC,CAAC,CAAC;YACV,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACI,GAAG,CAAC,MAAY;QACnB,IAAI,CAAC;YACD,kCAAkC;YAClC,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;gBAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAA;YAAC,CAAC;YAE/C,yBAAyB;YACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC/B,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAEX,gBAAgB;gBAChB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;gBAC9C,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;oBAAC,MAAM,IAAI,KAAK,CAAC,8EAA8E,QAAQ,CAAC,EAAE,iBAAiB,CAAC,CAAA;gBAAC,CAAC;gBAE5I,iDAAiD;gBACjD,EAAE,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;oBACtB,mCAAmC;oBACnC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;gBAC9D,CAAC;gBAAC,IAAI,CAAC,CAAC;oBACJ,uDAAuD;oBACvD,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBAC5B,CAAC;YACL,CAAC;YAAC,IAAI,CAAC,CAAC;gBACJ,wBAAwB;gBACxB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC;gBAC1B,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAC7B,CAAC;QACL,CAAC;QAAC,KAAK,CAAA,CAAC,GAAG,CAAC,CAAC,CAAC;YACV,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACI,MAAM;QACT,4BAA4B;QAC5B,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;YACxB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5C,CAAC;QACD,MAAM,CAAC,IAAI,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,OAAO,CAAC,QAAgB,EAAE,UAAgB;QAC7C,YAAY;QACZ,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;YAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAA;QAAC,CAAC;QAE/C,2BAA2B;QAC3B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC5C,CAAC;CACJ;AA9ND,sCA8NC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/dialogSet.d.ts b/libraries/botbuilder-dialogs/lib/dialogSet.d.ts index 1064094bb3..0d28504e79 100644 --- a/libraries/botbuilder-dialogs/lib/dialogSet.d.ts +++ b/libraries/botbuilder-dialogs/lib/dialogSet.d.ts @@ -10,37 +10,95 @@ import { Dialog } from './dialog'; import { Waterfall, WaterfallStep } from './waterfall'; import { DialogContext } from './dialogContext'; /** + * :package: **botbuilder-dialogs** + * * A related set of dialogs that can all call each other. * - * **Example usage:** + * ### Overview + * + * The dialogs library uses a stack based metaphor to manage a bot conversation with a user. In + * this model the bt begins dialogs to prompt the user for information. Those dialogs will + * typically call prompts to actually ask the user for information. A variety of typed prompts are + * provided and are themselves just other dialogs. When a prompt recognizes a users input as being + * valid, it will end itself and return the users input to the dialog that started it. That dialog + * is then free to either process the users input or ask the user for more information by pushing + * other dialogs/prompts onto the stack. Below is a simple `Waterfall` dialog that asks the user + * for their name and phone number: * * ```JavaScript - * const { Bot, MemoryStorage, BotStateManager } = require('botbuilder'); - * const { ConsoleAdapter } = require('botbuilder-node'); - * const { DialogSet } = require('botbuilder-dialogs'); + * const { DialogSet, TextPrompt } = require('botbuilder-dialogs'); * * const dialogs = new DialogSet(); * - * dialogs.add('greeting', [ - * function (context) { - * context.reply(`Hello... I'm a bot :)`); - * return dialogs.end(context); - * } + * dialogs.add('fillProfile', [ + * async function (dc, options) { + * dc.instance.state = {}; + * return dc.prompt('textPrompt', `What's your name?`); + * }, + * async function (dc, name) { + * dc.instance.state.name = name; + * return dc.prompt('textPrompt', `What's your phone number?`); + * }, + * async function (dc, phone) { + * dc.instance.state.phone = phone; + * + * // Return completed profile + * return dc.end(dc.instance.state); + * } * ]); * - * const adapter = new ConsoleAdapter().listen(); - * const bot = new Bot(adapter) - * .use(new MemoryStorage()) - * .use(new BotStateManager()) - * .onReceive((context) => { - * return dialogs.continue(context).then(() => { - * // If nothing has responded start greeting dialog - * if (!context.responded) { - * return dialogs.begin(context, 'greeting'); - * } - * }); - * }); + * dialogs.add('textPrompt', new TextPrompt()); + * ``` + * + * At first glance it probably looks like we're making this simple task of asking the user two + * questions way harder then it needs to be. It turns out though that asking a user even one + * question is a really hard problem. The primary issues coming from the fact that a) your bot will + * likely be running across multiple compute nodes and the node that asked the user a question may + * not be the one that receives their answer. and b) it could be minutes, hours, days, or even + * weeks before the user replies to the bot. Your bots compute process could have been restarted + * or updated any number of times before the user replies to the last question. + * + * The dialogs library addresses both of those issues by having you statically define and + * explicitly name all of your bots dialogs on startups. It then uses a persisted dialog stack to + * essentially maintain a program pointer so that any time a message is received from a user it can + * identify the function it should run to process that message in a deterministic way. + * + * ### Routing Requests + * + * To run the 'fillProfile' dialog above we need to add a bit of fairly boilerplate code to + * our bots routing logic: + * + * ```JavaScript + * server.post('/api/messages', (req, res) => { + * adapter.processActivity(req, res, async (context) => { + * // Continue execution if there's a "current" dialog + * const state = conversationState.get(context); + * const dc = dialogs.createContext(context, state); + * await dc.continue(); + * if (!context.responded && context.activity.type === ActivityType.Message) { + * // No active dialogs so start 'fillProfile' dialog + * await dc.begin('fillProfile'); + * } + * }); + * }); * ``` + * + * This code results in a bot that loops over prompting the user to fill out their profile so + * while not overly useful it does serve as a good starting point for understanding how to route + * request to your bots dialogs. + * + * The code first creates a `DialogContext` and then calls `dc.continue()` which will route the + * request to the "current" dialog on the top of the stack, if there is one. It's using + * `context.responded` to determine if anything processed the request which is reasonable given + * that as a best practice your bot should always reply to any message received from the user. So + * if nothing has responded and we've received a `message` activity we'll start the 'fillProfile' + * by calling `dc.begin()`. + * + * ### Detecting Interruptions + * + * + * + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. */ export declare class DialogSet { private readonly dialogs; @@ -51,13 +109,12 @@ export declare class DialogSet { * * ```JavaScript * dialogs.add('greeting', [ - * function (context, user) { - * context.reply(`Hello ${user.name}... I'm a bot :)`); - * return dialogs.end(context); + * async function (dc) { + * await dc.context.sendActivity(`Hello world!`); + * return dc.end(); * } * ]); * ``` - * @param T Type of the dialog being set and returned. * @param dialogId Unique ID of the dialog within the set. * @param dialogOrSteps Either a new dialog or an array of waterfall steps to execute. If waterfall steps are passed in they will automatically be passed into an new instance of a `Waterfall` class. */ diff --git a/libraries/botbuilder-dialogs/lib/dialogSet.js b/libraries/botbuilder-dialogs/lib/dialogSet.js index 2c0956c64d..5f1729f1a8 100644 --- a/libraries/botbuilder-dialogs/lib/dialogSet.js +++ b/libraries/botbuilder-dialogs/lib/dialogSet.js @@ -3,37 +3,95 @@ Object.defineProperty(exports, "__esModule", { value: true }); const waterfall_1 = require("./waterfall"); const dialogContext_1 = require("./dialogContext"); /** + * :package: **botbuilder-dialogs** + * * A related set of dialogs that can all call each other. * - * **Example usage:** + * ### Overview + * + * The dialogs library uses a stack based metaphor to manage a bot conversation with a user. In + * this model the bt begins dialogs to prompt the user for information. Those dialogs will + * typically call prompts to actually ask the user for information. A variety of typed prompts are + * provided and are themselves just other dialogs. When a prompt recognizes a users input as being + * valid, it will end itself and return the users input to the dialog that started it. That dialog + * is then free to either process the users input or ask the user for more information by pushing + * other dialogs/prompts onto the stack. Below is a simple `Waterfall` dialog that asks the user + * for their name and phone number: * * ```JavaScript - * const { Bot, MemoryStorage, BotStateManager } = require('botbuilder'); - * const { ConsoleAdapter } = require('botbuilder-node'); - * const { DialogSet } = require('botbuilder-dialogs'); + * const { DialogSet, TextPrompt } = require('botbuilder-dialogs'); * * const dialogs = new DialogSet(); * - * dialogs.add('greeting', [ - * function (context) { - * context.reply(`Hello... I'm a bot :)`); - * return dialogs.end(context); - * } + * dialogs.add('fillProfile', [ + * async function (dc, options) { + * dc.instance.state = {}; + * return dc.prompt('textPrompt', `What's your name?`); + * }, + * async function (dc, name) { + * dc.instance.state.name = name; + * return dc.prompt('textPrompt', `What's your phone number?`); + * }, + * async function (dc, phone) { + * dc.instance.state.phone = phone; + * + * // Return completed profile + * return dc.end(dc.instance.state); + * } * ]); * - * const adapter = new ConsoleAdapter().listen(); - * const bot = new Bot(adapter) - * .use(new MemoryStorage()) - * .use(new BotStateManager()) - * .onReceive((context) => { - * return dialogs.continue(context).then(() => { - * // If nothing has responded start greeting dialog - * if (!context.responded) { - * return dialogs.begin(context, 'greeting'); - * } - * }); - * }); + * dialogs.add('textPrompt', new TextPrompt()); + * ``` + * + * At first glance it probably looks like we're making this simple task of asking the user two + * questions way harder then it needs to be. It turns out though that asking a user even one + * question is a really hard problem. The primary issues coming from the fact that a) your bot will + * likely be running across multiple compute nodes and the node that asked the user a question may + * not be the one that receives their answer. and b) it could be minutes, hours, days, or even + * weeks before the user replies to the bot. Your bots compute process could have been restarted + * or updated any number of times before the user replies to the last question. + * + * The dialogs library addresses both of those issues by having you statically define and + * explicitly name all of your bots dialogs on startups. It then uses a persisted dialog stack to + * essentially maintain a program pointer so that any time a message is received from a user it can + * identify the function it should run to process that message in a deterministic way. + * + * ### Routing Requests + * + * To run the 'fillProfile' dialog above we need to add a bit of fairly boilerplate code to + * our bots routing logic: + * + * ```JavaScript + * server.post('/api/messages', (req, res) => { + * adapter.processActivity(req, res, async (context) => { + * // Continue execution if there's a "current" dialog + * const state = conversationState.get(context); + * const dc = dialogs.createContext(context, state); + * await dc.continue(); + * if (!context.responded && context.activity.type === ActivityType.Message) { + * // No active dialogs so start 'fillProfile' dialog + * await dc.begin('fillProfile'); + * } + * }); + * }); * ``` + * + * This code results in a bot that loops over prompting the user to fill out their profile so + * while not overly useful it does serve as a good starting point for understanding how to route + * request to your bots dialogs. + * + * The code first creates a `DialogContext` and then calls `dc.continue()` which will route the + * request to the "current" dialog on the top of the stack, if there is one. It's using + * `context.responded` to determine if anything processed the request which is reasonable given + * that as a best practice your bot should always reply to any message received from the user. So + * if nothing has responded and we've received a `message` activity we'll start the 'fillProfile' + * by calling `dc.begin()`. + * + * ### Detecting Interruptions + * + * + * + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. */ class DialogSet { constructor() { diff --git a/libraries/botbuilder-dialogs/lib/dialogSet.js.map b/libraries/botbuilder-dialogs/lib/dialogSet.js.map index 3727ab53c5..5f9def65e1 100644 --- a/libraries/botbuilder-dialogs/lib/dialogSet.js.map +++ b/libraries/botbuilder-dialogs/lib/dialogSet.js.map @@ -1 +1 @@ -{"version":3,"file":"dialogSet.js","sourceRoot":"","sources":["../src/dialogSet.ts"],"names":[],"mappings":";;AASA,2CAAuD;AACvD,mDAAgD;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAAA;QACqB,YAAO,GAAgC,EAAE,CAAC;IA6C/D,CAAC;IAxBU,GAAG,CAAC,QAAgB,EAAE,aAA2C;QACpE,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAAC,MAAM,IAAI,KAAK,CAAC,4CAA4C,QAAQ,kBAAkB,CAAC,CAAA;QAAC,CAAC;QACtI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,qBAAS,CAAC,aAAoB,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;IACvH,CAAC;IAEM,aAAa,CAAC,OAAU,EAAE,KAAa;QAC1C,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;YAAC,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,CAAA;QAAC,CAAC;QACvE,MAAM,CAAC,IAAI,6BAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;IAClE,CAAC;IAED;;;;;;;;;;OAUG;IACI,IAAI,CAAkC,QAAgB;QACzD,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3F,CAAC;CACJ;AA9CD,8BA8CC"} \ No newline at end of file +{"version":3,"file":"dialogSet.js","sourceRoot":"","sources":["../src/dialogSet.ts"],"names":[],"mappings":";;AASA,2CAAuD;AACvD,mDAAgD;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH;IAAA;QACqB,YAAO,GAAgC,EAAE,CAAC;IA4C/D,CAAC;IAxBU,GAAG,CAAC,QAAgB,EAAE,aAA2C;QACpE,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAAC,MAAM,IAAI,KAAK,CAAC,4CAA4C,QAAQ,kBAAkB,CAAC,CAAA;QAAC,CAAC;QACtI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,qBAAS,CAAC,aAAoB,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;IACvH,CAAC;IAEM,aAAa,CAAC,OAAU,EAAE,KAAa;QAC1C,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;YAAC,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,CAAA;QAAC,CAAC;QACvE,MAAM,CAAC,IAAI,6BAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;IAClE,CAAC;IAED;;;;;;;;;;OAUG;IACI,IAAI,CAAkC,QAAgB;QACzD,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3F,CAAC;CACJ;AA7CD,8BA6CC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts index b2edcf2437..e17407499e 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts @@ -10,10 +10,20 @@ import { PromptValidator } from 'botbuilder-prompts'; import { DialogContext } from '../dialogContext'; import { Prompt, PromptOptions } from './prompt'; /** + * :package: **botbuilder-dialogs** + * * Prompts a user to upload attachments like images. By default the prompt will return to the * calling dialog a `Attachment[]` but this can be overridden using a custom `PromptValidator`. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to upload one or + * more attachments which will be passed as an argument to the callers next waterfall step: * * ```JavaScript * const { DialogSet, AttachmentPrompt } = require('botbuilder-dialogs'); @@ -32,24 +42,71 @@ import { Prompt, PromptOptions } from './prompt'; * } * ]); * ``` + * + * If the users response to the prompt fails to be recognized they will be automatically re-prompted + * to try again. By default the original prompt is re-sent to the user but you can provide an + * alternate prompt to send by passing in additional options: + * + * ```JavaScript + * return dc.prompt('attachmentPrompt', `Send me image(s)`, { retryPrompt: `I didn't get anything. Send me an image.` }); + * ``` + * + * The prompts retry logic can also be completely customized by passing the prompts constructor a + * custom validator: + * + * ```JavaScript + * dialogs.add('imagePrompt', new AttachmentPrompt(async (context, values) => { + * if (values && values.length > 0) { + * for (let i = 0; i < values.length; i++) { + * if (!values[i].contentType.startsWith('image')) { + * await context.sendActivity(`Only images are accepted.`); + * return undefined; + * } + * } + * } else { + * await context.sendActivity(`Please upload at least one image.`); + * } + * return values; + * })); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new AttachmentPrompt(); + * await prompt.begin(context, state, { + * prompt: `Send me image(s)`, + * retryPrompt: `I didn't get anything. Send me an image.` + * }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new AttachmentPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const attachments = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to an `Attachment[]` but can be changed by a custom validator passed to the prompt. */ export declare class AttachmentPrompt extends Prompt { private prompt; /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('imagePrompt', new AttachmentPrompt(async (context, values) => { - * if (!Array.isArray(values) || values.length < 1) { - * await context.sendActivity(`Send me an image or say "cancel".`); - * return undefined; - * } else { - * return values; - * } - * })); - * ``` + * Creates a new `AttachmentPrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. */ constructor(validator?: PromptValidator); diff --git a/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.js b/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.js index 5b917528c0..41e23d02b0 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.js @@ -3,10 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true }); const prompt_1 = require("./prompt"); const prompts = require("botbuilder-prompts"); /** + * :package: **botbuilder-dialogs** + * * Prompts a user to upload attachments like images. By default the prompt will return to the * calling dialog a `Attachment[]` but this can be overridden using a custom `PromptValidator`. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to upload one or + * more attachments which will be passed as an argument to the callers next waterfall step: * * ```JavaScript * const { DialogSet, AttachmentPrompt } = require('botbuilder-dialogs'); @@ -25,23 +35,70 @@ const prompts = require("botbuilder-prompts"); * } * ]); * ``` + * + * If the users response to the prompt fails to be recognized they will be automatically re-prompted + * to try again. By default the original prompt is re-sent to the user but you can provide an + * alternate prompt to send by passing in additional options: + * + * ```JavaScript + * return dc.prompt('attachmentPrompt', `Send me image(s)`, { retryPrompt: `I didn't get anything. Send me an image.` }); + * ``` + * + * The prompts retry logic can also be completely customized by passing the prompts constructor a + * custom validator: + * + * ```JavaScript + * dialogs.add('imagePrompt', new AttachmentPrompt(async (context, values) => { + * if (values && values.length > 0) { + * for (let i = 0; i < values.length; i++) { + * if (!values[i].contentType.startsWith('image')) { + * await context.sendActivity(`Only images are accepted.`); + * return undefined; + * } + * } + * } else { + * await context.sendActivity(`Please upload at least one image.`); + * } + * return values; + * })); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new AttachmentPrompt(); + * await prompt.begin(context, state, { + * prompt: `Send me image(s)`, + * retryPrompt: `I didn't get anything. Send me an image.` + * }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new AttachmentPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const attachments = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to an `Attachment[]` but can be changed by a custom validator passed to the prompt. */ class AttachmentPrompt extends prompt_1.Prompt { /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('imagePrompt', new AttachmentPrompt(async (context, values) => { - * if (!Array.isArray(values) || values.length < 1) { - * await context.sendActivity(`Send me an image or say "cancel".`); - * return undefined; - * } else { - * return values; - * } - * })); - * ``` + * Creates a new `AttachmentPrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. */ constructor(validator) { diff --git a/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.js.map b/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.js.map index 8a6d4ba429..eea4f71ad2 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.js.map +++ b/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"attachmentPrompt.js","sourceRoot":"","sources":["../../src/prompts/attachmentPrompt.ts"],"names":[],"mappings":";;AAUA,qCAAiD;AACjD,8CAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,sBAAuE,SAAQ,eAAS;IAGpF;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,SAA4C;QACpD,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IACnD,CAAC;IAES,QAAQ,CAAC,EAAoB,EAAE,OAAsB,EAAE,OAAgB;QAC7E,EAAE,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACnF,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAES,WAAW,CAAC,EAAoB,EAAE,OAAsB;QAC9D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;CACJ;AArCD,4CAqCC"} \ No newline at end of file +{"version":3,"file":"attachmentPrompt.js","sourceRoot":"","sources":["../../src/prompts/attachmentPrompt.ts"],"names":[],"mappings":";;AAUA,qCAAiD;AACjD,8CAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AACH,sBAAuE,SAAQ,eAAS;IAGpF;;;OAGG;IACH,YAAY,SAA4C;QACpD,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IACnD,CAAC;IAES,QAAQ,CAAC,EAAoB,EAAE,OAAsB,EAAE,OAAgB;QAC7E,EAAE,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACnF,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAES,WAAW,CAAC,EAAoB,EAAE,OAAsB;QAC9D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;CACJ;AAxBD,4CAwBC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts index 2336b9ed0d..a2d24b697c 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts @@ -10,16 +10,30 @@ import { PromptValidator } from 'botbuilder-prompts'; import { DialogContext } from '../dialogContext'; import { Prompt, PromptOptions } from './prompt'; import * as prompts from 'botbuilder-prompts'; -/** Additional options that can be used to configure a `ChoicePrompt`. */ +/** + * :package: **botbuilder-dialogs** + * + * Additional options that can be used to configure a `ChoicePrompt`. + */ export interface ChoicePromptOptions extends PromptOptions { /** List of choices to recognize. */ choices?: (string | prompts.Choice)[]; } /** + * :package: **botbuilder-dialogs** + * * Prompts a user to confirm something with a yes/no response. By default the prompt will return * to the calling dialog a `boolean` representing the users selection. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to select a choice + * from a list and their choice will be passed as an argument to the callers next waterfall step: * * ```JavaScript * const { DialogSet, ChoicePrompt } = require('botbuilder-dialogs'); @@ -28,34 +42,64 @@ export interface ChoicePromptOptions extends PromptOptions { * * dialogs.add('choicePrompt', new ChoicePrompt()); * - * dialogs.add('choiceDemo', [ + * dialogs.add('colorPrompt', [ * async function (dc) { - * return dc.prompt('choicePrompt', `choice: select a color`, ['red', 'green', 'blue']); + * return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue']); * }, * async function (dc, choice) { - * await dc.context.sendActivity(`Recognized choice: ${JSON.stringify(choice)}`); + * const color = choice.value; + * await dc.context.sendActivity(`I like ${color} too!`); * return dc.end(); * } * ]); * ``` + * + * If the users response to the prompt fails to be recognized they will be automatically re-prompted + * to try again. By default the original prompt is re-sent to the user but you can provide an + * alternate prompt to send by passing in additional options: + * + * ```JavaScript + * return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue'], { retryPrompt: `I didn't catch that. Select a color from the list.` }); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new ChoicePrompt(); + * await prompt.begin(context, state, { + * choices: ['red', 'green', 'blue'], + * prompt: `Select a color`, + * retryPrompt: `I didn't catch that. Select a color from the list.` + * }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new ChoicePrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const color = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to an instance of `FoundChoice` but can be changed by a custom validator passed to the prompt. */ export declare class ChoicePrompt extends Prompt { private prompt; /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('choicePrompt', new ChoicePrompt(async (context, value) => { - * if (value === undefined) { - * await context.sendActivity(`I didn't recognize your choice. Please select from the choices on the list.`); - * return undefined; - * } else { - * return value; - * } - * })); - * ``` + * Creates a new `ChoicePrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.js b/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.js index 2832baa316..dd60380a6e 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.js @@ -3,10 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true }); const prompt_1 = require("./prompt"); const prompts = require("botbuilder-prompts"); /** + * :package: **botbuilder-dialogs** + * * Prompts a user to confirm something with a yes/no response. By default the prompt will return * to the calling dialog a `boolean` representing the users selection. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to select a choice + * from a list and their choice will be passed as an argument to the callers next waterfall step: * * ```JavaScript * const { DialogSet, ChoicePrompt } = require('botbuilder-dialogs'); @@ -15,33 +25,63 @@ const prompts = require("botbuilder-prompts"); * * dialogs.add('choicePrompt', new ChoicePrompt()); * - * dialogs.add('choiceDemo', [ + * dialogs.add('colorPrompt', [ * async function (dc) { - * return dc.prompt('choicePrompt', `choice: select a color`, ['red', 'green', 'blue']); + * return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue']); * }, * async function (dc, choice) { - * await dc.context.sendActivity(`Recognized choice: ${JSON.stringify(choice)}`); + * const color = choice.value; + * await dc.context.sendActivity(`I like ${color} too!`); * return dc.end(); * } * ]); * ``` + * + * If the users response to the prompt fails to be recognized they will be automatically re-prompted + * to try again. By default the original prompt is re-sent to the user but you can provide an + * alternate prompt to send by passing in additional options: + * + * ```JavaScript + * return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue'], { retryPrompt: `I didn't catch that. Select a color from the list.` }); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new ChoicePrompt(); + * await prompt.begin(context, state, { + * choices: ['red', 'green', 'blue'], + * prompt: `Select a color`, + * retryPrompt: `I didn't catch that. Select a color from the list.` + * }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new ChoicePrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const color = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to an instance of `FoundChoice` but can be changed by a custom validator passed to the prompt. */ class ChoicePrompt extends prompt_1.Prompt { /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('choicePrompt', new ChoicePrompt(async (context, value) => { - * if (value === undefined) { - * await context.sendActivity(`I didn't recognize your choice. Please select from the choices on the list.`); - * return undefined; - * } else { - * return value; - * } - * })); - * ``` + * Creates a new `ChoicePrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.js.map b/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.js.map index 10a048fea3..944d0a025b 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.js.map +++ b/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"choicePrompt.js","sourceRoot":"","sources":["../../src/prompts/choicePrompt.ts"],"names":[],"mappings":";;AAUA,qCAAiD;AACjD,8CAA8C;AAQ9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,kBAA0E,SAAQ,eAAS;IAGvF;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,SAAmD,EAAE,aAAsB;QACnF,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACvE,CAAC;IAED;;;;OAIG;IACI,aAAa,CAAC,OAAqC;QACtD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAClD,MAAM,CAAC,IAAI,CAAC;IAChB,CAAC;IAED;;;OAGG;IACI,iBAAiB,CAAC,OAAmC;QACxD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;QACtD,MAAM,CAAC,IAAI,CAAC;IAChB,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,SAA4B;QACrC,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,SAAS,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC;IAChB,CAAC;IAES,QAAQ,CAAC,EAAoB,EAAE,OAA4B,EAAE,OAAgB;QACnF,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,EAAE,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QAC5F,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAClF,CAAC;IAES,WAAW,CAAC,EAAoB,EAAE,OAA4B;QACpE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9D,CAAC;CACJ;AAjED,oCAiEC"} \ No newline at end of file +{"version":3,"file":"choicePrompt.js","sourceRoot":"","sources":["../../src/prompts/choicePrompt.ts"],"names":[],"mappings":";;AAUA,qCAAiD;AACjD,8CAA8C;AAY9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,kBAA0E,SAAQ,eAAS;IAGvF;;;;OAIG;IACH,YAAY,SAAmD,EAAE,aAAsB;QACnF,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACvE,CAAC;IAED;;;;OAIG;IACI,aAAa,CAAC,OAAqC;QACtD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAClD,MAAM,CAAC,IAAI,CAAC;IAChB,CAAC;IAED;;;OAGG;IACI,iBAAiB,CAAC,OAAmC;QACxD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;QACtD,MAAM,CAAC,IAAI,CAAC;IAChB,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,SAA4B;QACrC,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,SAAS,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC;IAChB,CAAC;IAES,QAAQ,CAAC,EAAoB,EAAE,OAA4B,EAAE,OAAgB;QACnF,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,EAAE,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QAC5F,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAClF,CAAC;IAES,WAAW,CAAC,EAAoB,EAAE,OAA4B;QACpE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9D,CAAC;CACJ;AApDD,oCAoDC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts index f4c180fe6b..7408b3eea5 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts @@ -11,10 +11,21 @@ import { DialogContext } from '../dialogContext'; import { Prompt, PromptOptions } from './prompt'; import * as prompts from 'botbuilder-prompts'; /** + * :package: **botbuilder-dialogs** + * * Prompts a user to confirm something with a yes/no response. By default the prompt will return * to the calling dialog a `boolean` representing the users selection. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to answer a + * `yes/no` or `true/false` question and the users response will be passed as an argument to the + * callers next waterfall step: * * ```JavaScript * const { DialogSet, ConfirmPrompt } = require('botbuilder-dialogs'); @@ -23,16 +34,71 @@ import * as prompts from 'botbuilder-prompts'; * * dialogs.add('confirmPrompt', new ConfirmPrompt()); * - * dialogs.add('confirmDemo', [ + * dialogs.add('confirmCancel', [ * async function (dc) { - * return dc.prompt('confirmPrompt', `confirm: answer "yes" or "no"`); + * return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`); * }, - * async function (dc, value) { - * await dc.context.sendActivity(`Recognized value: ${value}`); + * async function (dc, cancel) { + * if (cancel) { + * await dc.context.sendActivity(`Order cancelled.`); + * } * return dc.end(); * } * ]); * ``` + * + * If the users response to the prompt fails to be recognized they will be automatically re-prompted + * to try again. By default the original prompt is re-sent to the user but you can provide an + * alternate prompt to send by passing in additional options: + * + * ```JavaScript + * return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`, { retryPrompt: `Please answer "yes" or "no".` }); + * ``` + * + * The prompts retry logic can also be completely customized by passing the prompts constructor a + * custom validator: + * + * ```JavaScript + * dialogs.add('confirmPrompt', new ConfirmPrompt(async (context, value) => { + * if (typeof confirmed != 'boolean') { + * await context.sendActivity(`Please answer "yes" or "no".`); + * } + * return confirmed; + * })); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new ConfirmPrompt(); + * await prompt.begin(context, state, { + * prompt: `This will cancel your order. Are you sure?`, + * retryPrompt: `Please answer "yes" or "no".` + * }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new ConfirmPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const cancelOrder = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to a boolean `true` or `false` but can be changed by a custom validator passed to the prompt. */ export declare class ConfirmPrompt extends Prompt { private prompt; @@ -44,28 +110,20 @@ export declare class ConfirmPrompt extends P * **Example usage:** * * ```JavaScript + * const confirmPrompt = new ConfirmPrompt(); + * * // Configure yes/no choices for english and spanish (default) - * ConfirmPrompt.choices['*'] = ['sí', 'no']; - * ConfirmPrompt.choices['es'] = ['sí', 'no']; - * ConfirmPrompt.choices['en-us'] = ['yes', 'no']; + * confirmPrompt.choices['*'] = ['sí', 'no']; + * confirmPrompt.choices['es'] = ['sí', 'no']; + * confirmPrompt.choices['en-us'] = ['yes', 'no']; + * + * // Add to dialogs + * dialogs.add('confirmPrompt', confirmPrompt); * ``` */ static choices: prompts.ConfirmChoices; /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('confirmPrompt', new ConfirmPrompt(async (context, value) => { - * if (value === undefined) { - * await context.sendActivity(`Invalid answer. Answer with "yes" or "no".`); - * return undefined; - * } else { - * return value; - * } - * })); - * ``` + * Creates a new `ConfirmPrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. */ @@ -73,7 +131,7 @@ export declare class ConfirmPrompt extends P /** * Sets additional options passed to the `ChoiceFactory` and used to tweak the style of choices * rendered to the user. - * @param options Additional options to set. + * @param options Additional options to set. Defaults to `{ includeNumbers: false }` */ choiceOptions(options: prompts.ChoiceFactoryOptions): this; /** diff --git a/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.js b/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.js index 707a169568..bdb1cf7667 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.js @@ -3,10 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true }); const prompt_1 = require("./prompt"); const prompts = require("botbuilder-prompts"); /** + * :package: **botbuilder-dialogs** + * * Prompts a user to confirm something with a yes/no response. By default the prompt will return * to the calling dialog a `boolean` representing the users selection. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to answer a + * `yes/no` or `true/false` question and the users response will be passed as an argument to the + * callers next waterfall step: * * ```JavaScript * const { DialogSet, ConfirmPrompt } = require('botbuilder-dialogs'); @@ -15,33 +26,75 @@ const prompts = require("botbuilder-prompts"); * * dialogs.add('confirmPrompt', new ConfirmPrompt()); * - * dialogs.add('confirmDemo', [ + * dialogs.add('confirmCancel', [ * async function (dc) { - * return dc.prompt('confirmPrompt', `confirm: answer "yes" or "no"`); + * return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`); * }, - * async function (dc, value) { - * await dc.context.sendActivity(`Recognized value: ${value}`); + * async function (dc, cancel) { + * if (cancel) { + * await dc.context.sendActivity(`Order cancelled.`); + * } * return dc.end(); * } * ]); * ``` + * + * If the users response to the prompt fails to be recognized they will be automatically re-prompted + * to try again. By default the original prompt is re-sent to the user but you can provide an + * alternate prompt to send by passing in additional options: + * + * ```JavaScript + * return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`, { retryPrompt: `Please answer "yes" or "no".` }); + * ``` + * + * The prompts retry logic can also be completely customized by passing the prompts constructor a + * custom validator: + * + * ```JavaScript + * dialogs.add('confirmPrompt', new ConfirmPrompt(async (context, value) => { + * if (typeof confirmed != 'boolean') { + * await context.sendActivity(`Please answer "yes" or "no".`); + * } + * return confirmed; + * })); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new ConfirmPrompt(); + * await prompt.begin(context, state, { + * prompt: `This will cancel your order. Are you sure?`, + * retryPrompt: `Please answer "yes" or "no".` + * }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new ConfirmPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const cancelOrder = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to a boolean `true` or `false` but can be changed by a custom validator passed to the prompt. */ class ConfirmPrompt extends prompt_1.Prompt { /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('confirmPrompt', new ConfirmPrompt(async (context, value) => { - * if (value === undefined) { - * await context.sendActivity(`Invalid answer. Answer with "yes" or "no".`); - * return undefined; - * } else { - * return value; - * } - * })); - * ``` + * Creates a new `ConfirmPrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. */ @@ -53,7 +106,7 @@ class ConfirmPrompt extends prompt_1.Prompt { /** * Sets additional options passed to the `ChoiceFactory` and used to tweak the style of choices * rendered to the user. - * @param options Additional options to set. + * @param options Additional options to set. Defaults to `{ includeNumbers: false }` */ choiceOptions(options) { Object.assign(this.prompt.choiceOptions, options); @@ -88,10 +141,15 @@ class ConfirmPrompt extends prompt_1.Prompt { * **Example usage:** * * ```JavaScript + * const confirmPrompt = new ConfirmPrompt(); + * * // Configure yes/no choices for english and spanish (default) - * ConfirmPrompt.choices['*'] = ['sí', 'no']; - * ConfirmPrompt.choices['es'] = ['sí', 'no']; - * ConfirmPrompt.choices['en-us'] = ['yes', 'no']; + * confirmPrompt.choices['*'] = ['sí', 'no']; + * confirmPrompt.choices['es'] = ['sí', 'no']; + * confirmPrompt.choices['en-us'] = ['yes', 'no']; + * + * // Add to dialogs + * dialogs.add('confirmPrompt', confirmPrompt); * ``` */ ConfirmPrompt.choices = { '*': ['yes', 'no'] }; diff --git a/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.js.map b/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.js.map index c151c1ff24..c99cf95426 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.js.map +++ b/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"confirmPrompt.js","sourceRoot":"","sources":["../../src/prompts/confirmPrompt.ts"],"names":[],"mappings":";;AAUA,qCAAiD;AACjD,8CAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,mBAA+D,SAAQ,eAAS;IAmB5E;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,SAAuC,EAAE,aAAsB;QACvE,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;QACpE,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC;IAChD,CAAC;IAED;;;;OAIG;IACI,aAAa,CAAC,OAAqC;QACtD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAClD,MAAM,CAAC,IAAI,CAAC;IAChB,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,SAA4B;QACrC,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,SAAS,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC;IAChB,CAAC;IAES,QAAQ,CAAC,EAAoB,EAAE,OAAsB,EAAE,OAAgB;QAC7E,EAAE,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACnF,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAES,WAAW,CAAC,EAAoB,EAAE,OAAsB;QAC9D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;;AAtED;;;;;;;;;;;;;GAaG;AACI,qBAAO,GAA2B,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;AAjBpE,sCA0EC"} \ No newline at end of file +{"version":3,"file":"confirmPrompt.js","sourceRoot":"","sources":["../../src/prompts/confirmPrompt.ts"],"names":[],"mappings":";;AAUA,qCAAiD;AACjD,8CAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;AACH,mBAA+D,SAAQ,eAAS;IAwB5E;;;;OAIG;IACH,YAAY,SAAuC,EAAE,aAAsB;QACvE,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;QACpE,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC;IAChD,CAAC;IAED;;;;OAIG;IACI,aAAa,CAAC,OAAqC;QACtD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAClD,MAAM,CAAC,IAAI,CAAC;IAChB,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,SAA4B;QACrC,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,SAAS,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC;IAChB,CAAC;IAES,QAAQ,CAAC,EAAoB,EAAE,OAAsB,EAAE,OAAgB;QAC7E,EAAE,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACnF,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAES,WAAW,CAAC,EAAoB,EAAE,OAAsB;QAC9D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;;AA9DD;;;;;;;;;;;;;;;;;;GAkBG;AACI,qBAAO,GAA2B,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;AAtBpE,sCAkEC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts index 0a7c2fe865..2898e588a1 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts @@ -11,50 +11,87 @@ import { DialogContext } from '../dialogContext'; import { Prompt, PromptOptions } from './prompt'; import * as prompts from 'botbuilder-prompts'; /** + * :package: **botbuilder-dialogs** + * * Prompts a user to enter a datetime expression. By default the prompt will return to the * calling dialog a `FoundDatetime[]` but this can be overridden using a custom `PromptValidator`. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to reply with a + * date and/or time. The recognized date/time will be passed as an argument to the callers next + * waterfall step: * * ```JavaScript * const { DialogSet, DatetimePrompt } = require('botbuilder-dialogs'); * * const dialogs = new DialogSet(); * - * dialogs.add('datetimePrompt', new DatetimePrompt()); + * dialogs.add('datetimePrompt', new DatetimePrompt(AlarmTimeValidator)); * - * dialogs.add('datetimeDemo', [ + * dialogs.add('setAlarmTime', [ * async function (dc) { - * return dc.prompt('datetimePrompt', `datetime: enter a datetime`); + * return dc.prompt('datetimePrompt', `What time should I set your alarm for?`); * }, - * async function (dc, values) { - * await dc.context.sendActivity(`Recognized values: ${JSON.stringify(values)}`); + * async function (dc, time) { + * await dc.context.sendActivity(`Alarm time set`); * return dc.end(); * } * ]); + * + * async function AlarmTimeValidator(context, values) { + * try { + * if (!Array.isArray(values) || values.length < 0) { throw new Error('missing time') } + * if (values[0].type !== 'datetime') { throw new Error('unsupported type') } + * const value = new Date(values[0].value); + * if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } + * return value; + * } catch (err) { + * await context.sendActivity(`Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); + * return undefined; + * } + * } + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new DatetimePrompt(AlarmTimeValidator); + * await prompt.begin(context, state, { prompt: `What time should I set your alarm for?` }); * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new ConfirmPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const time = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to a `FoundDatetime[]` but can be changed by a custom validator passed to the prompt. */ export declare class DatetimePrompt extends Prompt { private prompt; /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('timePrompt', new DatetimePrompt(async (context, values) => { - * try { - * if (!Array.isArray(values) || values.length < 0) { throw new Error('missing time') } - * if (values[0].type !== 'datetime') { throw new Error('unsupported type') } - * const value = new Date(values[0].value); - * if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } - * return value; - * } catch (err) { - * await context.sendActivity(`Invalid time. Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); - * return undefined; - * } - * })); - * ``` + * Creates a new `DatetimePrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.js b/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.js index 0b3ab60ec3..df78a7b488 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.js @@ -3,49 +3,86 @@ Object.defineProperty(exports, "__esModule", { value: true }); const prompt_1 = require("./prompt"); const prompts = require("botbuilder-prompts"); /** + * :package: **botbuilder-dialogs** + * * Prompts a user to enter a datetime expression. By default the prompt will return to the * calling dialog a `FoundDatetime[]` but this can be overridden using a custom `PromptValidator`. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to reply with a + * date and/or time. The recognized date/time will be passed as an argument to the callers next + * waterfall step: * * ```JavaScript * const { DialogSet, DatetimePrompt } = require('botbuilder-dialogs'); * * const dialogs = new DialogSet(); * - * dialogs.add('datetimePrompt', new DatetimePrompt()); + * dialogs.add('datetimePrompt', new DatetimePrompt(AlarmTimeValidator)); * - * dialogs.add('datetimeDemo', [ + * dialogs.add('setAlarmTime', [ * async function (dc) { - * return dc.prompt('datetimePrompt', `datetime: enter a datetime`); + * return dc.prompt('datetimePrompt', `What time should I set your alarm for?`); * }, - * async function (dc, values) { - * await dc.context.sendActivity(`Recognized values: ${JSON.stringify(values)}`); + * async function (dc, time) { + * await dc.context.sendActivity(`Alarm time set`); * return dc.end(); * } * ]); + * + * async function AlarmTimeValidator(context, values) { + * try { + * if (!Array.isArray(values) || values.length < 0) { throw new Error('missing time') } + * if (values[0].type !== 'datetime') { throw new Error('unsupported type') } + * const value = new Date(values[0].value); + * if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } + * return value; + * } catch (err) { + * await context.sendActivity(`Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); + * return undefined; + * } + * } + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new DatetimePrompt(AlarmTimeValidator); + * await prompt.begin(context, state, { prompt: `What time should I set your alarm for?` }); * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new ConfirmPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const time = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to a `FoundDatetime[]` but can be changed by a custom validator passed to the prompt. */ class DatetimePrompt extends prompt_1.Prompt { /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('timePrompt', new DatetimePrompt(async (context, values) => { - * try { - * if (!Array.isArray(values) || values.length < 0) { throw new Error('missing time') } - * if (values[0].type !== 'datetime') { throw new Error('unsupported type') } - * const value = new Date(values[0].value); - * if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } - * return value; - * } catch (err) { - * await context.sendActivity(`Invalid time. Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); - * return undefined; - * } - * })); - * ``` + * Creates a new `DatetimePrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.js.map b/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.js.map index 796500d285..670764e9eb 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.js.map +++ b/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"datetimePrompt.js","sourceRoot":"","sources":["../../src/prompts/datetimePrompt.ts"],"names":[],"mappings":";;AAUA,qCAAiD;AACjD,8CAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,oBAAgF,SAAQ,eAAS;IAG7F;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,YAAY,SAAuD,EAAE,aAAsB;QACvF,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACzE,CAAC;IAES,QAAQ,CAAC,EAAoB,EAAE,OAAsB,EAAE,OAAgB;QAC7E,EAAE,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACnF,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAES,WAAW,CAAC,EAAoB,EAAE,OAAsB;QAC9D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;CACJ;AA1CD,wCA0CC"} \ No newline at end of file +{"version":3,"file":"datetimePrompt.js","sourceRoot":"","sources":["../../src/prompts/datetimePrompt.ts"],"names":[],"mappings":";;AAUA,qCAAiD;AACjD,8CAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,oBAAgF,SAAQ,eAAS;IAG7F;;;;OAIG;IACH,YAAY,SAAuD,EAAE,aAAsB;QACvF,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACzE,CAAC;IAES,QAAQ,CAAC,EAAoB,EAAE,OAAsB,EAAE,OAAgB;QAC7E,EAAE,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACnF,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAES,WAAW,CAAC,EAAoB,EAAE,OAAsB;QAC9D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;CACJ;AAzBD,wCAyBC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts index 951ee1feca..f8f828298e 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts @@ -10,46 +10,96 @@ import { PromptValidator } from 'botbuilder-prompts'; import { DialogContext } from '../dialogContext'; import { Prompt, PromptOptions } from './prompt'; /** + * :package: **botbuilder-dialogs** + * * Prompts a user to enter a number. By default the prompt will return to the calling dialog * a `number` representing the users input. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to reply with a + * number which will be passed as an argument to the callers next waterfall step: * * ```JavaScript * const { DialogSet, NumberPrompt } = require('botbuilder-dialogs'); * * const dialogs = new DialogSet(); * - * dialogs.add('numberPrompt', new NumberPrompt()); + * dialogs.add('agePrompt', new NumberPrompt()); * - * dialogs.add('numberDemo', [ + * dialogs.add('askAge', [ * async function (dc) { - * return dc.prompt('numberPrompt', `number: enter a number`); + * return dc.prompt('agePrompt', `How old are you?`); * }, - * async function (dc, value) { - * await dc.context.sendActivity(`Recognized value: ${value}`); + * async function (dc, age) { + * if (age < 40) { + * await dc.context.sendActivity(`So young :)`); + * } else { + * await dc.context.sendActivity(`I hear ${age} is the new ${age - 10} :)`); + * } * return dc.end(); * } * ]); * ``` + * + * The prompt can be configured with a custom validator to perform additional checks like ensuring + * that the user responds with a valid age and that only whole numbers are returned: + * + * ```JavaScript + * dialogs.add('agePrompt', new NumberPrompt(async (context, value) => { + * if (typeof value == 'number') { + * if (value >= 1 && value < 111) { + * // Return age rounded down to nearest whole number. + * return Math.floor(value); + * } + * } + * await context.sendActivity(`Please enter a number between 1 and 110 or say "cancel".`); + * return undefined; + * })); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new NumberPrompt(); + * await prompt.begin(context, state, { + * prompt: `How old are you?`, + * retryPrompt: `Please reply with a valid number like "23".` + * }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new ConfirmPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const age = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to a `number` but can be changed by a custom validator passed to the prompt. */ export declare class NumberPrompt extends Prompt { private prompt; /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('agePrompt', new NumberPrompt(async (context, value) => { - * if (value === undefined || value < 1 || value > 110) { - * await context.sendActivity(`Invalid age. Only ages between 1 and 110 are allowed.`); - * return undefined; - * } else { - * return value; - * } - * })); - * ``` + * Creates a new `NumberPrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.js b/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.js index 2a1926f28c..c744b8c928 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.js @@ -3,45 +3,95 @@ Object.defineProperty(exports, "__esModule", { value: true }); const prompt_1 = require("./prompt"); const prompts = require("botbuilder-prompts"); /** + * :package: **botbuilder-dialogs** + * * Prompts a user to enter a number. By default the prompt will return to the calling dialog * a `number` representing the users input. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to reply with a + * number which will be passed as an argument to the callers next waterfall step: * * ```JavaScript * const { DialogSet, NumberPrompt } = require('botbuilder-dialogs'); * * const dialogs = new DialogSet(); * - * dialogs.add('numberPrompt', new NumberPrompt()); + * dialogs.add('agePrompt', new NumberPrompt()); * - * dialogs.add('numberDemo', [ + * dialogs.add('askAge', [ * async function (dc) { - * return dc.prompt('numberPrompt', `number: enter a number`); + * return dc.prompt('agePrompt', `How old are you?`); * }, - * async function (dc, value) { - * await dc.context.sendActivity(`Recognized value: ${value}`); + * async function (dc, age) { + * if (age < 40) { + * await dc.context.sendActivity(`So young :)`); + * } else { + * await dc.context.sendActivity(`I hear ${age} is the new ${age - 10} :)`); + * } * return dc.end(); * } * ]); * ``` + * + * The prompt can be configured with a custom validator to perform additional checks like ensuring + * that the user responds with a valid age and that only whole numbers are returned: + * + * ```JavaScript + * dialogs.add('agePrompt', new NumberPrompt(async (context, value) => { + * if (typeof value == 'number') { + * if (value >= 1 && value < 111) { + * // Return age rounded down to nearest whole number. + * return Math.floor(value); + * } + * } + * await context.sendActivity(`Please enter a number between 1 and 110 or say "cancel".`); + * return undefined; + * })); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new NumberPrompt(); + * await prompt.begin(context, state, { + * prompt: `How old are you?`, + * retryPrompt: `Please reply with a valid number like "23".` + * }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new ConfirmPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const age = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to a `number` but can be changed by a custom validator passed to the prompt. */ class NumberPrompt extends prompt_1.Prompt { /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('agePrompt', new NumberPrompt(async (context, value) => { - * if (value === undefined || value < 1 || value > 110) { - * await context.sendActivity(`Invalid age. Only ages between 1 and 110 are allowed.`); - * return undefined; - * } else { - * return value; - * } - * })); - * ``` + * Creates a new `NumberPrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.js.map b/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.js.map index ca2bd14510..928e4d08ab 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.js.map +++ b/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"numberPrompt.js","sourceRoot":"","sources":["../../src/prompts/numberPrompt.ts"],"names":[],"mappings":";;AAUA,qCAAiD;AACjD,8CAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,kBAA6D,SAAQ,eAAS;IAG1E;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,SAAsC,EAAE,aAAsB;QACtE,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACvE,CAAC;IAES,QAAQ,CAAC,EAAoB,EAAE,OAAsB,EAAE,OAAgB;QAC7E,EAAE,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACnF,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAES,WAAW,CAAC,EAAoB,EAAE,OAAsB;QAC9D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;CACJ;AAtCD,oCAsCC"} \ No newline at end of file +{"version":3,"file":"numberPrompt.js","sourceRoot":"","sources":["../../src/prompts/numberPrompt.ts"],"names":[],"mappings":";;AAUA,qCAAiD;AACjD,8CAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,kBAA6D,SAAQ,eAAS;IAG1E;;;;OAIG;IACH,YAAY,SAAsC,EAAE,aAAsB;QACtE,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACvE,CAAC;IAES,QAAQ,CAAC,EAAoB,EAAE,OAAsB,EAAE,OAAgB;QAC7E,EAAE,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACnF,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAES,WAAW,CAAC,EAAoB,EAAE,OAAsB;QAC9D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;CACJ;AAzBD,oCAyBC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts index b8dc1ab6c4..509d4a78ef 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts @@ -10,6 +10,12 @@ import * as prompts from 'botbuilder-prompts'; import { DialogContext } from '../dialogContext'; import { Control } from '../control'; import { PromptOptions } from './prompt'; +/** + * :package: **botbuilder-dialogs** + * + * Settings used to configure an `OAuthPrompt` instance. Includes the ability to adjust the prompts + * timeout settings. + */ export interface OAuthPromptSettingsWithTimeout extends prompts.OAuthPromptSettings { /** * (Optional) number of milliseconds the prompt will wait for the user to authenticate. @@ -17,11 +23,128 @@ export interface OAuthPromptSettingsWithTimeout extends prompts.OAuthPromptSetti */ timeout?: number; } +/** + * :package: **botbuilder-dialogs** + * + * Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) + * service. The prompt will attempt to retrieve the users current token and if the user isn't + * signed in, it will send them an `OAuthCard` containing a button they can press to signin. + * Depending on the channel, the user will be sent through one of two possible signin flows: + * + * - The automatic signin flow where once the user signs in and the SSO service will forward the bot + * the users access token using either an `event` or `invoke` activity. + * - The "magic code" flow where where once the user signs in they will be prompted by the SSO + * service to send the bot a six digit code confirming their identity. This code will be sent as a + * standard `message` activity. + * + * Both flows are automatically supported by the `OAuthPrompt` and the only thing you need to be + * careful of is that you don't block the `event` and `invoke` activities that the prompt might + * be waiting on. + * + * Like other prompts, the `OAuthPrompt` can be used either as a dialog added to your bots + * `DialogSet` or on its own as a control if your bot is using some other conversation management + * system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to signin as + * needed and their access token will be passed as an argument to the callers next waterfall step: + * + * ```JavaScript + * const { DialogSet, OAuthPrompt } = require('botbuilder-dialogs'); + * + * const dialogs = new DialogSet(); + * + * dialogs.add('loginPrompt', new OAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub', + * timeout: 300000 // User has 5 minutes to login + * })); + * + * dialogs.add('taskNeedingLogin', [ + * async function (dc) { + * return dc.begin('loginPrompt'); + * }, + * async function (dc, token) { + * if (token) { + * // Continue with task needing access token + * } else { + * await dc.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`); + * return dc.end(); + * } + * } + * ]); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new OAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * const result = await prompt.begin(context, state); + * if (!result.active) { + * const token = result.result; + * } + * ``` + * + * If the user is already signed into the service we will get a token back immediately. We + * therefore need to check to see if the prompt is still active after the call to `begin()`. + * + * If the prompt is still active that means the user was sent an `OAuthCard` prompting the user to + * signin and we need to pass any additional activities we receive to the `continue()` method. We + * can't be certain which auth flow is being used so it's best to route *all* activities, regardless + * of type, to the `continue()` method for processing. + * + * ```JavaScript + * const prompt = new OAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const token = result.result; + * if (token) { + * // User has successfully signed in + * } else { + * // The signin has timed out + * } + * } + * ``` + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + */ export declare class OAuthPrompt extends Control { private settings; private prompt; + /** + * Creates a new `OAuthPrompt` instance. + * @param settings Settings used to configure the prompt. + * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. + */ constructor(settings: OAuthPromptSettingsWithTimeout, validator?: prompts.PromptValidator); dialogBegin(dc: DialogContext, options: PromptOptions): Promise; dialogContinue(dc: DialogContext): Promise; + /** + * Signs the user out of the service. + * + * **Usage Example:** + * + * ```JavaScript + * const prompt = new OAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * await prompt.signOutUser(context); + * ``` + * @param context + */ signOutUser(context: TurnContext): Promise; } diff --git a/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.js b/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.js index ec1c3e73c3..096e49071a 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.js @@ -10,7 +10,110 @@ Object.defineProperty(exports, "__esModule", { value: true }); const botbuilder_1 = require("botbuilder"); const prompts = require("botbuilder-prompts"); const control_1 = require("../control"); +/** + * :package: **botbuilder-dialogs** + * + * Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) + * service. The prompt will attempt to retrieve the users current token and if the user isn't + * signed in, it will send them an `OAuthCard` containing a button they can press to signin. + * Depending on the channel, the user will be sent through one of two possible signin flows: + * + * - The automatic signin flow where once the user signs in and the SSO service will forward the bot + * the users access token using either an `event` or `invoke` activity. + * - The "magic code" flow where where once the user signs in they will be prompted by the SSO + * service to send the bot a six digit code confirming their identity. This code will be sent as a + * standard `message` activity. + * + * Both flows are automatically supported by the `OAuthPrompt` and the only thing you need to be + * careful of is that you don't block the `event` and `invoke` activities that the prompt might + * be waiting on. + * + * Like other prompts, the `OAuthPrompt` can be used either as a dialog added to your bots + * `DialogSet` or on its own as a control if your bot is using some other conversation management + * system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to signin as + * needed and their access token will be passed as an argument to the callers next waterfall step: + * + * ```JavaScript + * const { DialogSet, OAuthPrompt } = require('botbuilder-dialogs'); + * + * const dialogs = new DialogSet(); + * + * dialogs.add('loginPrompt', new OAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub', + * timeout: 300000 // User has 5 minutes to login + * })); + * + * dialogs.add('taskNeedingLogin', [ + * async function (dc) { + * return dc.begin('loginPrompt'); + * }, + * async function (dc, token) { + * if (token) { + * // Continue with task needing access token + * } else { + * await dc.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`); + * return dc.end(); + * } + * } + * ]); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new OAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * const result = await prompt.begin(context, state); + * if (!result.active) { + * const token = result.result; + * } + * ``` + * + * If the user is already signed into the service we will get a token back immediately. We + * therefore need to check to see if the prompt is still active after the call to `begin()`. + * + * If the prompt is still active that means the user was sent an `OAuthCard` prompting the user to + * signin and we need to pass any additional activities we receive to the `continue()` method. We + * can't be certain which auth flow is being used so it's best to route *all* activities, regardless + * of type, to the `continue()` method for processing. + * + * ```JavaScript + * const prompt = new OAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const token = result.result; + * if (token) { + * // User has successfully signed in + * } else { + * // The signin has timed out + * } + * } + * ``` + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + */ class OAuthPrompt extends control_1.Control { + /** + * Creates a new `OAuthPrompt` instance. + * @param settings Settings used to configure the prompt. + * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. + */ constructor(settings, validator) { super(); this.settings = settings; @@ -58,6 +161,20 @@ class OAuthPrompt extends control_1.Control { } }); } + /** + * Signs the user out of the service. + * + * **Usage Example:** + * + * ```JavaScript + * const prompt = new OAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * await prompt.signOutUser(context); + * ``` + * @param context + */ signOutUser(context) { return this.prompt.signOutUser(context); } diff --git a/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.js.map b/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.js.map index c02fefc528..1ff7ae15aa 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.js.map +++ b/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"oauthPrompt.js","sourceRoot":"","sources":["../../src/prompts/oauthPrompt.ts"],"names":[],"mappings":"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"} \ No newline at end of file +{"version":3,"file":"oauthPrompt.js","sourceRoot":"","sources":["../../src/prompts/oauthPrompt.ts"],"names":[],"mappings":"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"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts index 000ca8711f..33d698ed75 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts @@ -9,7 +9,11 @@ import { TurnContext, Activity } from 'botbuilder'; import { PromptValidator } from 'botbuilder-prompts'; import { DialogContext } from '../dialogContext'; import { Control } from '../control'; -/** Basic configuration options supported by all prompts. */ +/** + * :package: **botbuilder-dialogs** + * + * Basic configuration options supported by all prompts. + */ export interface PromptOptions { /** (Optional) Initial prompt to send the user. */ prompt?: string | Partial; @@ -20,6 +24,12 @@ export interface PromptOptions { /** (Optional) Retry SSML to send the user. */ retrySpeak?: string; } +/** + * :package: **botbuilder-dialogs** + * + * Base class for all prompts. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + */ export declare abstract class Prompt extends Control { private validator; constructor(validator?: PromptValidator); diff --git a/libraries/botbuilder-dialogs/lib/prompts/prompt.js b/libraries/botbuilder-dialogs/lib/prompts/prompt.js index 4988add5a5..555133beed 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/prompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/prompt.js @@ -9,6 +9,12 @@ Object.defineProperty(exports, "__esModule", { value: true }); */ const botbuilder_1 = require("botbuilder"); const control_1 = require("../control"); +/** + * :package: **botbuilder-dialogs** + * + * Base class for all prompts. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + */ class Prompt extends control_1.Control { constructor(validator) { super(); diff --git a/libraries/botbuilder-dialogs/lib/prompts/prompt.js.map b/libraries/botbuilder-dialogs/lib/prompts/prompt.js.map index fb37a94612..71953149a2 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/prompt.js.map +++ b/libraries/botbuilder-dialogs/lib/prompts/prompt.js.map @@ -1 +1 @@ -{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/prompts/prompt.ts"],"names":[],"mappings":";;AAAA;;GAEG;AACH;;;GAGG;AACH,2CAA+E;AAG/E,wCAAqC;AAiBrC,YAAoD,SAAQ,iBAAU;IAClE,YAAoB,SAAqC;QACrD,KAAK,EAAE,CAAC;QADQ,cAAS,GAAT,SAAS,CAA4B;IAEzD,CAAC;IAMM,WAAW,CAAC,EAAoB,EAAE,OAAsB;QAC3D,kBAAkB;QAClB,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC;QAC7B,QAAQ,CAAC,KAAK,GAAG,OAAO,IAAI,EAAE,CAAC;QAE/B,sBAAsB;QACtB,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC;IAEM,cAAc,CAAC,EAAoB;QACtC,+CAA+C;QAC/C,EAAE,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,0BAAa,CAAC,OAAO,CAAC,CAAC,CAAC;YACrD,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC7B,CAAC;QAED,kBAAkB;QAClB,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,KAAK,CAAC;aACtC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE;YACjB,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;gBACjB,iBAAiB;gBACjB,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;YACnE,CAAC;YAAC,IAAI,CAAC,CAAC;gBACJ,gCAAgC;gBAChC,MAAM,CAAC,UAAU,CAAC;YACtB,CAAC;QACL,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;YACf,EAAE,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC;gBACvB,0BAA0B;gBAC1B,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC1B,CAAC;YAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;gBAC/B,oBAAoB;gBACpB,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YACnD,CAAC;QACL,CAAC,CAAC,CAAC;IACX,CAAC;CACJ;AA7CD,wBA6CC"} \ No newline at end of file +{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/prompts/prompt.ts"],"names":[],"mappings":";;AAAA;;GAEG;AACH;;;GAGG;AACH,2CAA+E;AAG/E,wCAAqC;AAqBrC;;;;;GAKG;AACH,YAAoD,SAAQ,iBAAU;IAClE,YAAoB,SAAqC;QACrD,KAAK,EAAE,CAAC;QADQ,cAAS,GAAT,SAAS,CAA4B;IAEzD,CAAC;IAMM,WAAW,CAAC,EAAoB,EAAE,OAAsB;QAC3D,kBAAkB;QAClB,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC;QAC7B,QAAQ,CAAC,KAAK,GAAG,OAAO,IAAI,EAAE,CAAC;QAE/B,sBAAsB;QACtB,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC;IAEM,cAAc,CAAC,EAAoB;QACtC,+CAA+C;QAC/C,EAAE,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,0BAAa,CAAC,OAAO,CAAC,CAAC,CAAC;YACrD,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC7B,CAAC;QAED,kBAAkB;QAClB,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,KAAK,CAAC;aACtC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE;YACjB,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;gBACjB,iBAAiB;gBACjB,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;YACnE,CAAC;YAAC,IAAI,CAAC,CAAC;gBACJ,gCAAgC;gBAChC,MAAM,CAAC,UAAU,CAAC;YACtB,CAAC;QACL,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;YACf,EAAE,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC;gBACvB,0BAA0B;gBAC1B,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC1B,CAAC;YAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;gBAC/B,oBAAoB;gBACpB,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YACnD,CAAC;QACL,CAAC,CAAC,CAAC;IACX,CAAC;CACJ;AA7CD,wBA6CC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts index c8305c915e..4e002edd3b 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts @@ -10,46 +10,85 @@ import { PromptValidator } from 'botbuilder-prompts'; import { DialogContext } from '../dialogContext'; import { Prompt, PromptOptions } from './prompt'; /** + * :package: **botbuilder-dialogs** + * * Prompts a user to enter some text. By default the prompt will return to the calling * dialog a `string` representing the users reply. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted with a question + * and the response will be passed as an argument to the callers next waterfall step: * * ```JavaScript * const { DialogSet, TextPrompt } = require('botbuilder-dialogs'); * * const dialogs = new DialogSet(); * - * dialogs.add('textPrompt', new TextPrompt()); + * dialogs.add('namePrompt', new TextPrompt()); * - * dialogs.add('textDemo', [ + * dialogs.add('askName', [ * async function (dc) { - * return dc.prompt('textPrompt', `text: enter some text`); + * return dc.prompt('namePrompt', `What's your name?`); * }, - * async function (dc, value) { - * await dc.context.sendActivity(`Recognized value: ${value}`); + * async function (dc, name) { + * await dc.context.sendActivity(`Hi ${name}!`); * return dc.end(); * } * ]); * ``` + * The prompt can be configured with a custom validator to perform additional checks like ensuring + * that the user responds with a valid age and that only whole numbers are returned: + * + * ```JavaScript + * dialogs.add('namePrompt', new TextPrompt(async (context, value) => { + * if (value && value.length >= 3) { + * return value; + * } + * await context.sendActivity(`Your entry must be at least 3 characters in length.`); + * return undefined; + * })); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new TextPrompt(); + * await prompt.begin(context, state, { prompt: `What's your name?` }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new TextPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const name = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to a `string` but can be changed by a custom validator passed to the prompt. */ export declare class TextPrompt extends Prompt { private prompt; /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('titlePrompt', new TextPrompt(async (context, value) => { - * if (!value || value.length < 3) { - * await context.sendActivity(`Title should be at least 3 characters long.`); - * return undefined; - * } else { - * return value.trim(); - * } - * })); - * ``` + * Creates a new `TextPrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. */ constructor(validator?: PromptValidator); diff --git a/libraries/botbuilder-dialogs/lib/prompts/textPrompt.js b/libraries/botbuilder-dialogs/lib/prompts/textPrompt.js index 2bdd6a970a..f96a09f3c2 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/textPrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/textPrompt.js @@ -3,45 +3,84 @@ Object.defineProperty(exports, "__esModule", { value: true }); const prompt_1 = require("./prompt"); const prompts = require("botbuilder-prompts"); /** + * :package: **botbuilder-dialogs** + * * Prompts a user to enter some text. By default the prompt will return to the calling * dialog a `string` representing the users reply. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted with a question + * and the response will be passed as an argument to the callers next waterfall step: * * ```JavaScript * const { DialogSet, TextPrompt } = require('botbuilder-dialogs'); * * const dialogs = new DialogSet(); * - * dialogs.add('textPrompt', new TextPrompt()); + * dialogs.add('namePrompt', new TextPrompt()); * - * dialogs.add('textDemo', [ + * dialogs.add('askName', [ * async function (dc) { - * return dc.prompt('textPrompt', `text: enter some text`); + * return dc.prompt('namePrompt', `What's your name?`); * }, - * async function (dc, value) { - * await dc.context.sendActivity(`Recognized value: ${value}`); + * async function (dc, name) { + * await dc.context.sendActivity(`Hi ${name}!`); * return dc.end(); * } * ]); * ``` + * The prompt can be configured with a custom validator to perform additional checks like ensuring + * that the user responds with a valid age and that only whole numbers are returned: + * + * ```JavaScript + * dialogs.add('namePrompt', new TextPrompt(async (context, value) => { + * if (value && value.length >= 3) { + * return value; + * } + * await context.sendActivity(`Your entry must be at least 3 characters in length.`); + * return undefined; + * })); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new TextPrompt(); + * await prompt.begin(context, state, { prompt: `What's your name?` }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new TextPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const name = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to a `string` but can be changed by a custom validator passed to the prompt. */ class TextPrompt extends prompt_1.Prompt { /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('titlePrompt', new TextPrompt(async (context, value) => { - * if (!value || value.length < 3) { - * await context.sendActivity(`Title should be at least 3 characters long.`); - * return undefined; - * } else { - * return value.trim(); - * } - * })); - * ``` + * Creates a new `TextPrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. */ constructor(validator) { diff --git a/libraries/botbuilder-dialogs/lib/prompts/textPrompt.js.map b/libraries/botbuilder-dialogs/lib/prompts/textPrompt.js.map index bb4521ec21..1139e77e16 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/textPrompt.js.map +++ b/libraries/botbuilder-dialogs/lib/prompts/textPrompt.js.map @@ -1 +1 @@ -{"version":3,"file":"textPrompt.js","sourceRoot":"","sources":["../../src/prompts/textPrompt.ts"],"names":[],"mappings":";;AAUA,qCAAiD;AACjD,8CAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,gBAA2D,SAAQ,eAAS;IAGxE;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,SAAsC;QAC9C,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAC7C,CAAC;IAES,QAAQ,CAAC,EAAoB,EAAE,OAAsB,EAAE,OAAgB;QAC7E,EAAE,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACnF,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAES,WAAW,CAAC,EAAoB,EAAE,OAAsB;QAC9D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;CACJ;AArCD,gCAqCC"} \ No newline at end of file +{"version":3,"file":"textPrompt.js","sourceRoot":"","sources":["../../src/prompts/textPrompt.ts"],"names":[],"mappings":";;AAUA,qCAAiD;AACjD,8CAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,gBAA2D,SAAQ,eAAS;IAGxE;;;OAGG;IACH,YAAY,SAAsC;QAC9C,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAC7C,CAAC;IAES,QAAQ,CAAC,EAAoB,EAAE,OAAsB,EAAE,OAAgB;QAC7E,EAAE,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACnF,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAES,WAAW,CAAC,EAAoB,EAAE,OAAsB;QAC9D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;CACJ;AAxBD,gCAwBC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/waterfall.d.ts b/libraries/botbuilder-dialogs/lib/waterfall.d.ts index 19e9d74d8c..d06acf59b1 100644 --- a/libraries/botbuilder-dialogs/lib/waterfall.d.ts +++ b/libraries/botbuilder-dialogs/lib/waterfall.d.ts @@ -9,6 +9,8 @@ import { Promiseable, TurnContext } from 'botbuilder'; import { Dialog } from './dialog'; import { DialogContext } from './dialogContext'; /** + * :package: **botbuilder-dialogs** + * * Function signature of a waterfall step. * * **Example usage:** @@ -49,11 +51,15 @@ import { DialogContext } from './dialogContext'; */ export declare type WaterfallStep = (dc: DialogContext, args?: any, next?: SkipStepFunction) => Promiseable; /** + * :package: **botbuilder-dialogs** + * * When called, control will skip to the next waterfall step. * @param SkipStepFunction.args (Optional) additional argument(s) to pass into the next step. */ export declare type SkipStepFunction = (args?: any) => Promise; /** + * :package: **botbuilder-dialogs** + * * Dialog optimized for prompting a user with a series of questions. Waterfalls accept a stack of * functions which will be executed in sequence. Each waterfall step can ask a question of the user * and the users response will be passed as an argument to the next waterfall step. diff --git a/libraries/botbuilder-dialogs/lib/waterfall.js b/libraries/botbuilder-dialogs/lib/waterfall.js index 019cb21ceb..d63d566c54 100644 --- a/libraries/botbuilder-dialogs/lib/waterfall.js +++ b/libraries/botbuilder-dialogs/lib/waterfall.js @@ -9,6 +9,8 @@ Object.defineProperty(exports, "__esModule", { value: true }); */ const botbuilder_1 = require("botbuilder"); /** + * :package: **botbuilder-dialogs** + * * Dialog optimized for prompting a user with a series of questions. Waterfalls accept a stack of * functions which will be executed in sequence. Each waterfall step can ask a question of the user * and the users response will be passed as an argument to the next waterfall step. diff --git a/libraries/botbuilder-dialogs/lib/waterfall.js.map b/libraries/botbuilder-dialogs/lib/waterfall.js.map index 624484ba66..144e85ac6b 100644 --- a/libraries/botbuilder-dialogs/lib/waterfall.js.map +++ b/libraries/botbuilder-dialogs/lib/waterfall.js.map @@ -1 +1 @@ -{"version":3,"file":"waterfall.js","sourceRoot":"","sources":["../src/waterfall.ts"],"names":[],"mappings":";;AAAA;;GAEG;AACH;;;GAGG;AACH,2CAAqE;AAmDrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH;IAGI;;;OAGG;IACH,YAAY,KAAyB;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;IAEM,WAAW,CAAC,EAAoB,EAAE,IAAU;QAC/C,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAkC,CAAC;QACvD,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC;QAClB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAEM,cAAc,CAAC,EAAoB;QACtC,+CAA+C;QAC/C,EAAE,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,0BAAa,CAAC,OAAO,CAAC,CAAC,CAAC;YACrD,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAkC,CAAC;YACvD,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAA;YAClB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACtD,CAAC;QAAC,IAAI,CAAC,CAAC;YACJ,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC7B,CAAC;IACL,CAAC;IAEM,YAAY,CAAC,EAAoB,EAAE,MAAY;QAClD,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAkC,CAAC;QACvD,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAA;QAClB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAEO,OAAO,CAAC,EAAoB,EAAE,MAAY;QAC9C,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAkC,CAAC;YACvD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;YAC3B,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;gBACxC,eAAe;gBACf,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAO,EAAE,EAAE;oBAC5D,oBAAoB;oBACpB,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC;oBACnB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;gBAC/B,CAAC,CAAC,CAAC,CAAC;YACR,CAAC;YAAC,IAAI,CAAC,CAAC;gBACJ,4CAA4C;gBAC5C,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC1B,CAAC;QACL,CAAC;QAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACX,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC;IACL,CAAC;CACJ;AArDD,8BAqDC"} \ No newline at end of file +{"version":3,"file":"waterfall.js","sourceRoot":"","sources":["../src/waterfall.ts"],"names":[],"mappings":";;AAAA;;GAEG;AACH;;;GAGG;AACH,2CAAqE;AAuDrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH;IAGI;;;OAGG;IACH,YAAY,KAAyB;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;IAEM,WAAW,CAAC,EAAoB,EAAE,IAAU;QAC/C,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAkC,CAAC;QACvD,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC;QAClB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAEM,cAAc,CAAC,EAAoB;QACtC,+CAA+C;QAC/C,EAAE,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,0BAAa,CAAC,OAAO,CAAC,CAAC,CAAC;YACrD,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAkC,CAAC;YACvD,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAA;YAClB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACtD,CAAC;QAAC,IAAI,CAAC,CAAC;YACJ,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC7B,CAAC;IACL,CAAC;IAEM,YAAY,CAAC,EAAoB,EAAE,MAAY;QAClD,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAkC,CAAC;QACvD,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAA;QAClB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAEO,OAAO,CAAC,EAAoB,EAAE,MAAY;QAC9C,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAkC,CAAC;YACvD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;YAC3B,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;gBACxC,eAAe;gBACf,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAO,EAAE,EAAE;oBAC5D,oBAAoB;oBACpB,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC;oBACnB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;gBAC/B,CAAC,CAAC,CAAC,CAAC;YACR,CAAC;YAAC,IAAI,CAAC,CAAC;gBACJ,4CAA4C;gBAC5C,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC1B,CAAC;QACL,CAAC;QAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACX,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC;IACL,CAAC;CACJ;AArDD,8BAqDC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/src/compositeControl.ts b/libraries/botbuilder-dialogs/src/compositeControl.ts index a4cb944f09..a8ca83fdf3 100644 --- a/libraries/botbuilder-dialogs/src/compositeControl.ts +++ b/libraries/botbuilder-dialogs/src/compositeControl.ts @@ -12,31 +12,173 @@ import { DialogSet } from './dialogSet'; /** + * :package: **botbuilder-dialogs** * + * A `CompositeControl` makes it easy to take an existing set of dialogs and package them up as a + * control that can be used within another bot. The control can be used either as a dialog added + * to the other bots `DialogSet` or on its own for bots that are using some other conversation + * management system. + * + * ### Control Packaging + * + * You'll typically want to package your control as a new class derived from `CompositeControl`. + * Within your controls constructor you'll pass the `DialogSet` containing your controls dialogs + * and the `ID` of the initial dialog that should be started anytime a caller calls the dialog. + * + * If your control needs to be configured then you can pass through the configuration settings as + * a set of `defaultOptions` which will be merged with any options passed in by the caller when + * they call `begin()`. These will then be passed as arguments to the initial dialog that gets + * started. + * + * Here's a fairly simple example of a `ProfileControl` that's designed to prompt the user to + * enter their name and phone number which it will return as a JSON object to the caller: + * + * ```JavaScript + * const { CompositeControl, DialogSet, TextPrompt } = require('botbuilder-dialogs'); + * + * const dialogs = new DialogSet(); + * + * class ProfileControl extends CompositeControl { + * constructor() { + * super(dialogs, 'fillProfile'); + * } + * } + * module.exports.ProfileControl = ProfileControl; + * + * dialogs.add('fillProfile', [ + * async function (dc, options) { + * dc.instance.state = {}; + * return dc.prompt('textPrompt', `What's your name?`); + * }, + * async function (dc, name) { + * dc.instance.state.name = name; + * return dc.prompt('textPrompt', `What's your phone number?`); + * }, + * async function (dc, phone) { + * dc.instance.state.phone = phone; + * + * // Return completed profile + * return dc.end(dc.instance.state); + * } + * ]); + * + * dialogs.add('textPrompt', new TextPrompt()); + * ``` + * + * ### Consume as Dialog + * + * On the consumption side the control we created can be used by a bot in much the same way they + * would use any other prompt. They can add a new instance of the control as a named dialog to + * their bots `DialogSet` and then start it using a call to `DialogContext.begin()`. If the + * control accepts options these can be passed in to the `begin()` call as well. + * + * ```JavaScript + * const { DialogSet } = require('botbuilder-dialogs'); + * const { ProfileControl } = require('./profileControl'); + * + * const dialogs = new DialogSet(); + * + * dialogs.add('getProfile', new ProfileControl()); + * + * dialogs.add('firstrun', [ + * async function (dc) { + * await dc.context.sendActivity(`Welcome! We need to ask a few questions to get started.`); + * return dc.begin('getProfile'); + * }, + * async function (dc, profile) { + * await dc.context.sendActivity(`Thanks ${profile.name}!`); + * return dc.end(); + * } + * ]); + * ``` + * + * ### Control Usage + * + * If the consuming bot isn't dialog based they can still use your control. They will just need + * start the control from somewhere within their bots logic by calling the controls `begin()` + * method: + * + * ```JavaScript + * const state = {}; + * const control = new ProfileControl(); + * await prompt.begin(context, state); + * ``` + * + * The control will populate the `state` object passed in with information it needs to process + * the users response. This should be saved off with the bots conversation state as it needs to be + * passed into the controls `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const control = new ProfileControl(); + * const result = await control.continue(context, state); + * if (!result.active) { + * const profile = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the control is finished and then to access any results it might have returned. To interrupt or + * cancel the control simply delete the `state` object the bot has been persisting. + * @param R (Optional) type of result that's expected to be returned by the control. + * @param O (Optional) options that can be passed into the [begin()](#begin) method. */ -export class CompositeControl implements Dialog { +export class CompositeControl implements Dialog { /** - * Creates a new CompositeControl instance. + * Creates a new `CompositeControl` instance. * @param dialogs Controls dialog set. * @param dialogId ID of the root dialog that should be started anytime the control is started. * @param defaultOptions (Optional) set of default options that should be passed to controls root dialog. These will be merged with arguments passed in by the caller. */ - constructor(protected dialogs: DialogSet, protected dialogId: string, protected defaultOptions?: O) { } + constructor(protected dialogs: DialogSet, protected dialogId: string, protected defaultOptions?: O) { } - public begin(context: C, state: object, options?: O): Promise> { + /** + * Starts the control. Depending on the control, its possible for the control to finish + * immediately so it's advised to check the result object returned by `begin()` and ensure that + * the control is still active before continuing. + * + * **Usage Example:** + * + * ```JavaScript + * const state = {}; + * const result = await control.begin(context, state); + * if (!result.active) { + * const value = result.result; + * } + * ``` + * @param context Context for the current turn of the conversation with the user. + * @param state A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. + * @param options (Optional) additional options supported by the control. + */ + public begin(context: TurnContext, state: object, options?: O): Promise> { const cdc = this.dialogs.createContext(context, state); return cdc.begin(this.dialogId, Object.assign({}, this.defaultOptions, options)) .then(() => cdc.dialogResult); } - public continue(context: C, state: object): Promise> { + /** + * Passes a users reply to the control for further processing. The bot should keep calling + * `continue()` for future turns until the control returns a result with `Active == false`. + * To cancel or interrupt the prompt simply delete the `state` object being persisted. + * + * **Usage Example:** + * + * ```JavaScript + * const result = await control.continue(context, state); + * if (!result.active) { + * const value = result.result; + * } + * ``` + * @param context Context for the current turn of the conversation with the user. + * @param state A state object that was previously initialized by a call to [begin()](#begin). + */ + public continue(context: TurnContext, state: object): Promise> { const cdc = this.dialogs.createContext(context, state); return cdc.continue() .then(() => cdc.dialogResult); } - public dialogBegin(dc: DialogContext, dialogArgs?: any): Promise { + public dialogBegin(dc: DialogContext, dialogArgs?: any): Promise { // Start the controls entry point dialog. const cdc = this.dialogs.createContext(dc.context, dc.instance.state); return cdc.begin(this.dialogId, Object.assign({}, this.defaultOptions, dialogArgs)).then(() => { @@ -47,7 +189,7 @@ export class CompositeControl): Promise { + public dialogContinue(dc: DialogContext): Promise { // Continue controls dialog stack. const cdc = this.dialogs.createContext(dc.context, dc.instance.state); return cdc.continue().then(() => { diff --git a/libraries/botbuilder-dialogs/src/control.ts b/libraries/botbuilder-dialogs/src/control.ts index b5e8fa20b6..91deb6f8ae 100644 --- a/libraries/botbuilder-dialogs/src/control.ts +++ b/libraries/botbuilder-dialogs/src/control.ts @@ -11,16 +11,46 @@ import { DialogContext, DialogResult } from './dialogContext'; import { DialogSet } from './dialogSet'; /** + * :package: **botbuilder-dialogs** * + * Base class for any dialog that wants to support being used as a dialog within a bots `DialogSet` + * or on its own as a control within a bot that uses an alternate conversation management system. + * + * The `Control` and `CompositeControl` classes are very similar in that they both add `begin()` + * and `continue()` methods which simplify consuming the control from a non-dialog based bot. The + * primary difference between the two classes is that the `CompositeControl` class is designed to + * bridge one `DialogSet` to another where the `Control` class assumes that the derived dialog can + * be used in complete isolation without the need for any other supporting dialogs. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param R (Optional) type of result that's expected to be returned by the control. + * @param O (Optional) options that can be passed into the [begin()](#begin) method. */ -export abstract class Control implements Dialog { +export abstract class Control implements Dialog { /** * Creates a new Control instance. - * @param defaultOptions (Optional) set of default options that should be passed to controls root dialog. These will be merged with arguments passed in by the caller. + * @param defaultOptions (Optional) set of default options that should be passed to controls `dialogBegin()` method. These will be merged with arguments passed in by the caller. */ constructor(protected defaultOptions?: O) { } + /** + * Starts the control. Depending on the control, its possible for the control to finish + * immediately so it's advised to check the result object returned by `begin()` and ensure that + * the control is still active before continuing. + * + * **Usage Example:** + * + * ```JavaScript + * const state = {}; + * const result = await control.begin(context, state); + * if (!result.active) { + * const value = result.result; + * } + * ``` + * @param context Context for the current turn of the conversation with the user. + * @param state A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. + * @param options (Optional) additional options supported by the control. + */ public begin(context: C, state: object, options?: O): Promise> { // Create empty dialog set and ourselves to it const dialogs = new DialogSet(); @@ -32,6 +62,22 @@ export abstract class Control cdc.dialogResult); } + /** + * Passes a users reply to the control for further processing. The bot should keep calling + * `continue()` for future turns until the control returns a result with `Active == false`. + * To cancel or interrupt the prompt simply delete the `state` object being persisted. + * + * **Usage Example:** + * + * ```JavaScript + * const result = await control.continue(context, state); + * if (!result.active) { + * const value = result.result; + * } + * ``` + * @param context Context for the current turn of the conversation with the user. + * @param state A state object that was previously initialized by a call to [begin()](#begin). + */ public continue(context: C, state: object): Promise> { // Create empty dialog set and ourselves to it const dialogs = new DialogSet(); diff --git a/libraries/botbuilder-dialogs/src/dialog.ts b/libraries/botbuilder-dialogs/src/dialog.ts index 09aa5a6e66..28ea59644b 100644 --- a/libraries/botbuilder-dialogs/src/dialog.ts +++ b/libraries/botbuilder-dialogs/src/dialog.ts @@ -9,9 +9,12 @@ import { TurnContext, Promiseable } from 'botbuilder'; import { DialogContext } from './dialogContext'; /** + * :package: **botbuilder-dialogs** + * * Interface of Dialog objects that can be added to a `DialogSet`. The dialog should generally * be a singleton and added to a dialog set using `DialogSet.add()` at which point it will be * assigned a unique ID. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. */ export interface Dialog { /** @@ -46,7 +49,8 @@ export interface Dialog { } /** - * Tracking information for a dialog on the stack. + * Tracking information for a dialog on the stack. + * @param T (Optional) type of state being persisted for dialog. */ export interface DialogInstance { /** ID of the dialog this instance is for. */ diff --git a/libraries/botbuilder-dialogs/src/dialogContext.ts b/libraries/botbuilder-dialogs/src/dialogContext.ts index 07a180f2cc..f27159586f 100644 --- a/libraries/botbuilder-dialogs/src/dialogContext.ts +++ b/libraries/botbuilder-dialogs/src/dialogContext.ts @@ -12,6 +12,8 @@ import { PromptOptions, ChoicePromptOptions } from './prompts/index'; import { Choice } from 'botbuilder-prompts'; /** + * :package: **botbuilder-dialogs** + * * Result returned to the caller of one of the various stack manipulation methods and used to * return the result from a final call to `DialogContext.end()` to the bots logic. */ @@ -31,6 +33,12 @@ export interface DialogResult { result: T|undefined; } +/** + * :package: **botbuilder-dialogs** + * + * + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + */ export class DialogContext { private finalResult: any = undefined; diff --git a/libraries/botbuilder-dialogs/src/dialogSet.ts b/libraries/botbuilder-dialogs/src/dialogSet.ts index 1df1d75c72..bf36986c8e 100644 --- a/libraries/botbuilder-dialogs/src/dialogSet.ts +++ b/libraries/botbuilder-dialogs/src/dialogSet.ts @@ -11,37 +11,95 @@ import { Waterfall, WaterfallStep } from './waterfall'; import { DialogContext } from './dialogContext'; /** + * :package: **botbuilder-dialogs** + * * A related set of dialogs that can all call each other. - * - * **Example usage:** * + * ### Overview + * + * The dialogs library uses a stack based metaphor to manage a bot conversation with a user. In + * this model the bt begins dialogs to prompt the user for information. Those dialogs will + * typically call prompts to actually ask the user for information. A variety of typed prompts are + * provided and are themselves just other dialogs. When a prompt recognizes a users input as being + * valid, it will end itself and return the users input to the dialog that started it. That dialog + * is then free to either process the users input or ask the user for more information by pushing + * other dialogs/prompts onto the stack. Below is a simple `Waterfall` dialog that asks the user + * for their name and phone number: + * * ```JavaScript - * const { Bot, MemoryStorage, BotStateManager } = require('botbuilder'); - * const { ConsoleAdapter } = require('botbuilder-node'); - * const { DialogSet } = require('botbuilder-dialogs'); + * const { DialogSet, TextPrompt } = require('botbuilder-dialogs'); * * const dialogs = new DialogSet(); * - * dialogs.add('greeting', [ - * function (context) { - * context.reply(`Hello... I'm a bot :)`); - * return dialogs.end(context); - * } + * dialogs.add('fillProfile', [ + * async function (dc, options) { + * dc.instance.state = {}; + * return dc.prompt('textPrompt', `What's your name?`); + * }, + * async function (dc, name) { + * dc.instance.state.name = name; + * return dc.prompt('textPrompt', `What's your phone number?`); + * }, + * async function (dc, phone) { + * dc.instance.state.phone = phone; + * + * // Return completed profile + * return dc.end(dc.instance.state); + * } * ]); * - * const adapter = new ConsoleAdapter().listen(); - * const bot = new Bot(adapter) - * .use(new MemoryStorage()) - * .use(new BotStateManager()) - * .onReceive((context) => { - * return dialogs.continue(context).then(() => { - * // If nothing has responded start greeting dialog - * if (!context.responded) { - * return dialogs.begin(context, 'greeting'); - * } - * }); - * }); + * dialogs.add('textPrompt', new TextPrompt()); * ``` + * + * At first glance it probably looks like we're making this simple task of asking the user two + * questions way harder then it needs to be. It turns out though that asking a user even one + * question is a really hard problem. The primary issues coming from the fact that a) your bot will + * likely be running across multiple compute nodes and the node that asked the user a question may + * not be the one that receives their answer. and b) it could be minutes, hours, days, or even + * weeks before the user replies to the bot. Your bots compute process could have been restarted + * or updated any number of times before the user replies to the last question. + * + * The dialogs library addresses both of those issues by having you statically define and + * explicitly name all of your bots dialogs on startups. It then uses a persisted dialog stack to + * essentially maintain a program pointer so that any time a message is received from a user it can + * identify the function it should run to process that message in a deterministic way. + * + * ### Routing Requests + * + * To run the 'fillProfile' dialog above we need to add a bit of fairly boilerplate code to + * our bots routing logic: + * + * ```JavaScript + * server.post('/api/messages', (req, res) => { + * adapter.processActivity(req, res, async (context) => { + * // Continue execution if there's a "current" dialog + * const state = conversationState.get(context); + * const dc = dialogs.createContext(context, state); + * await dc.continue(); + * if (!context.responded && context.activity.type === ActivityType.Message) { + * // No active dialogs so start 'fillProfile' dialog + * await dc.begin('fillProfile'); + * } + * }); + * }); + * ``` + * + * This code results in a bot that loops over prompting the user to fill out their profile so + * while not overly useful it does serve as a good starting point for understanding how to route + * request to your bots dialogs. + * + * The code first creates a `DialogContext` and then calls `dc.continue()` which will route the + * request to the "current" dialog on the top of the stack, if there is one. It's using + * `context.responded` to determine if anything processed the request which is reasonable given + * that as a best practice your bot should always reply to any message received from the user. So + * if nothing has responded and we've received a `message` activity we'll start the 'fillProfile' + * by calling `dc.begin()`. + * + * ### Detecting Interruptions + * + * + * + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. */ export class DialogSet { private readonly dialogs: { [id:string]: Dialog; } = {}; @@ -53,13 +111,12 @@ export class DialogSet { * * ```JavaScript * dialogs.add('greeting', [ - * function (context, user) { - * context.reply(`Hello ${user.name}... I'm a bot :)`); - * return dialogs.end(context); + * async function (dc) { + * await dc.context.sendActivity(`Hello world!`); + * return dc.end(); * } * ]); * ``` - * @param T Type of the dialog being set and returned. * @param dialogId Unique ID of the dialog within the set. * @param dialogOrSteps Either a new dialog or an array of waterfall steps to execute. If waterfall steps are passed in they will automatically be passed into an new instance of a `Waterfall` class. */ diff --git a/libraries/botbuilder-dialogs/src/prompts/attachmentPrompt.ts b/libraries/botbuilder-dialogs/src/prompts/attachmentPrompt.ts index f103c05e52..df66dc3258 100644 --- a/libraries/botbuilder-dialogs/src/prompts/attachmentPrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/attachmentPrompt.ts @@ -12,11 +12,21 @@ import { Prompt, PromptOptions } from './prompt'; import * as prompts from 'botbuilder-prompts'; /** + * :package: **botbuilder-dialogs** + * * Prompts a user to upload attachments like images. By default the prompt will return to the * calling dialog a `Attachment[]` but this can be overridden using a custom `PromptValidator`. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to upload one or + * more attachments which will be passed as an argument to the callers next waterfall step: + * * ```JavaScript * const { DialogSet, AttachmentPrompt } = require('botbuilder-dialogs'); * @@ -34,25 +44,72 @@ import * as prompts from 'botbuilder-prompts'; * } * ]); * ``` + * + * If the users response to the prompt fails to be recognized they will be automatically re-prompted + * to try again. By default the original prompt is re-sent to the user but you can provide an + * alternate prompt to send by passing in additional options: + * + * ```JavaScript + * return dc.prompt('attachmentPrompt', `Send me image(s)`, { retryPrompt: `I didn't get anything. Send me an image.` }); + * ``` + * + * The prompts retry logic can also be completely customized by passing the prompts constructor a + * custom validator: + * + * ```JavaScript + * dialogs.add('imagePrompt', new AttachmentPrompt(async (context, values) => { + * if (values && values.length > 0) { + * for (let i = 0; i < values.length; i++) { + * if (!values[i].contentType.startsWith('image')) { + * await context.sendActivity(`Only images are accepted.`); + * return undefined; + * } + * } + * } else { + * await context.sendActivity(`Please upload at least one image.`); + * } + * return values; + * })); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new AttachmentPrompt(); + * await prompt.begin(context, state, { + * prompt: `Send me image(s)`, + * retryPrompt: `I didn't get anything. Send me an image.` + * }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new AttachmentPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const attachments = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to an `Attachment[]` but can be changed by a custom validator passed to the prompt. */ export class AttachmentPrompt extends Prompt { private prompt: prompts.AttachmentPrompt; /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('imagePrompt', new AttachmentPrompt(async (context, values) => { - * if (!Array.isArray(values) || values.length < 1) { - * await context.sendActivity(`Send me an image or say "cancel".`); - * return undefined; - * } else { - * return values; - * } - * })); - * ``` + * Creates a new `AttachmentPrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. */ constructor(validator?: PromptValidator) { diff --git a/libraries/botbuilder-dialogs/src/prompts/choicePrompt.ts b/libraries/botbuilder-dialogs/src/prompts/choicePrompt.ts index 063a0d9b65..8b2375e6e6 100644 --- a/libraries/botbuilder-dialogs/src/prompts/choicePrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/choicePrompt.ts @@ -11,17 +11,31 @@ import { DialogContext } from '../dialogContext'; import { Prompt, PromptOptions } from './prompt'; import * as prompts from 'botbuilder-prompts'; -/** Additional options that can be used to configure a `ChoicePrompt`. */ +/** + * :package: **botbuilder-dialogs** + * + * Additional options that can be used to configure a `ChoicePrompt`. + */ export interface ChoicePromptOptions extends PromptOptions { /** List of choices to recognize. */ choices?: (string|prompts.Choice)[]; } /** + * :package: **botbuilder-dialogs** + * * Prompts a user to confirm something with a yes/no response. By default the prompt will return * to the calling dialog a `boolean` representing the users selection. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to select a choice + * from a list and their choice will be passed as an argument to the callers next waterfall step: * * ```JavaScript * const { DialogSet, ChoicePrompt } = require('botbuilder-dialogs'); @@ -30,35 +44,65 @@ export interface ChoicePromptOptions extends PromptOptions { * * dialogs.add('choicePrompt', new ChoicePrompt()); * - * dialogs.add('choiceDemo', [ + * dialogs.add('colorPrompt', [ * async function (dc) { - * return dc.prompt('choicePrompt', `choice: select a color`, ['red', 'green', 'blue']); + * return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue']); * }, * async function (dc, choice) { - * await dc.context.sendActivity(`Recognized choice: ${JSON.stringify(choice)}`); + * const color = choice.value; + * await dc.context.sendActivity(`I like ${color} too!`); * return dc.end(); * } * ]); * ``` + * + * If the users response to the prompt fails to be recognized they will be automatically re-prompted + * to try again. By default the original prompt is re-sent to the user but you can provide an + * alternate prompt to send by passing in additional options: + * + * ```JavaScript + * return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue'], { retryPrompt: `I didn't catch that. Select a color from the list.` }); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new ChoicePrompt(); + * await prompt.begin(context, state, { + * choices: ['red', 'green', 'blue'], + * prompt: `Select a color`, + * retryPrompt: `I didn't catch that. Select a color from the list.` + * }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new ChoicePrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const color = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to an instance of `FoundChoice` but can be changed by a custom validator passed to the prompt. */ export class ChoicePrompt extends Prompt { private prompt: prompts.ChoicePrompt; /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('choicePrompt', new ChoicePrompt(async (context, value) => { - * if (value === undefined) { - * await context.sendActivity(`I didn't recognize your choice. Please select from the choices on the list.`); - * return undefined; - * } else { - * return value; - * } - * })); - * ``` + * Creates a new `ChoicePrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-dialogs/src/prompts/confirmPrompt.ts b/libraries/botbuilder-dialogs/src/prompts/confirmPrompt.ts index 009cca24c3..a5aae03097 100644 --- a/libraries/botbuilder-dialogs/src/prompts/confirmPrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/confirmPrompt.ts @@ -12,10 +12,21 @@ import { Prompt, PromptOptions } from './prompt'; import * as prompts from 'botbuilder-prompts'; /** + * :package: **botbuilder-dialogs** + * * Prompts a user to confirm something with a yes/no response. By default the prompt will return * to the calling dialog a `boolean` representing the users selection. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to answer a + * `yes/no` or `true/false` question and the users response will be passed as an argument to the + * callers next waterfall step: * * ```JavaScript * const { DialogSet, ConfirmPrompt } = require('botbuilder-dialogs'); @@ -24,16 +35,71 @@ import * as prompts from 'botbuilder-prompts'; * * dialogs.add('confirmPrompt', new ConfirmPrompt()); * - * dialogs.add('confirmDemo', [ + * dialogs.add('confirmCancel', [ * async function (dc) { - * return dc.prompt('confirmPrompt', `confirm: answer "yes" or "no"`); + * return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`); * }, - * async function (dc, value) { - * await dc.context.sendActivity(`Recognized value: ${value}`); + * async function (dc, cancel) { + * if (cancel) { + * await dc.context.sendActivity(`Order cancelled.`); + * } * return dc.end(); * } * ]); * ``` + * + * If the users response to the prompt fails to be recognized they will be automatically re-prompted + * to try again. By default the original prompt is re-sent to the user but you can provide an + * alternate prompt to send by passing in additional options: + * + * ```JavaScript + * return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`, { retryPrompt: `Please answer "yes" or "no".` }); + * ``` + * + * The prompts retry logic can also be completely customized by passing the prompts constructor a + * custom validator: + * + * ```JavaScript + * dialogs.add('confirmPrompt', new ConfirmPrompt(async (context, value) => { + * if (typeof confirmed != 'boolean') { + * await context.sendActivity(`Please answer "yes" or "no".`); + * } + * return confirmed; + * })); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new ConfirmPrompt(); + * await prompt.begin(context, state, { + * prompt: `This will cancel your order. Are you sure?`, + * retryPrompt: `Please answer "yes" or "no".` + * }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new ConfirmPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const cancelOrder = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to a boolean `true` or `false` but can be changed by a custom validator passed to the prompt. */ export class ConfirmPrompt extends Prompt { private prompt: prompts.ConfirmPrompt; @@ -46,29 +112,21 @@ export class ConfirmPrompt extends Prompt * **Example usage:** * * ```JavaScript + * const confirmPrompt = new ConfirmPrompt(); + * * // Configure yes/no choices for english and spanish (default) - * ConfirmPrompt.choices['*'] = ['sí', 'no']; - * ConfirmPrompt.choices['es'] = ['sí', 'no']; - * ConfirmPrompt.choices['en-us'] = ['yes', 'no']; + * confirmPrompt.choices['*'] = ['sí', 'no']; + * confirmPrompt.choices['es'] = ['sí', 'no']; + * confirmPrompt.choices['en-us'] = ['yes', 'no']; + * + * // Add to dialogs + * dialogs.add('confirmPrompt', confirmPrompt); * ``` */ static choices: prompts.ConfirmChoices = { '*': ['yes', 'no'] }; /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('confirmPrompt', new ConfirmPrompt(async (context, value) => { - * if (value === undefined) { - * await context.sendActivity(`Invalid answer. Answer with "yes" or "no".`); - * return undefined; - * } else { - * return value; - * } - * })); - * ``` + * Creates a new `ConfirmPrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. */ @@ -80,8 +138,8 @@ export class ConfirmPrompt extends Prompt /** * Sets additional options passed to the `ChoiceFactory` and used to tweak the style of choices - * rendered to the user. - * @param options Additional options to set. + * rendered to the user. + * @param options Additional options to set. Defaults to `{ includeNumbers: false }` */ public choiceOptions(options: prompts.ChoiceFactoryOptions): this { Object.assign(this.prompt.choiceOptions, options); diff --git a/libraries/botbuilder-dialogs/src/prompts/datetimePrompt.ts b/libraries/botbuilder-dialogs/src/prompts/datetimePrompt.ts index 16b07f0e22..63a9f66163 100644 --- a/libraries/botbuilder-dialogs/src/prompts/datetimePrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/datetimePrompt.ts @@ -12,51 +12,88 @@ import { Prompt, PromptOptions } from './prompt'; import * as prompts from 'botbuilder-prompts'; /** + * :package: **botbuilder-dialogs** + * * Prompts a user to enter a datetime expression. By default the prompt will return to the * calling dialog a `FoundDatetime[]` but this can be overridden using a custom `PromptValidator`. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to reply with a + * date and/or time. The recognized date/time will be passed as an argument to the callers next + * waterfall step: * * ```JavaScript * const { DialogSet, DatetimePrompt } = require('botbuilder-dialogs'); * * const dialogs = new DialogSet(); * - * dialogs.add('datetimePrompt', new DatetimePrompt()); + * dialogs.add('datetimePrompt', new DatetimePrompt(AlarmTimeValidator)); * - * dialogs.add('datetimeDemo', [ + * dialogs.add('setAlarmTime', [ * async function (dc) { - * return dc.prompt('datetimePrompt', `datetime: enter a datetime`); + * return dc.prompt('datetimePrompt', `What time should I set your alarm for?`); * }, - * async function (dc, values) { - * await dc.context.sendActivity(`Recognized values: ${JSON.stringify(values)}`); + * async function (dc, time) { + * await dc.context.sendActivity(`Alarm time set`); * return dc.end(); * } * ]); + * + * async function AlarmTimeValidator(context, values) { + * try { + * if (!Array.isArray(values) || values.length < 0) { throw new Error('missing time') } + * if (values[0].type !== 'datetime') { throw new Error('unsupported type') } + * const value = new Date(values[0].value); + * if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } + * return value; + * } catch (err) { + * await context.sendActivity(`Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); + * return undefined; + * } + * } + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new DatetimePrompt(AlarmTimeValidator); + * await prompt.begin(context, state, { prompt: `What time should I set your alarm for?` }); * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new ConfirmPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const time = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to a `FoundDatetime[]` but can be changed by a custom validator passed to the prompt. */ export class DatetimePrompt extends Prompt { private prompt: prompts.DatetimePrompt; /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('timePrompt', new DatetimePrompt(async (context, values) => { - * try { - * if (!Array.isArray(values) || values.length < 0) { throw new Error('missing time') } - * if (values[0].type !== 'datetime') { throw new Error('unsupported type') } - * const value = new Date(values[0].value); - * if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } - * return value; - * } catch (err) { - * await context.sendActivity(`Invalid time. Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); - * return undefined; - * } - * })); - * ``` + * Creates a new `DatetimePrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. */ diff --git a/libraries/botbuilder-dialogs/src/prompts/numberPrompt.ts b/libraries/botbuilder-dialogs/src/prompts/numberPrompt.ts index a8bc36a5a1..99f12ea065 100644 --- a/libraries/botbuilder-dialogs/src/prompts/numberPrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/numberPrompt.ts @@ -12,47 +12,97 @@ import { Prompt, PromptOptions } from './prompt'; import * as prompts from 'botbuilder-prompts'; /** + * :package: **botbuilder-dialogs** + * * Prompts a user to enter a number. By default the prompt will return to the calling dialog * a `number` representing the users input. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to reply with a + * number which will be passed as an argument to the callers next waterfall step: * * ```JavaScript * const { DialogSet, NumberPrompt } = require('botbuilder-dialogs'); * * const dialogs = new DialogSet(); * - * dialogs.add('numberPrompt', new NumberPrompt()); + * dialogs.add('agePrompt', new NumberPrompt()); * - * dialogs.add('numberDemo', [ + * dialogs.add('askAge', [ * async function (dc) { - * return dc.prompt('numberPrompt', `number: enter a number`); + * return dc.prompt('agePrompt', `How old are you?`); * }, - * async function (dc, value) { - * await dc.context.sendActivity(`Recognized value: ${value}`); + * async function (dc, age) { + * if (age < 40) { + * await dc.context.sendActivity(`So young :)`); + * } else { + * await dc.context.sendActivity(`I hear ${age} is the new ${age - 10} :)`); + * } * return dc.end(); * } * ]); * ``` + * + * The prompt can be configured with a custom validator to perform additional checks like ensuring + * that the user responds with a valid age and that only whole numbers are returned: + * + * ```JavaScript + * dialogs.add('agePrompt', new NumberPrompt(async (context, value) => { + * if (typeof value == 'number') { + * if (value >= 1 && value < 111) { + * // Return age rounded down to nearest whole number. + * return Math.floor(value); + * } + * } + * await context.sendActivity(`Please enter a number between 1 and 110 or say "cancel".`); + * return undefined; + * })); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new NumberPrompt(); + * await prompt.begin(context, state, { + * prompt: `How old are you?`, + * retryPrompt: `Please reply with a valid number like "23".` + * }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new ConfirmPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const age = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to a `number` but can be changed by a custom validator passed to the prompt. */ export class NumberPrompt extends Prompt { private prompt: prompts.NumberPrompt; /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('agePrompt', new NumberPrompt(async (context, value) => { - * if (value === undefined || value < 1 || value > 110) { - * await context.sendActivity(`Invalid age. Only ages between 1 and 110 are allowed.`); - * return undefined; - * } else { - * return value; - * } - * })); - * ``` + * Creates a new `NumberPrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`. */ @@ -74,5 +124,3 @@ export class NumberPrompt extends Prompt { return this.prompt.recognize(dc.context); } } - - diff --git a/libraries/botbuilder-dialogs/src/prompts/oauthPrompt.ts b/libraries/botbuilder-dialogs/src/prompts/oauthPrompt.ts index 97b4ba02b3..26f6b00b99 100644 --- a/libraries/botbuilder-dialogs/src/prompts/oauthPrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/oauthPrompt.ts @@ -11,6 +11,12 @@ import { DialogContext } from '../dialogContext'; import { Control } from '../control'; import { PromptOptions } from './prompt'; +/** + * :package: **botbuilder-dialogs** + * + * Settings used to configure an `OAuthPrompt` instance. Includes the ability to adjust the prompts + * timeout settings. + */ export interface OAuthPromptSettingsWithTimeout extends prompts.OAuthPromptSettings { /** * (Optional) number of milliseconds the prompt will wait for the user to authenticate. @@ -19,14 +25,112 @@ export interface OAuthPromptSettingsWithTimeout extends prompts.OAuthPromptSetti timeout?: number; } -interface OAuthPromptState extends PromptOptions { - /** Timestamp of when the prompt will timeout. */ - expires: number; -} - +/** + * :package: **botbuilder-dialogs** + * + * Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) + * service. The prompt will attempt to retrieve the users current token and if the user isn't + * signed in, it will send them an `OAuthCard` containing a button they can press to signin. + * Depending on the channel, the user will be sent through one of two possible signin flows: + * + * - The automatic signin flow where once the user signs in and the SSO service will forward the bot + * the users access token using either an `event` or `invoke` activity. + * - The "magic code" flow where where once the user signs in they will be prompted by the SSO + * service to send the bot a six digit code confirming their identity. This code will be sent as a + * standard `message` activity. + * + * Both flows are automatically supported by the `OAuthPrompt` and the only thing you need to be + * careful of is that you don't block the `event` and `invoke` activities that the prompt might + * be waiting on. + * + * Like other prompts, the `OAuthPrompt` can be used either as a dialog added to your bots + * `DialogSet` or on its own as a control if your bot is using some other conversation management + * system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted to signin as + * needed and their access token will be passed as an argument to the callers next waterfall step: + * + * ```JavaScript + * const { DialogSet, OAuthPrompt } = require('botbuilder-dialogs'); + * + * const dialogs = new DialogSet(); + * + * dialogs.add('loginPrompt', new OAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub', + * timeout: 300000 // User has 5 minutes to login + * })); + * + * dialogs.add('taskNeedingLogin', [ + * async function (dc) { + * return dc.begin('loginPrompt'); + * }, + * async function (dc, token) { + * if (token) { + * // Continue with task needing access token + * } else { + * await dc.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`); + * return dc.end(); + * } + * } + * ]); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new OAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * const result = await prompt.begin(context, state); + * if (!result.active) { + * const token = result.result; + * } + * ``` + * + * If the user is already signed into the service we will get a token back immediately. We + * therefore need to check to see if the prompt is still active after the call to `begin()`. + * + * If the prompt is still active that means the user was sent an `OAuthCard` prompting the user to + * signin and we need to pass any additional activities we receive to the `continue()` method. We + * can't be certain which auth flow is being used so it's best to route *all* activities, regardless + * of type, to the `continue()` method for processing. + * + * ```JavaScript + * const prompt = new OAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const token = result.result; + * if (token) { + * // User has successfully signed in + * } else { + * // The signin has timed out + * } + * } + * ``` + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + */ export class OAuthPrompt extends Control { private prompt: prompts.OAuthPrompt; + /** + * Creates a new `OAuthPrompt` instance. + * @param settings Settings used to configure the prompt. + * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. + */ constructor(private settings: OAuthPromptSettingsWithTimeout, validator?: prompts.PromptValidator) { super(); this.prompt = prompts.createOAuthPrompt(settings, validator); @@ -75,7 +179,26 @@ export class OAuthPrompt extends Control { }); } + /** + * Signs the user out of the service. + * + * **Usage Example:** + * + * ```JavaScript + * const prompt = new OAuthPrompt({ + * connectionName: 'GitConnection', + * title: 'Login To GitHub' + * }); + * await prompt.signOutUser(context); + * ``` + * @param context + */ public signOutUser(context: TurnContext): Promise { return this.prompt.signOutUser(context); } } + +interface OAuthPromptState extends PromptOptions { + /** Timestamp of when the prompt will timeout. */ + expires: number; +} diff --git a/libraries/botbuilder-dialogs/src/prompts/prompt.ts b/libraries/botbuilder-dialogs/src/prompts/prompt.ts index f1dd9fa324..000bc100c8 100644 --- a/libraries/botbuilder-dialogs/src/prompts/prompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/prompt.ts @@ -10,7 +10,11 @@ import { PromptValidator } from 'botbuilder-prompts'; import { DialogContext } from '../dialogContext'; import { Control } from '../control'; -/** Basic configuration options supported by all prompts. */ +/** + * :package: **botbuilder-dialogs** + * + * Basic configuration options supported by all prompts. + */ export interface PromptOptions { /** (Optional) Initial prompt to send the user. */ prompt?: string|Partial; @@ -25,6 +29,12 @@ export interface PromptOptions { retrySpeak?: string; } +/** + * :package: **botbuilder-dialogs** + * + * Base class for all prompts. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + */ export abstract class Prompt extends Control { constructor(private validator?: PromptValidator) { super(); diff --git a/libraries/botbuilder-dialogs/src/prompts/textPrompt.ts b/libraries/botbuilder-dialogs/src/prompts/textPrompt.ts index 030ca5f42a..0096b2d582 100644 --- a/libraries/botbuilder-dialogs/src/prompts/textPrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/textPrompt.ts @@ -12,47 +12,86 @@ import { Prompt, PromptOptions } from './prompt'; import * as prompts from 'botbuilder-prompts'; /** + * :package: **botbuilder-dialogs** + * * Prompts a user to enter some text. By default the prompt will return to the calling * dialog a `string` representing the users reply. * - * **Example usage:** + * The prompt can be used either as a dialog added to your bots `DialogSet` or on its own as a + * control if your bot is using some other conversation management system. + * + * ### Dialog Usage + * + * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named + * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either + * `DialogContext.begin()` or `DialogContext.prompt()`. The user will be prompted with a question + * and the response will be passed as an argument to the callers next waterfall step: * * ```JavaScript * const { DialogSet, TextPrompt } = require('botbuilder-dialogs'); * * const dialogs = new DialogSet(); * - * dialogs.add('textPrompt', new TextPrompt()); + * dialogs.add('namePrompt', new TextPrompt()); * - * dialogs.add('textDemo', [ + * dialogs.add('askName', [ * async function (dc) { - * return dc.prompt('textPrompt', `text: enter some text`); + * return dc.prompt('namePrompt', `What's your name?`); * }, - * async function (dc, value) { - * await dc.context.sendActivity(`Recognized value: ${value}`); + * async function (dc, name) { + * await dc.context.sendActivity(`Hi ${name}!`); * return dc.end(); * } * ]); * ``` + * The prompt can be configured with a custom validator to perform additional checks like ensuring + * that the user responds with a valid age and that only whole numbers are returned: + * + * ```JavaScript + * dialogs.add('namePrompt', new TextPrompt(async (context, value) => { + * if (value && value.length >= 3) { + * return value; + * } + * await context.sendActivity(`Your entry must be at least 3 characters in length.`); + * return undefined; + * })); + * ``` + * + * ### Control Usage + * + * If your bot isn't dialog based you can still use the prompt on its own as a control. You will + * just need start the prompt from somewhere within your bots logic by calling the prompts + * `begin()` method: + * + * ```JavaScript + * const state = {}; + * const prompt = new TextPrompt(); + * await prompt.begin(context, state, { prompt: `What's your name?` }); + * ``` + * + * The prompt will populate the `state` object you passed in with information it needs to process + * the users response. You should save this off to your bots conversation state as you'll need to + * pass it to the prompts `continue()` method on the next turn of conversation with the user: + * + * ```JavaScript + * const prompt = new TextPrompt(); + * const result = await prompt.continue(context, state); + * if (!result.active) { + * const name = result.result; + * } + * ``` + * + * The `continue()` method returns a `DialogResult` object which can be used to determine when + * the prompt is finished and then to access the results of the prompt. To interrupt or cancel + * the prompt simply delete the `state` object your bot is persisting. + * @param C The type of `TurnContext` being passed around. This simply lets the typing information for any context extensions flow through to dialogs and waterfall steps. + * @param O (Optional) output type returned by prompt. This defaults to a `string` but can be changed by a custom validator passed to the prompt. */ export class TextPrompt extends Prompt { private prompt: prompts.TextPrompt; /** - * Creates a new instance of the prompt. - * - * **Example usage:** - * - * ```JavaScript - * dialogs.add('titlePrompt', new TextPrompt(async (context, value) => { - * if (!value || value.length < 3) { - * await context.sendActivity(`Title should be at least 3 characters long.`); - * return undefined; - * } else { - * return value.trim(); - * } - * })); - * ``` + * Creates a new `TextPrompt` instance. * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent. */ constructor(validator?: PromptValidator) { diff --git a/libraries/botbuilder-dialogs/src/waterfall.ts b/libraries/botbuilder-dialogs/src/waterfall.ts index 2ffacde970..3246745aa6 100644 --- a/libraries/botbuilder-dialogs/src/waterfall.ts +++ b/libraries/botbuilder-dialogs/src/waterfall.ts @@ -10,6 +10,8 @@ import { Dialog, DialogInstance } from './dialog'; import { DialogContext } from './dialogContext'; /** + * :package: **botbuilder-dialogs** + * * Function signature of a waterfall step. * * **Example usage:** @@ -51,12 +53,16 @@ import { DialogContext } from './dialogContext'; export type WaterfallStep = (dc: DialogContext, args?: any, next?: SkipStepFunction) => Promiseable; /** + * :package: **botbuilder-dialogs** + * * When called, control will skip to the next waterfall step. * @param SkipStepFunction.args (Optional) additional argument(s) to pass into the next step. */ export type SkipStepFunction = (args?: any) => Promise; /** + * :package: **botbuilder-dialogs** + * * Dialog optimized for prompting a user with a series of questions. Waterfalls accept a stack of * functions which will be executed in sequence. Each waterfall step can ask a question of the user * and the users response will be passed as an argument to the next waterfall step. diff --git a/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts b/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts index 411e744902..d11c308821 100644 --- a/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/attachmentPrompt.d.ts @@ -12,7 +12,7 @@ import { PromptValidator } from './textPrompt'; * * Prompts the user to upload one or more attachments. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createAttachmentPrompt } = require('botbuilder-prompts'); @@ -25,7 +25,7 @@ export interface AttachmentPrompt { /** * Sends a formated prompt to the user. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await imagePrompt.prompt(context, `Upload an image(s).`); @@ -42,7 +42,7 @@ export interface AttachmentPrompt { * The recognize() method will not automatically re-prompt the user so either the caller or the * prompts custom validator will need to implement re-prompting logic. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const images = await imagePrompt.recognize(context); @@ -59,7 +59,7 @@ export interface AttachmentPrompt { * * Creates a new prompt that asks the user to upload one or more attachments. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createAttachmentPrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/lib/attachmentPrompt.js b/libraries/botbuilder-prompts/lib/attachmentPrompt.js index 53ff1480b1..a6e2fbd982 100644 --- a/libraries/botbuilder-prompts/lib/attachmentPrompt.js +++ b/libraries/botbuilder-prompts/lib/attachmentPrompt.js @@ -6,7 +6,7 @@ const internal_1 = require("./internal"); * * Creates a new prompt that asks the user to upload one or more attachments. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createAttachmentPrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/lib/choicePrompt.d.ts b/libraries/botbuilder-prompts/lib/choicePrompt.d.ts index d55b7cf86c..ee27b9b53f 100644 --- a/libraries/botbuilder-prompts/lib/choicePrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/choicePrompt.d.ts @@ -31,7 +31,7 @@ export declare enum ListStyle { * * Prompts the user to select from a list of choices. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createChoicePrompt } = require('botbuilder-prompts'); @@ -61,7 +61,7 @@ export interface ChoicePrompt { * Further tweaks can be made to the rendering of choices using the * [choiceOptions](#choiceoptions) property. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await colorPrompt.prompt(context, ['red', 'green', 'blue'], `Pick a color.`); @@ -82,7 +82,7 @@ export interface ChoicePrompt { * The search options for the underlying choice recognizer can be tweaked using the prompts * [recognizerOptions](#recognizeroptions) property. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const choice = await colorPrompt.recognize(context, ['red', 'green', 'blue']); @@ -100,7 +100,7 @@ export interface ChoicePrompt { * * Creates a new prompt that asks the user to select from a list of choices. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createChoicePrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/lib/choicePrompt.js b/libraries/botbuilder-prompts/lib/choicePrompt.js index 458d27b665..bf705adf3b 100644 --- a/libraries/botbuilder-prompts/lib/choicePrompt.js +++ b/libraries/botbuilder-prompts/lib/choicePrompt.js @@ -26,7 +26,7 @@ var ListStyle; * * Creates a new prompt that asks the user to select from a list of choices. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createChoicePrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts b/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts index ba0734a659..772ead9455 100644 --- a/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/confirmPrompt.d.ts @@ -27,7 +27,7 @@ export interface ConfirmChoices { * but you can easily add support for other languages using the prompts [choices](#choices) * property. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createConfirmPrompt } = require('botbuilder-prompts'); @@ -48,7 +48,7 @@ export interface ConfirmPrompt { * * ```JavaScript * const confirmPrompt = createConfirmPrompt(); - + * * // Configure yes/no choices for english and spanish (default) * confirmPrompt.choices['*'] = ['sí', 'no']; * confirmPrompt.choices['es'] = ['sí', 'no']; @@ -77,7 +77,7 @@ export interface ConfirmPrompt { * Further tweaks can be made to the rendering of the yes/no choices using the * [choiceOptions](#choiceoptions) property. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await confirmPrompt.prompt(context, `This will cancel your order. Are you sure?`); @@ -94,7 +94,7 @@ export interface ConfirmPrompt { * The recognize() method will not automatically re-prompt the user so either the caller or the * prompts custom validator will need to implement re-prompting logic. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const confirmed = await confirmPrompt.recognize(context); @@ -115,7 +115,7 @@ export interface ConfirmPrompt { * * Creates a new prompt that asks the user to answer a yes/no question. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createConfirmPrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/lib/confirmPrompt.js b/libraries/botbuilder-prompts/lib/confirmPrompt.js index 56db54ddac..7181aaacea 100644 --- a/libraries/botbuilder-prompts/lib/confirmPrompt.js +++ b/libraries/botbuilder-prompts/lib/confirmPrompt.js @@ -9,7 +9,7 @@ const Recognizers = require("@microsoft/recognizers-text-choice"); * * Creates a new prompt that asks the user to answer a yes/no question. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createConfirmPrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts b/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts index 7a1d8bb335..627d896910 100644 --- a/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/datetimePrompt.d.ts @@ -35,7 +35,7 @@ export interface FoundDatetime { * Prompts the user to reply with a date and/or time. The user can use natural language utterances * like "tomorrow at 9am". * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createDatetimePrompt } = require('botbuilder-prompts'); @@ -48,7 +48,7 @@ export interface DatetimePrompt { /** * Sends a formated prompt to the user. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await timePrompt.prompt(context, `What time should I set your alarm for?`); @@ -65,7 +65,7 @@ export interface DatetimePrompt { * The recognize() method will not automatically re-prompt the user so either the caller or the * prompts custom validator will need to implement re-prompting logic. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const values = await timePrompt.recognize(context); @@ -89,7 +89,7 @@ export interface DatetimePrompt { * * Creates a new prompt that asks the user to reply with a date or time. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createDatetimePrompt } = require('botbuilder-prompts'); @@ -102,7 +102,7 @@ export interface DatetimePrompt { * if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } * return value; * } catch (err) { - * await context.sendActivity(`Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); + * await timePrompt.prompt(context, `Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); * return undefined; * } * }); diff --git a/libraries/botbuilder-prompts/lib/datetimePrompt.js b/libraries/botbuilder-prompts/lib/datetimePrompt.js index f23682a1af..0890310e20 100644 --- a/libraries/botbuilder-prompts/lib/datetimePrompt.js +++ b/libraries/botbuilder-prompts/lib/datetimePrompt.js @@ -7,7 +7,7 @@ const Recognizers = require("@microsoft/recognizers-text-date-time"); * * Creates a new prompt that asks the user to reply with a date or time. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createDatetimePrompt } = require('botbuilder-prompts'); @@ -20,7 +20,7 @@ const Recognizers = require("@microsoft/recognizers-text-date-time"); * if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } * return value; * } catch (err) { - * await context.sendActivity(`Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); + * await timePrompt.prompt(context, `Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); * return undefined; * } * }); diff --git a/libraries/botbuilder-prompts/lib/numberPrompt.d.ts b/libraries/botbuilder-prompts/lib/numberPrompt.d.ts index 2b74e5afa8..d7f68eb8fe 100644 --- a/libraries/botbuilder-prompts/lib/numberPrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/numberPrompt.d.ts @@ -12,7 +12,7 @@ import { PromptValidator } from './textPrompt'; * * Prompts the user to reply with a number. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createNumberPrompt } = require('botbuilder-prompts'); @@ -25,7 +25,7 @@ export interface NumberPrompt { /** * Sends a formated prompt to the user. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await agePrompt.prompt(context, `How old are you?`); @@ -42,7 +42,7 @@ export interface NumberPrompt { * The recognize() method will not automatically re-prompt the user so either the caller or the * prompts custom validator will need to implement re-prompting logic. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const age = await agePrompt.recognize(context); @@ -59,7 +59,7 @@ export interface NumberPrompt { * * Creates a new prompt that asks the user to reply with a number. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createNumberPrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/lib/numberPrompt.js b/libraries/botbuilder-prompts/lib/numberPrompt.js index e8da2025de..fbbfe08bf5 100644 --- a/libraries/botbuilder-prompts/lib/numberPrompt.js +++ b/libraries/botbuilder-prompts/lib/numberPrompt.js @@ -7,7 +7,7 @@ const Recognizers = require("@microsoft/recognizers-text-number"); * * Creates a new prompt that asks the user to reply with a number. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createNumberPrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts b/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts index 41782352d0..25c868e559 100644 --- a/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/oauthPrompt.d.ts @@ -25,7 +25,7 @@ export interface OAuthPromptSettings { * * Prompts the user to sign in using the Bot Frameworks Single Sign On (SSO) service. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createOAuthPrompt } = require('botbuilder-prompts'); @@ -46,7 +46,7 @@ export interface OAuthPrompt { * reason you can pass in the `Activity` to send. This should just be an activity of type * `message` and contain at least one attachment that's an `OAuthCard`. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await loginPrompt.prompt(context); @@ -72,7 +72,7 @@ export interface OAuthPrompt { * You should also be prepared for the case where the user fails to enter the correct * "magic code" or simply decides they don't want to click the signin button. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const token = await loginPrompt.recognize(context); @@ -88,7 +88,7 @@ export interface OAuthPrompt { * Attempts to retrieve the cached token for a signed in user. You will generally want to call * this before calling [prompt()](#prompt) to send the user a signin card. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const token = await loginPrompt.getUserToken(context); @@ -102,7 +102,7 @@ export interface OAuthPrompt { /** * Signs the user out of the service. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await loginPrompt.signOutUser(context); @@ -117,7 +117,7 @@ export interface OAuthPrompt { * Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) * service. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * async function ensureLogin(context, state, botLogic) { diff --git a/libraries/botbuilder-prompts/lib/oauthPrompt.js b/libraries/botbuilder-prompts/lib/oauthPrompt.js index f3f55c2141..47656a0cac 100644 --- a/libraries/botbuilder-prompts/lib/oauthPrompt.js +++ b/libraries/botbuilder-prompts/lib/oauthPrompt.js @@ -15,7 +15,7 @@ const internal_1 = require("./internal"); * Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) * service. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * async function ensureLogin(context, state, botLogic) { diff --git a/libraries/botbuilder-prompts/lib/textPrompt.d.ts b/libraries/botbuilder-prompts/lib/textPrompt.d.ts index a662b68705..5f03b50cc3 100644 --- a/libraries/botbuilder-prompts/lib/textPrompt.d.ts +++ b/libraries/botbuilder-prompts/lib/textPrompt.d.ts @@ -11,7 +11,7 @@ import { Promiseable, Activity, TurnContext } from 'botbuilder'; * * Prompts the user to reply with some text. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createTextPrompt } = require('botbuilder-prompts'); @@ -24,10 +24,10 @@ export interface TextPrompt { /** * Sends a formated prompt to the user. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript - * await namePrompt.prompt(context, `What's name?`); + * await namePrompt.prompt(context, `What's your name?`); * ``` * @param context Context for the current turn of conversation. * @param prompt Text or activity to send as the prompt. @@ -41,7 +41,7 @@ export interface TextPrompt { * The recognize() method will not automatically re-prompt the user so either the caller or the * prompts custom validator will need to implement re-prompting logic. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const name = await namePrompt.recognize(context); @@ -69,7 +69,7 @@ export declare type PromptValidator = (context: TurnContext, value: R * * Creates a new prompt that asks the user to enter some text. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createTextPrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/lib/textPrompt.js b/libraries/botbuilder-prompts/lib/textPrompt.js index bc20ec8877..e5b3e58572 100644 --- a/libraries/botbuilder-prompts/lib/textPrompt.js +++ b/libraries/botbuilder-prompts/lib/textPrompt.js @@ -6,7 +6,7 @@ const internal_1 = require("./internal"); * * Creates a new prompt that asks the user to enter some text. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createTextPrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/src/attachmentPrompt.ts b/libraries/botbuilder-prompts/src/attachmentPrompt.ts index 48554c66ad..c59b8da3ab 100644 --- a/libraries/botbuilder-prompts/src/attachmentPrompt.ts +++ b/libraries/botbuilder-prompts/src/attachmentPrompt.ts @@ -14,7 +14,7 @@ import { sendPrompt } from './internal'; * * Prompts the user to upload one or more attachments. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createAttachmentPrompt } = require('botbuilder-prompts'); @@ -27,7 +27,7 @@ export interface AttachmentPrompt { /** * Sends a formated prompt to the user. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await imagePrompt.prompt(context, `Upload an image(s).`); @@ -45,7 +45,7 @@ export interface AttachmentPrompt { * The recognize() method will not automatically re-prompt the user so either the caller or the * prompts custom validator will need to implement re-prompting logic. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const images = await imagePrompt.recognize(context); @@ -63,7 +63,7 @@ export interface AttachmentPrompt { * * Creates a new prompt that asks the user to upload one or more attachments. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createAttachmentPrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/src/choicePrompt.ts b/libraries/botbuilder-prompts/src/choicePrompt.ts index 615d20bc34..9eec7e3e7e 100644 --- a/libraries/botbuilder-prompts/src/choicePrompt.ts +++ b/libraries/botbuilder-prompts/src/choicePrompt.ts @@ -38,7 +38,7 @@ export enum ListStyle { * * Prompts the user to select from a list of choices. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createChoicePrompt } = require('botbuilder-prompts'); @@ -71,7 +71,7 @@ export interface ChoicePrompt { * Further tweaks can be made to the rendering of choices using the * [choiceOptions](#choiceoptions) property. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await colorPrompt.prompt(context, ['red', 'green', 'blue'], `Pick a color.`); @@ -93,7 +93,7 @@ export interface ChoicePrompt { * The search options for the underlying choice recognizer can be tweaked using the prompts * [recognizerOptions](#recognizeroptions) property. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const choice = await colorPrompt.recognize(context, ['red', 'green', 'blue']); @@ -112,7 +112,7 @@ export interface ChoicePrompt { * * Creates a new prompt that asks the user to select from a list of choices. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createChoicePrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/src/confirmPrompt.ts b/libraries/botbuilder-prompts/src/confirmPrompt.ts index 346bf1cb3d..ce983dd2bf 100644 --- a/libraries/botbuilder-prompts/src/confirmPrompt.ts +++ b/libraries/botbuilder-prompts/src/confirmPrompt.ts @@ -31,7 +31,7 @@ export interface ConfirmChoices { * but you can easily add support for other languages using the prompts [choices](#choices) * property. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createConfirmPrompt } = require('botbuilder-prompts'); @@ -52,7 +52,7 @@ export interface ConfirmPrompt { * * ```JavaScript * const confirmPrompt = createConfirmPrompt(); - + * * // Configure yes/no choices for english and spanish (default) * confirmPrompt.choices['*'] = ['sí', 'no']; * confirmPrompt.choices['es'] = ['sí', 'no']; @@ -84,7 +84,7 @@ export interface ConfirmPrompt { * Further tweaks can be made to the rendering of the yes/no choices using the * [choiceOptions](#choiceoptions) property. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await confirmPrompt.prompt(context, `This will cancel your order. Are you sure?`); @@ -102,7 +102,7 @@ export interface ConfirmPrompt { * The recognize() method will not automatically re-prompt the user so either the caller or the * prompts custom validator will need to implement re-prompting logic. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const confirmed = await confirmPrompt.recognize(context); @@ -124,7 +124,7 @@ export interface ConfirmPrompt { * * Creates a new prompt that asks the user to answer a yes/no question. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createConfirmPrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/src/datetimePrompt.ts b/libraries/botbuilder-prompts/src/datetimePrompt.ts index 0ea4ca26c3..d486ea9263 100644 --- a/libraries/botbuilder-prompts/src/datetimePrompt.ts +++ b/libraries/botbuilder-prompts/src/datetimePrompt.ts @@ -41,7 +41,7 @@ export interface FoundDatetime { * Prompts the user to reply with a date and/or time. The user can use natural language utterances * like "tomorrow at 9am". * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createDatetimePrompt } = require('botbuilder-prompts'); @@ -54,7 +54,7 @@ export interface DatetimePrompt { /** * Sends a formated prompt to the user. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await timePrompt.prompt(context, `What time should I set your alarm for?`); @@ -72,7 +72,7 @@ export interface DatetimePrompt { * The recognize() method will not automatically re-prompt the user so either the caller or the * prompts custom validator will need to implement re-prompting logic. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const values = await timePrompt.recognize(context); @@ -97,7 +97,7 @@ export interface DatetimePrompt { * * Creates a new prompt that asks the user to reply with a date or time. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createDatetimePrompt } = require('botbuilder-prompts'); @@ -110,7 +110,7 @@ export interface DatetimePrompt { * if (value.getTime() < new Date().getTime()) { throw new Error('in the past') } * return value; * } catch (err) { - * await context.sendActivity(`Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); + * await timePrompt.prompt(context, `Answer with a time in the future like "tomorrow at 9am" or say "cancel".`); * return undefined; * } * }); diff --git a/libraries/botbuilder-prompts/src/numberPrompt.ts b/libraries/botbuilder-prompts/src/numberPrompt.ts index af7ec6a949..69c7f8e845 100644 --- a/libraries/botbuilder-prompts/src/numberPrompt.ts +++ b/libraries/botbuilder-prompts/src/numberPrompt.ts @@ -15,7 +15,7 @@ import * as Recognizers from '@microsoft/recognizers-text-number'; * * Prompts the user to reply with a number. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createNumberPrompt } = require('botbuilder-prompts'); @@ -28,7 +28,7 @@ export interface NumberPrompt { /** * Sends a formated prompt to the user. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await agePrompt.prompt(context, `How old are you?`); @@ -46,7 +46,7 @@ export interface NumberPrompt { * The recognize() method will not automatically re-prompt the user so either the caller or the * prompts custom validator will need to implement re-prompting logic. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const age = await agePrompt.recognize(context); @@ -64,7 +64,7 @@ export interface NumberPrompt { * * Creates a new prompt that asks the user to reply with a number. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createNumberPrompt } = require('botbuilder-prompts'); diff --git a/libraries/botbuilder-prompts/src/oauthPrompt.ts b/libraries/botbuilder-prompts/src/oauthPrompt.ts index 8cbfcbd938..9b4f65b734 100644 --- a/libraries/botbuilder-prompts/src/oauthPrompt.ts +++ b/libraries/botbuilder-prompts/src/oauthPrompt.ts @@ -30,7 +30,7 @@ export interface OAuthPromptSettings { * * Prompts the user to sign in using the Bot Frameworks Single Sign On (SSO) service. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createOAuthPrompt } = require('botbuilder-prompts'); @@ -51,7 +51,7 @@ export interface OAuthPrompt { * reason you can pass in the `Activity` to send. This should just be an activity of type * `message` and contain at least one attachment that's an `OAuthCard`. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await loginPrompt.prompt(context); @@ -78,7 +78,7 @@ export interface OAuthPrompt { * You should also be prepared for the case where the user fails to enter the correct * "magic code" or simply decides they don't want to click the signin button. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const token = await loginPrompt.recognize(context); @@ -95,7 +95,7 @@ export interface OAuthPrompt { * Attempts to retrieve the cached token for a signed in user. You will generally want to call * this before calling [prompt()](#prompt) to send the user a signin card. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const token = await loginPrompt.getUserToken(context); @@ -110,7 +110,7 @@ export interface OAuthPrompt { /** * Signs the user out of the service. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * await loginPrompt.signOutUser(context); @@ -127,7 +127,7 @@ export interface OAuthPrompt { * Creates a new prompt that asks the user to sign in using the Bot Frameworks Single Sign On (SSO) * service. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * async function ensureLogin(context, state, botLogic) { diff --git a/libraries/botbuilder-prompts/src/textPrompt.ts b/libraries/botbuilder-prompts/src/textPrompt.ts index f14f6cc762..219bab97d6 100644 --- a/libraries/botbuilder-prompts/src/textPrompt.ts +++ b/libraries/botbuilder-prompts/src/textPrompt.ts @@ -13,7 +13,7 @@ import { sendPrompt } from './internal'; * * Prompts the user to reply with some text. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createTextPrompt } = require('botbuilder-prompts'); @@ -26,10 +26,10 @@ export interface TextPrompt { /** * Sends a formated prompt to the user. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript - * await namePrompt.prompt(context, `What's name?`); + * await namePrompt.prompt(context, `What's your name?`); * ``` * @param context Context for the current turn of conversation. * @param prompt Text or activity to send as the prompt. @@ -44,7 +44,7 @@ export interface TextPrompt { * The recognize() method will not automatically re-prompt the user so either the caller or the * prompts custom validator will need to implement re-prompting logic. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const name = await namePrompt.recognize(context); @@ -74,7 +74,7 @@ export type PromptValidator = (context: TurnContext, value: R|undefine * * Creates a new prompt that asks the user to enter some text. * - * **Usage Example** + * **Usage Example:** * * ```JavaScript * const { createTextPrompt } = require('botbuilder-prompts'); From ad875d1b6df5bbbbcc65063d0b3a899ef11cb52c Mon Sep 17 00:00:00 2001 From: Steven Ickman Date: Wed, 25 Apr 2018 12:51:09 -0700 Subject: [PATCH 4/5] updated dialog docs --- doc/botbuilder-dialogs/README.md | 4 ++-- .../botbuilder_dialogs.attachmentprompt.md | 16 ++++++------- .../botbuilder_dialogs.choiceprompt.md | 22 ++++++++--------- .../botbuilder_dialogs.compositecontrol.md | 18 +++++++------- .../botbuilder_dialogs.confirmprompt.md | 22 ++++++++--------- .../classes/botbuilder_dialogs.control.md | 10 ++++---- .../botbuilder_dialogs.datetimeprompt.md | 16 ++++++------- .../botbuilder_dialogs.dialogcontext.md | 24 +++++++++---------- .../classes/botbuilder_dialogs.dialogset.md | 8 +++---- .../botbuilder_dialogs.numberprompt.md | 16 ++++++------- .../classes/botbuilder_dialogs.oauthprompt.md | 14 +++++------ .../classes/botbuilder_dialogs.prompt.md | 16 ++++++------- .../classes/botbuilder_dialogs.textprompt.md | 16 ++++++------- .../classes/botbuilder_dialogs.waterfall.md | 8 +++---- .../botbuilder_dialogs.choicepromptoptions.md | 10 ++++---- .../interfaces/botbuilder_dialogs.dialog.md | 6 ++--- .../botbuilder_dialogs.dialoginstance.md | 4 ++-- .../botbuilder_dialogs.dialogresult.md | 4 ++-- ..._dialogs.oauthpromptsettingswithtimeout.md | 2 +- .../botbuilder_dialogs.promptoptions.md | 8 +++---- .../lib/compositeControl.d.ts | 2 +- .../lib/compositeControl.js | 2 +- .../src/compositeControl.ts | 2 +- 23 files changed, 125 insertions(+), 125 deletions(-) diff --git a/doc/botbuilder-dialogs/README.md b/doc/botbuilder-dialogs/README.md index dd1b8564c6..8f5f8dc135 100644 --- a/doc/botbuilder-dialogs/README.md +++ b/doc/botbuilder-dialogs/README.md @@ -48,7 +48,7 @@ **Τ SkipStepFunction**: *`function`* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:59](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L59)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:59](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L59)* @@ -86,7 +86,7 @@ ___ **Τ WaterfallStep**: *`function`* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L52)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L52)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.attachmentprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.attachmentprompt.md index a37c0c6b6d..a192933c3b 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.attachmentprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.attachmentprompt.md @@ -133,7 +133,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:107](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L107)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:107](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L107)* @@ -164,7 +164,7 @@ Creates a new `AttachmentPrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -184,7 +184,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -229,7 +229,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -274,7 +274,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -309,7 +309,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -341,7 +341,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:113](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L113)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:113](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L113)* @@ -375,7 +375,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:114](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L114)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:114](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L114)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.choiceprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.choiceprompt.md index 3fe89b510d..969953e7d5 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.choiceprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.choiceprompt.md @@ -122,7 +122,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L100)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L100)* @@ -154,7 +154,7 @@ Creates a new `ChoicePrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -174,7 +174,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -217,7 +217,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:112](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L112)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:112](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L112)* @@ -252,7 +252,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -297,7 +297,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -332,7 +332,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -364,7 +364,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:123](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L123)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:123](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L123)* @@ -398,7 +398,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L124)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L124)* @@ -429,7 +429,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:117](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L117)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:117](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L117)* @@ -462,7 +462,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:122](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L122)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:122](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L122)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.compositecontrol.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.compositecontrol.md index 1caef9886d..c92eb623f8 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.compositecontrol.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.compositecontrol.md @@ -69,7 +69,7 @@ On the consumption side the control we created can be used by a bot in much the } ]); -### Control Usage +### Consume as Control If the consuming bot isn't dialog based they can still use your control. They will just need start the control from somewhere within their bots logic by calling the controls `begin()` method: @@ -131,7 +131,7 @@ The `continue()` method returns a `DialogResult` object which can be used to det ### ⊕ **new CompositeControl**(dialogs: *[DialogSet](botbuilder_dialogs.dialogset.md)`TurnContext`*, dialogId: *`string`*, defaultOptions?: *`O`*): [CompositeControl](botbuilder_dialogs.compositecontrol.md) -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L126)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L126)* @@ -162,7 +162,7 @@ Creates a new `CompositeControl` instance. **● defaultOptions**: *`O`* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L126)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L126)* @@ -176,7 +176,7 @@ ___ **● dialogId**: *`string`* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:125](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L125)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:125](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L125)* @@ -190,7 +190,7 @@ ___ **● dialogs**: *[DialogSet](botbuilder_dialogs.dialogset.md)`TurnContext`* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L124)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L124)* @@ -208,7 +208,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:152](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L152)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:152](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L152)* @@ -251,7 +251,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:169](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L169)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:169](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L169)* @@ -294,7 +294,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogBegin](../interfaces/botbuilder_dialogs.dialog.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:170](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L170)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:170](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L170)* @@ -327,7 +327,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogContinue](../interfaces/botbuilder_dialogs.dialog.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:171](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L171)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:171](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L171)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.confirmprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.confirmprompt.md index 3d12aa2d97..10a4c7682b 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.confirmprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.confirmprompt.md @@ -131,7 +131,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L124)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L124)* @@ -163,7 +163,7 @@ Creates a new `ConfirmPrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -177,7 +177,7 @@ ___ **● choices**: *`prompts.ConfirmChoices`* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L124)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L124)* @@ -212,7 +212,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -255,7 +255,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:136](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L136)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:136](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L136)* @@ -290,7 +290,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -335,7 +335,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -370,7 +370,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -402,7 +402,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:142](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L142)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:142](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L142)* @@ -436,7 +436,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:143](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L143)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:143](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L143)* @@ -467,7 +467,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:141](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L141)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:141](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L141)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.control.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.control.md index 1626d85f65..232462113b 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.control.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.control.md @@ -74,7 +74,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor ### ⊕ **new Control**(defaultOptions?: *`O`*): [Control](botbuilder_dialogs.control.md) -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -103,7 +103,7 @@ Creates a new Control instance. **● defaultOptions**: *`O`* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -121,7 +121,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -164,7 +164,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -207,7 +207,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogBegin](../interfaces/botbuilder_dialogs.dialog.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:69](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L69)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:69](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L69)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.datetimeprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.datetimeprompt.md index b49ebb09b6..2ec91b967b 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.datetimeprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.datetimeprompt.md @@ -123,7 +123,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:92](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L92)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:92](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L92)* @@ -155,7 +155,7 @@ Creates a new `DatetimePrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -175,7 +175,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -220,7 +220,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -265,7 +265,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -300,7 +300,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -332,7 +332,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:99](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L99)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:99](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L99)* @@ -366,7 +366,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L100)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L100)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogcontext.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogcontext.md index 974061c42e..d71fd85f68 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogcontext.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogcontext.md @@ -47,7 +47,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor ### ⊕ **new DialogContext**(dialogs: *[DialogSet](botbuilder_dialogs.dialogset.md)`C`*, context: *`C`*, stack: *[DialogInstance](../interfaces/botbuilder_dialogs.dialoginstance.md)[]*): [DialogContext](botbuilder_dialogs.dialogcontext.md) -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:43](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L43)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:43](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L43)* @@ -78,7 +78,7 @@ Creates a new DialogContext instance. **● context**: *`C`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:41](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L41)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:41](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L41)* @@ -92,7 +92,7 @@ ___ **● dialogResult**: *[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`any`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:57](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L57)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:57](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L57)* @@ -109,7 +109,7 @@ ___ **● dialogs**: *[DialogSet](botbuilder_dialogs.dialogset.md)`C`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L40)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L40)* @@ -123,7 +123,7 @@ ___ **● instance**: *[DialogInstance](../interfaces/botbuilder_dialogs.dialoginstance.md)⎮`undefined`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L52)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L52)* @@ -140,7 +140,7 @@ ___ **● stack**: *[DialogInstance](../interfaces/botbuilder_dialogs.dialoginstance.md)[]* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:42](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L42)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:42](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L42)* @@ -158,7 +158,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:70](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L70)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:70](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L70)* @@ -197,7 +197,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:103](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L103)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:103](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L103)* @@ -231,7 +231,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:128](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L128)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:128](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L128)* @@ -277,7 +277,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:138](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L138)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:138](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L138)* @@ -306,7 +306,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:86](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L86)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:86](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L86)* @@ -352,7 +352,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:160](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L160)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:160](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L160)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogset.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogset.md index 5173047bb9..e9c8069a6b 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogset.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogset.md @@ -90,7 +90,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor -*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:121](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L121)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:121](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L121)* @@ -121,7 +121,7 @@ Adds a new dialog to the set and returns the added dialog. -*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:122](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L122)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:122](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L122)* @@ -152,7 +152,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:123](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L123)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:123](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L123)* @@ -183,7 +183,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:135](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L135)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:135](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L135)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.numberprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.numberprompt.md index 1f594f28e9..623e3cc9c9 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.numberprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.numberprompt.md @@ -130,7 +130,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L100)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L100)* @@ -162,7 +162,7 @@ Creates a new `NumberPrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -182,7 +182,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -227,7 +227,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -272,7 +272,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -307,7 +307,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -339,7 +339,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:107](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L107)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:107](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L107)* @@ -373,7 +373,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:108](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L108)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:108](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L108)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.oauthprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.oauthprompt.md index 3f0f7c9baa..7ce2af355b 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.oauthprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.oauthprompt.md @@ -132,7 +132,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Control](botbuilder_dialogs.control.md).[constructor](botbuilder_dialogs.control.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L126)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L126)* @@ -164,7 +164,7 @@ Creates a new `OAuthPrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -184,7 +184,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -229,7 +229,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -272,7 +272,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:133](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L133)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:133](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L133)* @@ -305,7 +305,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogContinue](../interfaces/botbuilder_dialogs.dialog.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:134](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L134)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:134](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L134)* @@ -335,7 +335,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:149](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L149)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:149](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L149)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.prompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.prompt.md index b010cafc07..3561c16036 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.prompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.prompt.md @@ -96,7 +96,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Control](botbuilder_dialogs.control.md).[constructor](botbuilder_dialogs.control.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L34)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L34)* @@ -124,7 +124,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -144,7 +144,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -189,7 +189,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -232,7 +232,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -265,7 +265,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogContinue](../interfaces/botbuilder_dialogs.dialog.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -295,7 +295,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L36)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L36)* @@ -327,7 +327,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L37)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L37)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.textprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.textprompt.md index ddc9712660..d4931abc01 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.textprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.textprompt.md @@ -120,7 +120,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:89](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L89)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:89](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L89)* @@ -151,7 +151,7 @@ Creates a new `TextPrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -171,7 +171,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -216,7 +216,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -261,7 +261,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -296,7 +296,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -328,7 +328,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:95](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L95)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:95](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L95)* @@ -362,7 +362,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:96](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L96)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:96](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L96)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.waterfall.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.waterfall.md index 13ecc5b400..8141c7e301 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.waterfall.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.waterfall.md @@ -91,7 +91,7 @@ You should generally call `dc.end()` or `dc.replace()` from your last waterfall ### ⊕ **new Waterfall**(steps: *[WaterfallStep](../#waterfallstep)`C`[]*): [Waterfall](botbuilder_dialogs.waterfall.md) -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:131](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L131)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:131](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L131)* @@ -124,7 +124,7 @@ Creates a new waterfall dialog containing the given array of steps. *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogBegin](../interfaces/botbuilder_dialogs.dialog.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:137](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L137)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:137](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L137)* @@ -157,7 +157,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogContinue](../interfaces/botbuilder_dialogs.dialog.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:138](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L138)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:138](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L138)* @@ -189,7 +189,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogResume](../interfaces/botbuilder_dialogs.dialog.md#dialogresume)* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:139](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L139)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:139](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L139)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.choicepromptoptions.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.choicepromptoptions.md index 2248012761..9f6b7e7c87 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.choicepromptoptions.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.choicepromptoptions.md @@ -30,7 +30,7 @@ Additional options that can be used to configure a `ChoicePrompt`. **● choices**: *`any`[]* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L20)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L20)* @@ -49,7 +49,7 @@ ___ *Inherited from [PromptOptions](botbuilder_dialogs.promptoptions.md).[prompt](botbuilder_dialogs.promptoptions.md#prompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L19)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L19)* @@ -68,7 +68,7 @@ ___ *Inherited from [PromptOptions](botbuilder_dialogs.promptoptions.md).[retryPrompt](botbuilder_dialogs.promptoptions.md#retryprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L23)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L23)* @@ -87,7 +87,7 @@ ___ *Inherited from [PromptOptions](botbuilder_dialogs.promptoptions.md).[retrySpeak](botbuilder_dialogs.promptoptions.md#retryspeak)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L25)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L25)* @@ -106,7 +106,7 @@ ___ *Inherited from [PromptOptions](botbuilder_dialogs.promptoptions.md).[speak](botbuilder_dialogs.promptoptions.md#speak)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L21)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialog.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialog.md index f29e7f24bd..348e53ee5b 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialog.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialog.md @@ -38,7 +38,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialog.d.ts#L24)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialog.d.ts#L24)* @@ -72,7 +72,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialog.d.ts#L34)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialog.d.ts#L34)* @@ -107,7 +107,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:45](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialog.d.ts#L45)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:45](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialog.d.ts#L45)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialoginstance.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialoginstance.md index 8af19b1add..405061a317 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialoginstance.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialoginstance.md @@ -20,7 +20,7 @@ Tracking information for a dialog on the stack. **● id**: *`string`* -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:53](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialog.d.ts#L53)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:53](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialog.d.ts#L53)* @@ -37,7 +37,7 @@ ___ **● state**: *`T`* -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialog.d.ts#L55)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialog.d.ts#L55)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialogresult.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialogresult.md index 326f8398a1..a979c3d671 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialogresult.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialogresult.md @@ -19,7 +19,7 @@ Result returned to the caller of one of the various stack manipulation methods a **● active**: *`boolean`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L21)* @@ -36,7 +36,7 @@ ___ **● result**: *`T`⎮`undefined`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:31](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L31)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:31](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L31)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md index 7b31cc7055..b52f3ec1b9 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md @@ -30,7 +30,7 @@ Settings used to configure an `OAuthPrompt` instance. Includes the ability to ad **● timeout**: *`number`* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L24)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L24)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.promptoptions.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.promptoptions.md index 6e09474ad0..6d97ca975c 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.promptoptions.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.promptoptions.md @@ -30,7 +30,7 @@ Basic configuration options supported by all prompts. **● prompt**: *`string`⎮`Partial`.<`Activity`>* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L19)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L19)* @@ -47,7 +47,7 @@ ___ **● retryPrompt**: *`string`⎮`Partial`.<`Activity`>* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L23)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L23)* @@ -64,7 +64,7 @@ ___ **● retrySpeak**: *`string`* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L25)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L25)* @@ -81,7 +81,7 @@ ___ **● speak**: *`string`* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/b50d910/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L21)* diff --git a/libraries/botbuilder-dialogs/lib/compositeControl.d.ts b/libraries/botbuilder-dialogs/lib/compositeControl.d.ts index 9d05e17d41..789f1af02a 100644 --- a/libraries/botbuilder-dialogs/lib/compositeControl.d.ts +++ b/libraries/botbuilder-dialogs/lib/compositeControl.d.ts @@ -90,7 +90,7 @@ import { DialogSet } from './dialogSet'; * ]); * ``` * - * ### Control Usage + * ### Consume as Control * * If the consuming bot isn't dialog based they can still use your control. They will just need * start the control from somewhere within their bots logic by calling the controls `begin()` diff --git a/libraries/botbuilder-dialogs/lib/compositeControl.js b/libraries/botbuilder-dialogs/lib/compositeControl.js index 866aabf09f..d34114e893 100644 --- a/libraries/botbuilder-dialogs/lib/compositeControl.js +++ b/libraries/botbuilder-dialogs/lib/compositeControl.js @@ -81,7 +81,7 @@ Object.defineProperty(exports, "__esModule", { value: true }); * ]); * ``` * - * ### Control Usage + * ### Consume as Control * * If the consuming bot isn't dialog based they can still use your control. They will just need * start the control from somewhere within their bots logic by calling the controls `begin()` diff --git a/libraries/botbuilder-dialogs/src/compositeControl.ts b/libraries/botbuilder-dialogs/src/compositeControl.ts index a8ca83fdf3..8b12d26f7a 100644 --- a/libraries/botbuilder-dialogs/src/compositeControl.ts +++ b/libraries/botbuilder-dialogs/src/compositeControl.ts @@ -92,7 +92,7 @@ import { DialogSet } from './dialogSet'; * ]); * ``` * - * ### Control Usage + * ### Consume as Control * * If the consuming bot isn't dialog based they can still use your control. They will just need * start the control from somewhere within their bots logic by calling the controls `begin()` From 01440f1dbc0db3c7ec134804ebd6ba945d731aa8 Mon Sep 17 00:00:00 2001 From: Steven Ickman Date: Wed, 25 Apr 2018 15:45:23 -0700 Subject: [PATCH 5/5] Updated composite control --- doc/botbuilder-dialogs/README.md | 4 +- .../botbuilder_dialogs.attachmentprompt.md | 22 ++-- .../botbuilder_dialogs.choiceprompt.md | 28 ++--- .../botbuilder_dialogs.compositecontrol.md | 107 ++++++++---------- .../botbuilder_dialogs.confirmprompt.md | 28 ++--- .../classes/botbuilder_dialogs.control.md | 10 +- .../botbuilder_dialogs.datetimeprompt.md | 20 ++-- .../botbuilder_dialogs.dialogcontext.md | 34 +++--- .../classes/botbuilder_dialogs.dialogset.md | 16 +-- .../botbuilder_dialogs.numberprompt.md | 20 ++-- .../classes/botbuilder_dialogs.oauthprompt.md | 18 +-- .../classes/botbuilder_dialogs.prompt.md | 16 +-- .../classes/botbuilder_dialogs.textprompt.md | 20 ++-- .../classes/botbuilder_dialogs.waterfall.md | 8 +- .../botbuilder_dialogs.choicepromptoptions.md | 10 +- .../interfaces/botbuilder_dialogs.dialog.md | 6 +- .../botbuilder_dialogs.dialoginstance.md | 4 +- .../botbuilder_dialogs.dialogresult.md | 4 +- ..._dialogs.oauthpromptsettingswithtimeout.md | 2 +- .../botbuilder_dialogs.promptoptions.md | 8 +- .../lib/compositeControl.d.ts | 66 +++++------ .../lib/compositeControl.js | 60 +++++----- .../lib/compositeControl.js.map | 2 +- .../botbuilder-dialogs/lib/dialogContext.d.ts | 10 +- .../botbuilder-dialogs/lib/dialogContext.js | 10 +- .../botbuilder-dialogs/lib/dialogSet.d.ts | 8 +- libraries/botbuilder-dialogs/lib/dialogSet.js | 6 +- .../lib/prompts/attachmentPrompt.d.ts | 6 +- .../lib/prompts/attachmentPrompt.js | 6 +- .../lib/prompts/choicePrompt.d.ts | 6 +- .../lib/prompts/choicePrompt.js | 6 +- .../lib/prompts/confirmPrompt.d.ts | 6 +- .../lib/prompts/confirmPrompt.js | 6 +- .../lib/prompts/datetimePrompt.d.ts | 4 +- .../lib/prompts/datetimePrompt.js | 4 +- .../lib/prompts/numberPrompt.d.ts | 4 +- .../lib/prompts/numberPrompt.js | 4 +- .../lib/prompts/oauthPrompt.d.ts | 4 +- .../lib/prompts/oauthPrompt.js | 4 +- .../lib/prompts/textPrompt.d.ts | 4 +- .../lib/prompts/textPrompt.js | 4 +- .../src/compositeControl.ts | 70 ++++++------ .../botbuilder-dialogs/src/dialogContext.ts | 10 +- libraries/botbuilder-dialogs/src/dialogSet.ts | 8 +- .../src/prompts/attachmentPrompt.ts | 6 +- .../src/prompts/choicePrompt.ts | 6 +- .../src/prompts/confirmPrompt.ts | 6 +- .../src/prompts/datetimePrompt.ts | 4 +- .../src/prompts/numberPrompt.ts | 4 +- .../src/prompts/oauthPrompt.ts | 4 +- .../src/prompts/textPrompt.ts | 4 +- .../tests/compositeControl.test.js | 28 +---- 52 files changed, 371 insertions(+), 394 deletions(-) diff --git a/doc/botbuilder-dialogs/README.md b/doc/botbuilder-dialogs/README.md index 8f5f8dc135..6d4082b44b 100644 --- a/doc/botbuilder-dialogs/README.md +++ b/doc/botbuilder-dialogs/README.md @@ -48,7 +48,7 @@ **Τ SkipStepFunction**: *`function`* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:59](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L59)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:59](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L59)* @@ -86,7 +86,7 @@ ___ **Τ WaterfallStep**: *`function`* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L52)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L52)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.attachmentprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.attachmentprompt.md index a192933c3b..bcab83635e 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.attachmentprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.attachmentprompt.md @@ -23,17 +23,17 @@ When used with your bots `DialogSet` you can simply add a new instance of the pr dialogs.add('uploadImage', [ async function (dc) { - return dc.prompt('attachmentPrompt', `Send me image(s)`); + await dc.prompt('attachmentPrompt', `Send me image(s)`); }, async function (dc, attachments) { await dc.context.sendActivity(`Processing ${attachments.length} images.`); - return dc.end(); + await dc.end(); } ]); If the users response to the prompt fails to be recognized they will be automatically re-prompted to try again. By default the original prompt is re-sent to the user but you can provide an alternate prompt to send by passing in additional options: - return dc.prompt('attachmentPrompt', `Send me image(s)`, { retryPrompt: `I didn't get anything. Send me an image.` }); + await dc.prompt('attachmentPrompt', `Send me image(s)`, { retryPrompt: `I didn't get anything. Send me an image.` }); The prompts retry logic can also be completely customized by passing the prompts constructor a custom validator: @@ -133,7 +133,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:107](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L107)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:107](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L107)* @@ -164,7 +164,7 @@ Creates a new `AttachmentPrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -184,7 +184,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -229,7 +229,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -274,7 +274,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -309,7 +309,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -341,7 +341,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:113](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L113)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:113](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L113)* @@ -375,7 +375,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:114](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L114)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts:114](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts#L114)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.choiceprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.choiceprompt.md index 969953e7d5..59cc3bc07a 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.choiceprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.choiceprompt.md @@ -23,18 +23,18 @@ When used with your bots `DialogSet` you can simply add a new instance of the pr dialogs.add('colorPrompt', [ async function (dc) { - return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue']); + await dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue']); }, async function (dc, choice) { const color = choice.value; await dc.context.sendActivity(`I like ${color} too!`); - return dc.end(); + await dc.end(); } ]); If the users response to the prompt fails to be recognized they will be automatically re-prompted to try again. By default the original prompt is re-sent to the user but you can provide an alternate prompt to send by passing in additional options: - return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue'], { retryPrompt: `I didn't catch that. Select a color from the list.` }); + await dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue'], { retryPrompt: `I didn't catch that. Select a color from the list.` }); ### Control Usage @@ -122,7 +122,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L100)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L100)* @@ -154,7 +154,7 @@ Creates a new `ChoicePrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -174,7 +174,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -217,7 +217,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:112](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L112)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:112](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L112)* @@ -252,7 +252,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -297,7 +297,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -332,7 +332,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -364,7 +364,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:123](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L123)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:123](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L123)* @@ -398,7 +398,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L124)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L124)* @@ -429,7 +429,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:117](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L117)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:117](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L117)* @@ -462,7 +462,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:122](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L122)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:122](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L122)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.compositecontrol.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.compositecontrol.md index c92eb623f8..0004e4d49d 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.compositecontrol.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.compositecontrol.md @@ -23,30 +23,30 @@ Here's a fairly simple example of a `ProfileControl` that's designed to prompt t class ProfileControl extends CompositeControl { constructor() { - super(dialogs, 'fillProfile'); + super('fillProfile'); + + this.dialogs.add('fillProfile', [ + async function (dc, options) { + dc.instance.state = {}; + await dc.prompt('textPrompt', `What's your name?`); + }, + async function (dc, name) { + dc.instance.state.name = name; + await dc.prompt('textPrompt', `What's your phone number?`); + }, + async function (dc, phone) { + dc.instance.state.phone = phone; + + // Return completed profile + await dc.end(dc.instance.state); + } + ]); + + this.dialogs.add('textPrompt', new TextPrompt()); } } module.exports.ProfileControl = ProfileControl; - dialogs.add('fillProfile', [ - async function (dc, options) { - dc.instance.state = {}; - return dc.prompt('textPrompt', `What's your name?`); - }, - async function (dc, name) { - dc.instance.state.name = name; - return dc.prompt('textPrompt', `What's your phone number?`); - }, - async function (dc, phone) { - dc.instance.state.phone = phone; - - // Return completed profile - return dc.end(dc.instance.state); - } - ]); - - dialogs.add('textPrompt', new TextPrompt()); - ### Consume as Dialog On the consumption side the control we created can be used by a bot in much the same way they would use any other prompt. They can add a new instance of the control as a named dialog to their bots `DialogSet` and then start it using a call to `DialogContext.begin()`. If the control accepts options these can be passed in to the `begin()` call as well. @@ -61,11 +61,11 @@ On the consumption side the control we created can be used by a bot in much the dialogs.add('firstrun', [ async function (dc) { await dc.context.sendActivity(`Welcome! We need to ask a few questions to get started.`); - return dc.begin('getProfile'); + await dc.begin('getProfile'); }, async function (dc, profile) { await dc.context.sendActivity(`Thanks ${profile.name}!`); - return dc.end(); + await dc.end(); } ]); @@ -94,11 +94,15 @@ The `continue()` method returns a `DialogResult` object which can be used to det #### O -(Optional) options that can be passed into the [begin()](#begin) method. +(Optional) options that can be passed into the begin() method. + +#### C : `TurnContext` + +(Optional) type of `TurnContext` being passed to dialogs in the set. ## Implements -* [Dialog](../interfaces/botbuilder_dialogs.dialog.md)`TurnContext` +* [Dialog](../interfaces/botbuilder_dialogs.dialog.md)`C` ## Index @@ -109,7 +113,6 @@ The `continue()` method returns a `DialogResult` object which can be used to det ### Properties -* [defaultOptions](botbuilder_dialogs.compositecontrol.md#defaultoptions) * [dialogId](botbuilder_dialogs.compositecontrol.md#dialogid) * [dialogs](botbuilder_dialogs.compositecontrol.md#dialogs) @@ -128,10 +131,10 @@ The `continue()` method returns a `DialogResult` object which can be used to det -### ⊕ **new CompositeControl**(dialogs: *[DialogSet](botbuilder_dialogs.dialogset.md)`TurnContext`*, dialogId: *`string`*, defaultOptions?: *`O`*): [CompositeControl](botbuilder_dialogs.compositecontrol.md) +### ⊕ **new CompositeControl**(dialogId: *`string`*, dialogs?: *[DialogSet](botbuilder_dialogs.dialogset.md)`C`*): [CompositeControl](botbuilder_dialogs.compositecontrol.md) -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L126)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:127](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L127)* @@ -142,9 +145,8 @@ Creates a new `CompositeControl` instance. | Param | Type | Description | | ------ | ------ | ------ | -| dialogs | [DialogSet](botbuilder_dialogs.dialogset.md)`TurnContext` | Controls dialog set. | | dialogId | `string` | ID of the root dialog that should be started anytime the control is started. | -| defaultOptions | `O` | (Optional) set of default options that should be passed to controls root dialog. These will be merged with arguments passed in by the caller. | +| dialogs | [DialogSet](botbuilder_dialogs.dialogset.md)`C` | (Optional) set of existing dialogs the control should use. If omitted an empty set will be created. | @@ -156,27 +158,13 @@ Creates a new `CompositeControl` instance. ## Properties - - -### «Protected» defaultOptions - -**● defaultOptions**: *`O`* - -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L126)* - - - - - -___ - ### «Protected» dialogId **● dialogId**: *`string`* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:125](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L125)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:125](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L125)* @@ -188,10 +176,13 @@ ___ ### «Protected» dialogs -**● dialogs**: *[DialogSet](botbuilder_dialogs.dialogset.md)`TurnContext`* +**● dialogs**: *[DialogSet](botbuilder_dialogs.dialogset.md)`C`* + +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:127](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L127)* + -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L124)* +The controls dialog set. @@ -204,11 +195,11 @@ ___ ### begin -► **begin**(context: *`TurnContext`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> +► **begin**(context: *`C`*, state: *`object`*, options?: *`O`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:152](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L152)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:152](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L152)* @@ -227,7 +218,7 @@ Starts the control. Depending on the control, its possible for the control to fi | Param | Type | Description | | ------ | ------ | ------ | -| context | `TurnContext` | Context for the current turn of the conversation with the user. | +| context | `C` | Context for the current turn of the conversation with the user. | | state | `object` | A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. | | options | `O` | (Optional) additional options supported by the control. | @@ -247,11 +238,11 @@ ___ ### continue -► **continue**(context: *`TurnContext`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> +► **continue**(context: *`C`*, state: *`object`*): `Promise`.<[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`R`> -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:169](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L169)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:169](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L169)* @@ -269,7 +260,7 @@ Passes a users reply to the control for further processing. The bot should keep | Param | Type | Description | | ------ | ------ | ------ | -| context | `TurnContext` | Context for the current turn of the conversation with the user. | +| context | `C` | Context for the current turn of the conversation with the user. | | state | `object` | A state object that was previously initialized by a call to [begin()](#begin). | @@ -288,13 +279,13 @@ ___ ### dialogBegin -► **dialogBegin**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`TurnContext`*, dialogArgs?: *`any`*): `Promise`.<`any`> +► **dialogBegin**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*, dialogArgs?: *`any`*): `Promise`.<`any`> *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogBegin](../interfaces/botbuilder_dialogs.dialog.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:170](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L170)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:170](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L170)* @@ -302,7 +293,7 @@ ___ | Param | Type | Description | | ------ | ------ | ------ | -| dc | [DialogContext](botbuilder_dialogs.dialogcontext.md)`TurnContext` | - | +| dc | [DialogContext](botbuilder_dialogs.dialogcontext.md)`C` | - | | dialogArgs | `any` | - | @@ -321,13 +312,13 @@ ___ ### dialogContinue -► **dialogContinue**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`TurnContext`*): `Promise`.<`any`> +► **dialogContinue**(dc: *[DialogContext](botbuilder_dialogs.dialogcontext.md)`C`*): `Promise`.<`any`> *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogContinue](../interfaces/botbuilder_dialogs.dialog.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:171](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L171)* +*Defined in [libraries/botbuilder-dialogs/lib/compositeControl.d.ts:171](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/compositeControl.d.ts#L171)* @@ -335,7 +326,7 @@ ___ | Param | Type | Description | | ------ | ------ | ------ | -| dc | [DialogContext](botbuilder_dialogs.dialogcontext.md)`TurnContext` | - | +| dc | [DialogContext](botbuilder_dialogs.dialogcontext.md)`C` | - | diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.confirmprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.confirmprompt.md index 10a4c7682b..ae56e62565 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.confirmprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.confirmprompt.md @@ -23,19 +23,19 @@ When used with your bots `DialogSet` you can simply add a new instance of the pr dialogs.add('confirmCancel', [ async function (dc) { - return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`); + await dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`); }, async function (dc, cancel) { if (cancel) { await dc.context.sendActivity(`Order cancelled.`); } - return dc.end(); + await dc.end(); } ]); If the users response to the prompt fails to be recognized they will be automatically re-prompted to try again. By default the original prompt is re-sent to the user but you can provide an alternate prompt to send by passing in additional options: - return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`, { retryPrompt: `Please answer "yes" or "no".` }); + await dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`, { retryPrompt: `Please answer "yes" or "no".` }); The prompts retry logic can also be completely customized by passing the prompts constructor a custom validator: @@ -131,7 +131,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L124)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L124)* @@ -163,7 +163,7 @@ Creates a new `ConfirmPrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -177,7 +177,7 @@ ___ **● choices**: *`prompts.ConfirmChoices`* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L124)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:124](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L124)* @@ -212,7 +212,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -255,7 +255,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:136](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L136)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:136](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L136)* @@ -290,7 +290,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -335,7 +335,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -370,7 +370,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -402,7 +402,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:142](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L142)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:142](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L142)* @@ -436,7 +436,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:143](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L143)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:143](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L143)* @@ -467,7 +467,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:141](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L141)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts:141](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts#L141)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.control.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.control.md index 232462113b..50691cb9f9 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.control.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.control.md @@ -74,7 +74,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor ### ⊕ **new Control**(defaultOptions?: *`O`*): [Control](botbuilder_dialogs.control.md) -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -103,7 +103,7 @@ Creates a new Control instance. **● defaultOptions**: *`O`* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -121,7 +121,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -164,7 +164,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -207,7 +207,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogBegin](../interfaces/botbuilder_dialogs.dialog.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:69](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L69)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:69](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L69)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.datetimeprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.datetimeprompt.md index 2ec91b967b..2caec1b6e1 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.datetimeprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.datetimeprompt.md @@ -23,11 +23,11 @@ When used with your bots `DialogSet` you can simply add a new instance of the pr dialogs.add('setAlarmTime', [ async function (dc) { - return dc.prompt('datetimePrompt', `What time should I set your alarm for?`); + await dc.prompt('datetimePrompt', `What time should I set your alarm for?`); }, async function (dc, time) { await dc.context.sendActivity(`Alarm time set`); - return dc.end(); + await dc.end(); } ]); @@ -123,7 +123,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:92](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L92)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:92](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L92)* @@ -155,7 +155,7 @@ Creates a new `DatetimePrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -175,7 +175,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -220,7 +220,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -265,7 +265,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -300,7 +300,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -332,7 +332,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:99](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L99)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:99](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L99)* @@ -366,7 +366,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L100)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts#L100)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogcontext.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogcontext.md index d71fd85f68..6dce03902e 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogcontext.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogcontext.md @@ -47,7 +47,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor ### ⊕ **new DialogContext**(dialogs: *[DialogSet](botbuilder_dialogs.dialogset.md)`C`*, context: *`C`*, stack: *[DialogInstance](../interfaces/botbuilder_dialogs.dialoginstance.md)[]*): [DialogContext](botbuilder_dialogs.dialogcontext.md) -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:43](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L43)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:43](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L43)* @@ -78,7 +78,7 @@ Creates a new DialogContext instance. **● context**: *`C`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:41](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L41)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:41](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L41)* @@ -92,7 +92,7 @@ ___ **● dialogResult**: *[DialogResult](../interfaces/botbuilder_dialogs.dialogresult.md)`any`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:57](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L57)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:57](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L57)* @@ -109,7 +109,7 @@ ___ **● dialogs**: *[DialogSet](botbuilder_dialogs.dialogset.md)`C`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L40)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:40](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L40)* @@ -123,7 +123,7 @@ ___ **● instance**: *[DialogInstance](../interfaces/botbuilder_dialogs.dialoginstance.md)⎮`undefined`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L52)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:52](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L52)* @@ -140,7 +140,7 @@ ___ **● stack**: *[DialogInstance](../interfaces/botbuilder_dialogs.dialoginstance.md)[]* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:42](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L42)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:42](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L42)* @@ -158,7 +158,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:70](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L70)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:70](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L70)* @@ -167,7 +167,7 @@ Pushes a new dialog onto the dialog stack. **Example usage:** const dc = dialogs.createContext(context, stack); - return dc.begin('greeting', user); + await dc.begin('greeting', user); **Parameters:** @@ -197,7 +197,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:103](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L103)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:103](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L103)* @@ -208,7 +208,7 @@ Continues execution of the active dialog, if there is one, by passing the contex const dc = dialogs.createContext(context, dialogStack); return dc.continue().then(() => { if (!context.responded) { - return dc.begin('fallback'); + await dc.begin('fallback'); } }); @@ -231,7 +231,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:128](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L128)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:128](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L128)* @@ -245,7 +245,7 @@ The parent dialog will have its `Dialog.resume()` method invoked with any return function (dc) { const elapsed = new Date().getTime() - started; dc.batch.reply(`I've been running for ${elapsed / 1000} seconds.`); - return dc.end(elapsed); + await dc.end(elapsed); } ]); const started = new Date().getTime(); @@ -277,7 +277,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:138](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L138)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:138](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L138)* @@ -306,7 +306,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:86](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L86)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:86](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L86)* @@ -314,7 +314,7 @@ Helper function to simplify formatting the options for calling a prompt dialog. **Example usage:** - return dc.prompt('confirmPrompt', `Are you sure you'd like to quit?`); + await dc.prompt('confirmPrompt', `Are you sure you'd like to quit?`); **Type parameters:** @@ -352,7 +352,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:160](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L160)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:160](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L160)* @@ -363,7 +363,7 @@ Ends the active dialog and starts a new dialog in its place. This is particularl dialogs.add('loop', [ function (dc, args) { dc.instance.state = args; - return dc.begin(args.dialogId); + await dc.begin(args.dialogId); }, function (dc) { const args = dc.instance.state; diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogset.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogset.md index e9c8069a6b..b3f62e360b 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogset.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.dialogset.md @@ -20,17 +20,17 @@ The dialogs library uses a stack based metaphor to manage a bot conversation wit dialogs.add('fillProfile', [ async function (dc, options) { dc.instance.state = {}; - return dc.prompt('textPrompt', `What's your name?`); + await dc.prompt('textPrompt', `What's your name?`); }, async function (dc, name) { dc.instance.state.name = name; - return dc.prompt('textPrompt', `What's your phone number?`); + await dc.prompt('textPrompt', `What's your phone number?`); }, async function (dc, phone) { dc.instance.state.phone = phone; // Return completed profile - return dc.end(dc.instance.state); + await dc.end(dc.instance.state); } ]); @@ -90,7 +90,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor -*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:121](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L121)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:121](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L121)* @@ -101,7 +101,7 @@ Adds a new dialog to the set and returns the added dialog. dialogs.add('greeting', [ async function (dc) { await dc.context.sendActivity(`Hello world!`); - return dc.end(); + await dc.end(); } ]); @@ -121,7 +121,7 @@ Adds a new dialog to the set and returns the added dialog. -*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:122](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L122)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:122](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L122)* @@ -152,7 +152,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:123](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L123)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:123](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L123)* @@ -183,7 +183,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:135](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L135)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogSet.d.ts:135](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogSet.d.ts#L135)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.numberprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.numberprompt.md index 623e3cc9c9..e68e2523aa 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.numberprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.numberprompt.md @@ -23,7 +23,7 @@ When used with your bots `DialogSet` you can simply add a new instance of the pr dialogs.add('askAge', [ async function (dc) { - return dc.prompt('agePrompt', `How old are you?`); + await dc.prompt('agePrompt', `How old are you?`); }, async function (dc, age) { if (age < 40) { @@ -31,7 +31,7 @@ When used with your bots `DialogSet` you can simply add a new instance of the pr } else { await dc.context.sendActivity(`I hear ${age} is the new ${age - 10} :)`); } - return dc.end(); + await dc.end(); } ]); @@ -130,7 +130,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L100)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:100](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L100)* @@ -162,7 +162,7 @@ Creates a new `NumberPrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -182,7 +182,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -227,7 +227,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -272,7 +272,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -307,7 +307,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -339,7 +339,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:107](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L107)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:107](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L107)* @@ -373,7 +373,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:108](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L108)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts:108](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts#L108)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.oauthprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.oauthprompt.md index 7ce2af355b..e7ae095f2a 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.oauthprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.oauthprompt.md @@ -32,14 +32,14 @@ When used with your bots `DialogSet` you can simply add a new instance of the pr dialogs.add('taskNeedingLogin', [ async function (dc) { - return dc.begin('loginPrompt'); + await dc.begin('loginPrompt'); }, async function (dc, token) { if (token) { // Continue with task needing access token } else { await dc.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`); - return dc.end(); + await dc.end(); } } ]); @@ -132,7 +132,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Control](botbuilder_dialogs.control.md).[constructor](botbuilder_dialogs.control.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L126)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:126](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L126)* @@ -164,7 +164,7 @@ Creates a new `OAuthPrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -184,7 +184,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -229,7 +229,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -272,7 +272,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:133](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L133)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:133](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L133)* @@ -305,7 +305,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogContinue](../interfaces/botbuilder_dialogs.dialog.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:134](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L134)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:134](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L134)* @@ -335,7 +335,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:149](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L149)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:149](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L149)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.prompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.prompt.md index 3561c16036..3968d1c2ae 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.prompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.prompt.md @@ -96,7 +96,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Control](botbuilder_dialogs.control.md).[constructor](botbuilder_dialogs.control.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L34)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L34)* @@ -124,7 +124,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -144,7 +144,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -189,7 +189,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -232,7 +232,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -265,7 +265,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogContinue](../interfaces/botbuilder_dialogs.dialog.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -295,7 +295,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L36)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:36](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L36)* @@ -327,7 +327,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L37)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:37](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L37)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.textprompt.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.textprompt.md index d4931abc01..e9994d5353 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.textprompt.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.textprompt.md @@ -23,11 +23,11 @@ When used with your bots `DialogSet` you can simply add a new instance of the pr dialogs.add('askName', [ async function (dc) { - return dc.prompt('namePrompt', `What's your name?`); + await dc.prompt('namePrompt', `What's your name?`); }, async function (dc, name) { await dc.context.sendActivity(`Hi ${name}!`); - return dc.end(); + await dc.end(); } ]); @@ -120,7 +120,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor *Overrides [Prompt](botbuilder_dialogs.prompt.md).[constructor](botbuilder_dialogs.prompt.md#constructor)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:89](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L89)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:89](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L89)* @@ -151,7 +151,7 @@ Creates a new `TextPrompt` instance. *Inherited from [Control](botbuilder_dialogs.control.md).[defaultOptions](botbuilder_dialogs.control.md#defaultoptions)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:27](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L27)* @@ -171,7 +171,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[begin](botbuilder_dialogs.control.md#begin)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:51](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L51)* @@ -216,7 +216,7 @@ ___ *Inherited from [Control](botbuilder_dialogs.control.md).[continue](botbuilder_dialogs.control.md#continue)* -*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* +*Defined in [libraries/botbuilder-dialogs/lib/control.d.ts:68](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/control.d.ts#L68)* @@ -261,7 +261,7 @@ ___ *Overrides [Control](botbuilder_dialogs.control.md).[dialogBegin](botbuilder_dialogs.control.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:38](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L38)* @@ -296,7 +296,7 @@ ___ *Inherited from [Prompt](botbuilder_dialogs.prompt.md).[dialogContinue](botbuilder_dialogs.prompt.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:39](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L39)* @@ -328,7 +328,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onPrompt](botbuilder_dialogs.prompt.md#onprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:95](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L95)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:95](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L95)* @@ -362,7 +362,7 @@ ___ *Overrides [Prompt](botbuilder_dialogs.prompt.md).[onRecognize](botbuilder_dialogs.prompt.md#onrecognize)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:96](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L96)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts:96](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts#L96)* diff --git a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.waterfall.md b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.waterfall.md index 8141c7e301..db198bfd36 100644 --- a/doc/botbuilder-dialogs/classes/botbuilder_dialogs.waterfall.md +++ b/doc/botbuilder-dialogs/classes/botbuilder_dialogs.waterfall.md @@ -91,7 +91,7 @@ You should generally call `dc.end()` or `dc.replace()` from your last waterfall ### ⊕ **new Waterfall**(steps: *[WaterfallStep](../#waterfallstep)`C`[]*): [Waterfall](botbuilder_dialogs.waterfall.md) -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:131](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L131)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:131](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L131)* @@ -124,7 +124,7 @@ Creates a new waterfall dialog containing the given array of steps. *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogBegin](../interfaces/botbuilder_dialogs.dialog.md#dialogbegin)* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:137](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L137)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:137](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L137)* @@ -157,7 +157,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogContinue](../interfaces/botbuilder_dialogs.dialog.md#dialogcontinue)* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:138](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L138)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:138](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L138)* @@ -189,7 +189,7 @@ ___ *Implementation of [Dialog](../interfaces/botbuilder_dialogs.dialog.md).[dialogResume](../interfaces/botbuilder_dialogs.dialog.md#dialogresume)* -*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:139](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L139)* +*Defined in [libraries/botbuilder-dialogs/lib/waterfall.d.ts:139](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/waterfall.d.ts#L139)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.choicepromptoptions.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.choicepromptoptions.md index 9f6b7e7c87..be15b08828 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.choicepromptoptions.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.choicepromptoptions.md @@ -30,7 +30,7 @@ Additional options that can be used to configure a `ChoicePrompt`. **● choices**: *`any`[]* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L20)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts:20](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts#L20)* @@ -49,7 +49,7 @@ ___ *Inherited from [PromptOptions](botbuilder_dialogs.promptoptions.md).[prompt](botbuilder_dialogs.promptoptions.md#prompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L19)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L19)* @@ -68,7 +68,7 @@ ___ *Inherited from [PromptOptions](botbuilder_dialogs.promptoptions.md).[retryPrompt](botbuilder_dialogs.promptoptions.md#retryprompt)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L23)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L23)* @@ -87,7 +87,7 @@ ___ *Inherited from [PromptOptions](botbuilder_dialogs.promptoptions.md).[retrySpeak](botbuilder_dialogs.promptoptions.md#retryspeak)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L25)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L25)* @@ -106,7 +106,7 @@ ___ *Inherited from [PromptOptions](botbuilder_dialogs.promptoptions.md).[speak](botbuilder_dialogs.promptoptions.md#speak)* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L21)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialog.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialog.md index 348e53ee5b..3d4b52dcc4 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialog.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialog.md @@ -38,7 +38,7 @@ The type of `TurnContext` being passed around. This simply lets the typing infor -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialog.d.ts#L24)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialog.d.ts#L24)* @@ -72,7 +72,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialog.d.ts#L34)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:34](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialog.d.ts#L34)* @@ -107,7 +107,7 @@ ___ -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:45](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialog.d.ts#L45)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:45](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialog.d.ts#L45)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialoginstance.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialoginstance.md index 405061a317..90ae849700 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialoginstance.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialoginstance.md @@ -20,7 +20,7 @@ Tracking information for a dialog on the stack. **● id**: *`string`* -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:53](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialog.d.ts#L53)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:53](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialog.d.ts#L53)* @@ -37,7 +37,7 @@ ___ **● state**: *`T`* -*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialog.d.ts#L55)* +*Defined in [libraries/botbuilder-dialogs/lib/dialog.d.ts:55](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialog.d.ts#L55)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialogresult.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialogresult.md index a979c3d671..9bede98f53 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialogresult.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.dialogresult.md @@ -19,7 +19,7 @@ Result returned to the caller of one of the various stack manipulation methods a **● active**: *`boolean`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L21)* @@ -36,7 +36,7 @@ ___ **● result**: *`T`⎮`undefined`* -*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:31](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L31)* +*Defined in [libraries/botbuilder-dialogs/lib/dialogContext.d.ts:31](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/dialogContext.d.ts#L31)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md index b52f3ec1b9..61891bc010 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.oauthpromptsettingswithtimeout.md @@ -30,7 +30,7 @@ Settings used to configure an `OAuthPrompt` instance. Includes the ability to ad **● timeout**: *`number`* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L24)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts:24](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts#L24)* diff --git a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.promptoptions.md b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.promptoptions.md index 6d97ca975c..4ab16c6d66 100644 --- a/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.promptoptions.md +++ b/doc/botbuilder-dialogs/interfaces/botbuilder_dialogs.promptoptions.md @@ -30,7 +30,7 @@ Basic configuration options supported by all prompts. **● prompt**: *`string`⎮`Partial`.<`Activity`>* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L19)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:19](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L19)* @@ -47,7 +47,7 @@ ___ **● retryPrompt**: *`string`⎮`Partial`.<`Activity`>* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L23)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:23](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L23)* @@ -64,7 +64,7 @@ ___ **● retrySpeak**: *`string`* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L25)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:25](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L25)* @@ -81,7 +81,7 @@ ___ **● speak**: *`string`* -*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/ce7c4b3/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L21)* +*Defined in [libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts:21](https://github.com/Microsoft/botbuilder-js/blob/ad875d1/libraries/botbuilder-dialogs/lib/prompts/prompt.d.ts#L21)* diff --git a/libraries/botbuilder-dialogs/lib/compositeControl.d.ts b/libraries/botbuilder-dialogs/lib/compositeControl.d.ts index 789f1af02a..dbfdfaf48f 100644 --- a/libraries/botbuilder-dialogs/lib/compositeControl.d.ts +++ b/libraries/botbuilder-dialogs/lib/compositeControl.d.ts @@ -38,29 +38,29 @@ import { DialogSet } from './dialogSet'; * * class ProfileControl extends CompositeControl { * constructor() { - * super(dialogs, 'fillProfile'); + * super('fillProfile'); + * + * this.dialogs.add('fillProfile', [ + * async function (dc, options) { + * dc.instance.state = {}; + * await dc.prompt('textPrompt', `What's your name?`); + * }, + * async function (dc, name) { + * dc.instance.state.name = name; + * await dc.prompt('textPrompt', `What's your phone number?`); + * }, + * async function (dc, phone) { + * dc.instance.state.phone = phone; + * + * // Return completed profile + * await dc.end(dc.instance.state); + * } + * ]); + * + * this.dialogs.add('textPrompt', new TextPrompt()); * } * } * module.exports.ProfileControl = ProfileControl; - * - * dialogs.add('fillProfile', [ - * async function (dc, options) { - * dc.instance.state = {}; - * return dc.prompt('textPrompt', `What's your name?`); - * }, - * async function (dc, name) { - * dc.instance.state.name = name; - * return dc.prompt('textPrompt', `What's your phone number?`); - * }, - * async function (dc, phone) { - * dc.instance.state.phone = phone; - * - * // Return completed profile - * return dc.end(dc.instance.state); - * } - * ]); - * - * dialogs.add('textPrompt', new TextPrompt()); * ``` * * ### Consume as Dialog @@ -81,11 +81,11 @@ import { DialogSet } from './dialogSet'; * dialogs.add('firstrun', [ * async function (dc) { * await dc.context.sendActivity(`Welcome! We need to ask a few questions to get started.`); - * return dc.begin('getProfile'); + * await dc.begin('getProfile'); * }, * async function (dc, profile) { * await dc.context.sendActivity(`Thanks ${profile.name}!`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` @@ -118,19 +118,19 @@ import { DialogSet } from './dialogSet'; * the control is finished and then to access any results it might have returned. To interrupt or * cancel the control simply delete the `state` object the bot has been persisting. * @param R (Optional) type of result that's expected to be returned by the control. - * @param O (Optional) options that can be passed into the [begin()](#begin) method. + * @param O (Optional) options that can be passed into the begin() method. + * @param C (Optional) type of `TurnContext` being passed to dialogs in the set. */ -export declare class CompositeControl implements Dialog { - protected dialogs: DialogSet; +export declare class CompositeControl implements Dialog { protected dialogId: string; - protected defaultOptions: O; + /** The controls dialog set. */ + protected dialogs: DialogSet; /** * Creates a new `CompositeControl` instance. - * @param dialogs Controls dialog set. * @param dialogId ID of the root dialog that should be started anytime the control is started. - * @param defaultOptions (Optional) set of default options that should be passed to controls root dialog. These will be merged with arguments passed in by the caller. + * @param dialogs (Optional) set of existing dialogs the control should use. If omitted an empty set will be created. */ - constructor(dialogs: DialogSet, dialogId: string, defaultOptions?: O); + constructor(dialogId: string, dialogs?: DialogSet); /** * Starts the control. Depending on the control, its possible for the control to finish * immediately so it's advised to check the result object returned by `begin()` and ensure that @@ -149,7 +149,7 @@ export declare class CompositeControl implements Dialog>; + begin(context: C, state: object, options?: O): Promise>; /** * Passes a users reply to the control for further processing. The bot should keep calling * `continue()` for future turns until the control returns a result with `Active == false`. @@ -166,7 +166,7 @@ export declare class CompositeControl implements Dialog>; - dialogBegin(dc: DialogContext, dialogArgs?: any): Promise; - dialogContinue(dc: DialogContext): Promise; + continue(context: C, state: object): Promise>; + dialogBegin(dc: DialogContext, dialogArgs?: any): Promise; + dialogContinue(dc: DialogContext): Promise; } diff --git a/libraries/botbuilder-dialogs/lib/compositeControl.js b/libraries/botbuilder-dialogs/lib/compositeControl.js index d34114e893..e9a69d1aa1 100644 --- a/libraries/botbuilder-dialogs/lib/compositeControl.js +++ b/libraries/botbuilder-dialogs/lib/compositeControl.js @@ -1,5 +1,6 @@ "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); +const dialogSet_1 = require("./dialogSet"); /** * :package: **botbuilder-dialogs** * @@ -29,29 +30,29 @@ Object.defineProperty(exports, "__esModule", { value: true }); * * class ProfileControl extends CompositeControl { * constructor() { - * super(dialogs, 'fillProfile'); + * super('fillProfile'); + * + * this.dialogs.add('fillProfile', [ + * async function (dc, options) { + * dc.instance.state = {}; + * await dc.prompt('textPrompt', `What's your name?`); + * }, + * async function (dc, name) { + * dc.instance.state.name = name; + * await dc.prompt('textPrompt', `What's your phone number?`); + * }, + * async function (dc, phone) { + * dc.instance.state.phone = phone; + * + * // Return completed profile + * await dc.end(dc.instance.state); + * } + * ]); + * + * this.dialogs.add('textPrompt', new TextPrompt()); * } * } * module.exports.ProfileControl = ProfileControl; - * - * dialogs.add('fillProfile', [ - * async function (dc, options) { - * dc.instance.state = {}; - * return dc.prompt('textPrompt', `What's your name?`); - * }, - * async function (dc, name) { - * dc.instance.state.name = name; - * return dc.prompt('textPrompt', `What's your phone number?`); - * }, - * async function (dc, phone) { - * dc.instance.state.phone = phone; - * - * // Return completed profile - * return dc.end(dc.instance.state); - * } - * ]); - * - * dialogs.add('textPrompt', new TextPrompt()); * ``` * * ### Consume as Dialog @@ -72,11 +73,11 @@ Object.defineProperty(exports, "__esModule", { value: true }); * dialogs.add('firstrun', [ * async function (dc) { * await dc.context.sendActivity(`Welcome! We need to ask a few questions to get started.`); - * return dc.begin('getProfile'); + * await dc.begin('getProfile'); * }, * async function (dc, profile) { * await dc.context.sendActivity(`Thanks ${profile.name}!`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` @@ -109,19 +110,18 @@ Object.defineProperty(exports, "__esModule", { value: true }); * the control is finished and then to access any results it might have returned. To interrupt or * cancel the control simply delete the `state` object the bot has been persisting. * @param R (Optional) type of result that's expected to be returned by the control. - * @param O (Optional) options that can be passed into the [begin()](#begin) method. + * @param O (Optional) options that can be passed into the begin() method. + * @param C (Optional) type of `TurnContext` being passed to dialogs in the set. */ class CompositeControl { /** * Creates a new `CompositeControl` instance. - * @param dialogs Controls dialog set. * @param dialogId ID of the root dialog that should be started anytime the control is started. - * @param defaultOptions (Optional) set of default options that should be passed to controls root dialog. These will be merged with arguments passed in by the caller. + * @param dialogs (Optional) set of existing dialogs the control should use. If omitted an empty set will be created. */ - constructor(dialogs, dialogId, defaultOptions) { - this.dialogs = dialogs; + constructor(dialogId, dialogs) { this.dialogId = dialogId; - this.defaultOptions = defaultOptions; + this.dialogs = dialogs || new dialogSet_1.DialogSet(); } /** * Starts the control. Depending on the control, its possible for the control to finish @@ -143,7 +143,7 @@ class CompositeControl { */ begin(context, state, options) { const cdc = this.dialogs.createContext(context, state); - return cdc.begin(this.dialogId, Object.assign({}, this.defaultOptions, options)) + return cdc.begin(this.dialogId, options) .then(() => cdc.dialogResult); } /** @@ -170,7 +170,7 @@ class CompositeControl { dialogBegin(dc, dialogArgs) { // Start the controls entry point dialog. const cdc = this.dialogs.createContext(dc.context, dc.instance.state); - return cdc.begin(this.dialogId, Object.assign({}, this.defaultOptions, dialogArgs)).then(() => { + return cdc.begin(this.dialogId, Object.assign({}, dialogArgs)).then(() => { // End if the controls dialog ends. if (!cdc.dialogResult.active) { return dc.end(cdc.dialogResult.result); diff --git a/libraries/botbuilder-dialogs/lib/compositeControl.js.map b/libraries/botbuilder-dialogs/lib/compositeControl.js.map index a02ab1dc95..df94337aee 100644 --- a/libraries/botbuilder-dialogs/lib/compositeControl.js.map +++ b/libraries/botbuilder-dialogs/lib/compositeControl.js.map @@ -1 +1 @@ -{"version":3,"file":"compositeControl.js","sourceRoot":"","sources":["../src/compositeControl.ts"],"names":[],"mappings":";;AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8GG;AACH;IAEI;;;;;OAKG;IACH,YAAsB,OAA+B,EAAY,QAAgB,EAAY,cAAkB;QAAzF,YAAO,GAAP,OAAO,CAAwB;QAAY,aAAQ,GAAR,QAAQ,CAAQ;QAAY,mBAAc,GAAd,cAAc,CAAI;IAAI,CAAC;IAEpH;;;;;;;;;;;;;;;;;OAiBG;IACI,KAAK,CAAC,OAAoB,EAAE,KAAa,EAAE,OAAW;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACvD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;aACrE,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACI,QAAQ,CAAC,OAAoB,EAAE,KAAa;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACvD,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE;aACV,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;IAEM,WAAW,CAAC,EAA8B,EAAE,UAAgB;QAC/D,0CAA0C;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;YAC1F,mCAAmC;YACnC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3B,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;IAEM,cAAc,CAAC,EAA8B;QAChD,kCAAkC;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;YAC5B,mCAAmC;YACnC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3B,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;CACJ;AA7ED,4CA6EC"} \ No newline at end of file +{"version":3,"file":"compositeControl.js","sourceRoot":"","sources":["../src/compositeControl.ts"],"names":[],"mappings":";;AAUA,2CAAwC;AAGxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+GG;AACH;IAII;;;;OAIG;IACH,YAAsB,QAAgB,EAAE,OAAsB;QAAxC,aAAQ,GAAR,QAAQ,CAAQ;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,IAAI,qBAAS,EAAK,CAAC;IACjD,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACI,KAAK,CAAC,OAAU,EAAE,KAAa,EAAE,OAAW;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACvD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC;aAC7B,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACI,QAAQ,CAAC,OAAU,EAAE,KAAa;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACvD,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE;aACV,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;IAEM,WAAW,CAAC,EAAoB,EAAE,UAAgB;QACrD,0CAA0C;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;YACrE,mCAAmC;YACnC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3B,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;IAEM,cAAc,CAAC,EAAoB;QACtC,kCAAkC;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;YAC5B,mCAAmC;YACnC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3B,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;CACJ;AAhFD,4CAgFC"} \ No newline at end of file diff --git a/libraries/botbuilder-dialogs/lib/dialogContext.d.ts b/libraries/botbuilder-dialogs/lib/dialogContext.d.ts index e4868b00b9..88986eea2f 100644 --- a/libraries/botbuilder-dialogs/lib/dialogContext.d.ts +++ b/libraries/botbuilder-dialogs/lib/dialogContext.d.ts @@ -62,7 +62,7 @@ export declare class DialogContext { * * ```JavaScript * const dc = dialogs.createContext(context, stack); - * return dc.begin('greeting', user); + * await dc.begin('greeting', user); * ``` * @param dialogId ID of the dialog to start. * @param dialogArgs (Optional) additional argument(s) to pass to the dialog being started. @@ -75,7 +75,7 @@ export declare class DialogContext { * **Example usage:** * * ```JavaScript - * return dc.prompt('confirmPrompt', `Are you sure you'd like to quit?`); + * await dc.prompt('confirmPrompt', `Are you sure you'd like to quit?`); * ``` * @param O (Optional) type of options expected by the prompt. * @param dialogId ID of the prompt to start. @@ -95,7 +95,7 @@ export declare class DialogContext { * const dc = dialogs.createContext(context, dialogStack); * return dc.continue().then(() => { * if (!context.responded) { - * return dc.begin('fallback'); + * await dc.begin('fallback'); * } * }); * ``` @@ -118,7 +118,7 @@ export declare class DialogContext { * function (dc) { * const elapsed = new Date().getTime() - started; * dc.batch.reply(`I've been running for ${elapsed / 1000} seconds.`); - * return dc.end(elapsed); + * await dc.end(elapsed); * } * ]); * const started = new Date().getTime(); @@ -146,7 +146,7 @@ export declare class DialogContext { * dialogs.add('loop', [ * function (dc, args) { * dc.instance.state = args; - * return dc.begin(args.dialogId); + * await dc.begin(args.dialogId); * }, * function (dc) { * const args = dc.instance.state; diff --git a/libraries/botbuilder-dialogs/lib/dialogContext.js b/libraries/botbuilder-dialogs/lib/dialogContext.js index 40db5456e7..9ec64096f4 100644 --- a/libraries/botbuilder-dialogs/lib/dialogContext.js +++ b/libraries/botbuilder-dialogs/lib/dialogContext.js @@ -40,7 +40,7 @@ class DialogContext { * * ```JavaScript * const dc = dialogs.createContext(context, stack); - * return dc.begin('greeting', user); + * await dc.begin('greeting', user); * ``` * @param dialogId ID of the dialog to start. * @param dialogArgs (Optional) additional argument(s) to pass to the dialog being started. @@ -72,7 +72,7 @@ class DialogContext { * **Example usage:** * * ```JavaScript - * return dc.prompt('confirmPrompt', `Are you sure you'd like to quit?`); + * await dc.prompt('confirmPrompt', `Are you sure you'd like to quit?`); * ``` * @param O (Optional) type of options expected by the prompt. * @param dialogId ID of the prompt to start. @@ -98,7 +98,7 @@ class DialogContext { * const dc = dialogs.createContext(context, dialogStack); * return dc.continue().then(() => { * if (!context.responded) { - * return dc.begin('fallback'); + * await dc.begin('fallback'); * } * }); * ``` @@ -148,7 +148,7 @@ class DialogContext { * function (dc) { * const elapsed = new Date().getTime() - started; * dc.batch.reply(`I've been running for ${elapsed / 1000} seconds.`); - * return dc.end(elapsed); + * await dc.end(elapsed); * } * ]); * const started = new Date().getTime(); @@ -215,7 +215,7 @@ class DialogContext { * dialogs.add('loop', [ * function (dc, args) { * dc.instance.state = args; - * return dc.begin(args.dialogId); + * await dc.begin(args.dialogId); * }, * function (dc) { * const args = dc.instance.state; diff --git a/libraries/botbuilder-dialogs/lib/dialogSet.d.ts b/libraries/botbuilder-dialogs/lib/dialogSet.d.ts index 0d28504e79..9dbf39aebc 100644 --- a/libraries/botbuilder-dialogs/lib/dialogSet.d.ts +++ b/libraries/botbuilder-dialogs/lib/dialogSet.d.ts @@ -33,17 +33,17 @@ import { DialogContext } from './dialogContext'; * dialogs.add('fillProfile', [ * async function (dc, options) { * dc.instance.state = {}; - * return dc.prompt('textPrompt', `What's your name?`); + * await dc.prompt('textPrompt', `What's your name?`); * }, * async function (dc, name) { * dc.instance.state.name = name; - * return dc.prompt('textPrompt', `What's your phone number?`); + * await dc.prompt('textPrompt', `What's your phone number?`); * }, * async function (dc, phone) { * dc.instance.state.phone = phone; * * // Return completed profile - * return dc.end(dc.instance.state); + * await dc.end(dc.instance.state); * } * ]); * @@ -111,7 +111,7 @@ export declare class DialogSet { * dialogs.add('greeting', [ * async function (dc) { * await dc.context.sendActivity(`Hello world!`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` diff --git a/libraries/botbuilder-dialogs/lib/dialogSet.js b/libraries/botbuilder-dialogs/lib/dialogSet.js index 5f1729f1a8..051ce65e38 100644 --- a/libraries/botbuilder-dialogs/lib/dialogSet.js +++ b/libraries/botbuilder-dialogs/lib/dialogSet.js @@ -26,17 +26,17 @@ const dialogContext_1 = require("./dialogContext"); * dialogs.add('fillProfile', [ * async function (dc, options) { * dc.instance.state = {}; - * return dc.prompt('textPrompt', `What's your name?`); + * await dc.prompt('textPrompt', `What's your name?`); * }, * async function (dc, name) { * dc.instance.state.name = name; - * return dc.prompt('textPrompt', `What's your phone number?`); + * await dc.prompt('textPrompt', `What's your phone number?`); * }, * async function (dc, phone) { * dc.instance.state.phone = phone; * * // Return completed profile - * return dc.end(dc.instance.state); + * await dc.end(dc.instance.state); * } * ]); * diff --git a/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts index e17407499e..f9fa6ef81e 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.d.ts @@ -34,11 +34,11 @@ import { Prompt, PromptOptions } from './prompt'; * * dialogs.add('uploadImage', [ * async function (dc) { - * return dc.prompt('attachmentPrompt', `Send me image(s)`); + * await dc.prompt('attachmentPrompt', `Send me image(s)`); * }, * async function (dc, attachments) { * await dc.context.sendActivity(`Processing ${attachments.length} images.`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` @@ -48,7 +48,7 @@ import { Prompt, PromptOptions } from './prompt'; * alternate prompt to send by passing in additional options: * * ```JavaScript - * return dc.prompt('attachmentPrompt', `Send me image(s)`, { retryPrompt: `I didn't get anything. Send me an image.` }); + * await dc.prompt('attachmentPrompt', `Send me image(s)`, { retryPrompt: `I didn't get anything. Send me an image.` }); * ``` * * The prompts retry logic can also be completely customized by passing the prompts constructor a diff --git a/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.js b/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.js index 41e23d02b0..2347557ba6 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/attachmentPrompt.js @@ -27,11 +27,11 @@ const prompts = require("botbuilder-prompts"); * * dialogs.add('uploadImage', [ * async function (dc) { - * return dc.prompt('attachmentPrompt', `Send me image(s)`); + * await dc.prompt('attachmentPrompt', `Send me image(s)`); * }, * async function (dc, attachments) { * await dc.context.sendActivity(`Processing ${attachments.length} images.`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` @@ -41,7 +41,7 @@ const prompts = require("botbuilder-prompts"); * alternate prompt to send by passing in additional options: * * ```JavaScript - * return dc.prompt('attachmentPrompt', `Send me image(s)`, { retryPrompt: `I didn't get anything. Send me an image.` }); + * await dc.prompt('attachmentPrompt', `Send me image(s)`, { retryPrompt: `I didn't get anything. Send me an image.` }); * ``` * * The prompts retry logic can also be completely customized by passing the prompts constructor a diff --git a/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts index a2d24b697c..aa34b49ff5 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.d.ts @@ -44,12 +44,12 @@ export interface ChoicePromptOptions extends PromptOptions { * * dialogs.add('colorPrompt', [ * async function (dc) { - * return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue']); + * await dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue']); * }, * async function (dc, choice) { * const color = choice.value; * await dc.context.sendActivity(`I like ${color} too!`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` @@ -59,7 +59,7 @@ export interface ChoicePromptOptions extends PromptOptions { * alternate prompt to send by passing in additional options: * * ```JavaScript - * return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue'], { retryPrompt: `I didn't catch that. Select a color from the list.` }); + * await dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue'], { retryPrompt: `I didn't catch that. Select a color from the list.` }); * ``` * * ### Control Usage diff --git a/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.js b/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.js index dd60380a6e..73aa3a498c 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/choicePrompt.js @@ -27,12 +27,12 @@ const prompts = require("botbuilder-prompts"); * * dialogs.add('colorPrompt', [ * async function (dc) { - * return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue']); + * await dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue']); * }, * async function (dc, choice) { * const color = choice.value; * await dc.context.sendActivity(`I like ${color} too!`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` @@ -42,7 +42,7 @@ const prompts = require("botbuilder-prompts"); * alternate prompt to send by passing in additional options: * * ```JavaScript - * return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue'], { retryPrompt: `I didn't catch that. Select a color from the list.` }); + * await dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue'], { retryPrompt: `I didn't catch that. Select a color from the list.` }); * ``` * * ### Control Usage diff --git a/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts index 7408b3eea5..4ee3f511eb 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.d.ts @@ -36,13 +36,13 @@ import * as prompts from 'botbuilder-prompts'; * * dialogs.add('confirmCancel', [ * async function (dc) { - * return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`); + * await dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`); * }, * async function (dc, cancel) { * if (cancel) { * await dc.context.sendActivity(`Order cancelled.`); * } - * return dc.end(); + * await dc.end(); * } * ]); * ``` @@ -52,7 +52,7 @@ import * as prompts from 'botbuilder-prompts'; * alternate prompt to send by passing in additional options: * * ```JavaScript - * return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`, { retryPrompt: `Please answer "yes" or "no".` }); + * await dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`, { retryPrompt: `Please answer "yes" or "no".` }); * ``` * * The prompts retry logic can also be completely customized by passing the prompts constructor a diff --git a/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.js b/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.js index bdb1cf7667..7457af4d26 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/confirmPrompt.js @@ -28,13 +28,13 @@ const prompts = require("botbuilder-prompts"); * * dialogs.add('confirmCancel', [ * async function (dc) { - * return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`); + * await dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`); * }, * async function (dc, cancel) { * if (cancel) { * await dc.context.sendActivity(`Order cancelled.`); * } - * return dc.end(); + * await dc.end(); * } * ]); * ``` @@ -44,7 +44,7 @@ const prompts = require("botbuilder-prompts"); * alternate prompt to send by passing in additional options: * * ```JavaScript - * return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`, { retryPrompt: `Please answer "yes" or "no".` }); + * await dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`, { retryPrompt: `Please answer "yes" or "no".` }); * ``` * * The prompts retry logic can also be completely customized by passing the prompts constructor a diff --git a/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts index 2898e588a1..9a5da6a133 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.d.ts @@ -36,11 +36,11 @@ import * as prompts from 'botbuilder-prompts'; * * dialogs.add('setAlarmTime', [ * async function (dc) { - * return dc.prompt('datetimePrompt', `What time should I set your alarm for?`); + * await dc.prompt('datetimePrompt', `What time should I set your alarm for?`); * }, * async function (dc, time) { * await dc.context.sendActivity(`Alarm time set`); - * return dc.end(); + * await dc.end(); * } * ]); * diff --git a/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.js b/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.js index df78a7b488..852892fb01 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/datetimePrompt.js @@ -28,11 +28,11 @@ const prompts = require("botbuilder-prompts"); * * dialogs.add('setAlarmTime', [ * async function (dc) { - * return dc.prompt('datetimePrompt', `What time should I set your alarm for?`); + * await dc.prompt('datetimePrompt', `What time should I set your alarm for?`); * }, * async function (dc, time) { * await dc.context.sendActivity(`Alarm time set`); - * return dc.end(); + * await dc.end(); * } * ]); * diff --git a/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts index f8f828298e..86a392fd4e 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.d.ts @@ -34,7 +34,7 @@ import { Prompt, PromptOptions } from './prompt'; * * dialogs.add('askAge', [ * async function (dc) { - * return dc.prompt('agePrompt', `How old are you?`); + * await dc.prompt('agePrompt', `How old are you?`); * }, * async function (dc, age) { * if (age < 40) { @@ -42,7 +42,7 @@ import { Prompt, PromptOptions } from './prompt'; * } else { * await dc.context.sendActivity(`I hear ${age} is the new ${age - 10} :)`); * } - * return dc.end(); + * await dc.end(); * } * ]); * ``` diff --git a/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.js b/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.js index c744b8c928..0d1ffa6d5e 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/numberPrompt.js @@ -27,7 +27,7 @@ const prompts = require("botbuilder-prompts"); * * dialogs.add('askAge', [ * async function (dc) { - * return dc.prompt('agePrompt', `How old are you?`); + * await dc.prompt('agePrompt', `How old are you?`); * }, * async function (dc, age) { * if (age < 40) { @@ -35,7 +35,7 @@ const prompts = require("botbuilder-prompts"); * } else { * await dc.context.sendActivity(`I hear ${age} is the new ${age - 10} :)`); * } - * return dc.end(); + * await dc.end(); * } * ]); * ``` diff --git a/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts index 509d4a78ef..1eb4b2829b 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.d.ts @@ -65,14 +65,14 @@ export interface OAuthPromptSettingsWithTimeout extends prompts.OAuthPromptSetti * * dialogs.add('taskNeedingLogin', [ * async function (dc) { - * return dc.begin('loginPrompt'); + * await dc.begin('loginPrompt'); * }, * async function (dc, token) { * if (token) { * // Continue with task needing access token * } else { * await dc.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`); - * return dc.end(); + * await dc.end(); * } * } * ]); diff --git a/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.js b/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.js index 096e49071a..4b796bbfb3 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/oauthPrompt.js @@ -52,14 +52,14 @@ const control_1 = require("../control"); * * dialogs.add('taskNeedingLogin', [ * async function (dc) { - * return dc.begin('loginPrompt'); + * await dc.begin('loginPrompt'); * }, * async function (dc, token) { * if (token) { * // Continue with task needing access token * } else { * await dc.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`); - * return dc.end(); + * await dc.end(); * } * } * ]); diff --git a/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts b/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts index 4e002edd3b..bbde7e5be5 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts +++ b/libraries/botbuilder-dialogs/lib/prompts/textPrompt.d.ts @@ -34,11 +34,11 @@ import { Prompt, PromptOptions } from './prompt'; * * dialogs.add('askName', [ * async function (dc) { - * return dc.prompt('namePrompt', `What's your name?`); + * await dc.prompt('namePrompt', `What's your name?`); * }, * async function (dc, name) { * await dc.context.sendActivity(`Hi ${name}!`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` diff --git a/libraries/botbuilder-dialogs/lib/prompts/textPrompt.js b/libraries/botbuilder-dialogs/lib/prompts/textPrompt.js index f96a09f3c2..1e002201a7 100644 --- a/libraries/botbuilder-dialogs/lib/prompts/textPrompt.js +++ b/libraries/botbuilder-dialogs/lib/prompts/textPrompt.js @@ -27,11 +27,11 @@ const prompts = require("botbuilder-prompts"); * * dialogs.add('askName', [ * async function (dc) { - * return dc.prompt('namePrompt', `What's your name?`); + * await dc.prompt('namePrompt', `What's your name?`); * }, * async function (dc, name) { * await dc.context.sendActivity(`Hi ${name}!`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` diff --git a/libraries/botbuilder-dialogs/src/compositeControl.ts b/libraries/botbuilder-dialogs/src/compositeControl.ts index 8b12d26f7a..968071b600 100644 --- a/libraries/botbuilder-dialogs/src/compositeControl.ts +++ b/libraries/botbuilder-dialogs/src/compositeControl.ts @@ -40,29 +40,29 @@ import { DialogSet } from './dialogSet'; * * class ProfileControl extends CompositeControl { * constructor() { - * super(dialogs, 'fillProfile'); + * super('fillProfile'); + * + * this.dialogs.add('fillProfile', [ + * async function (dc, options) { + * dc.instance.state = {}; + * await dc.prompt('textPrompt', `What's your name?`); + * }, + * async function (dc, name) { + * dc.instance.state.name = name; + * await dc.prompt('textPrompt', `What's your phone number?`); + * }, + * async function (dc, phone) { + * dc.instance.state.phone = phone; + * + * // Return completed profile + * await dc.end(dc.instance.state); + * } + * ]); + * + * this.dialogs.add('textPrompt', new TextPrompt()); * } * } * module.exports.ProfileControl = ProfileControl; - * - * dialogs.add('fillProfile', [ - * async function (dc, options) { - * dc.instance.state = {}; - * return dc.prompt('textPrompt', `What's your name?`); - * }, - * async function (dc, name) { - * dc.instance.state.name = name; - * return dc.prompt('textPrompt', `What's your phone number?`); - * }, - * async function (dc, phone) { - * dc.instance.state.phone = phone; - * - * // Return completed profile - * return dc.end(dc.instance.state); - * } - * ]); - * - * dialogs.add('textPrompt', new TextPrompt()); * ``` * * ### Consume as Dialog @@ -83,11 +83,11 @@ import { DialogSet } from './dialogSet'; * dialogs.add('firstrun', [ * async function (dc) { * await dc.context.sendActivity(`Welcome! We need to ask a few questions to get started.`); - * return dc.begin('getProfile'); + * await dc.begin('getProfile'); * }, * async function (dc, profile) { * await dc.context.sendActivity(`Thanks ${profile.name}!`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` @@ -120,17 +120,21 @@ import { DialogSet } from './dialogSet'; * the control is finished and then to access any results it might have returned. To interrupt or * cancel the control simply delete the `state` object the bot has been persisting. * @param R (Optional) type of result that's expected to be returned by the control. - * @param O (Optional) options that can be passed into the [begin()](#begin) method. + * @param O (Optional) options that can be passed into the begin() method. + * @param C (Optional) type of `TurnContext` being passed to dialogs in the set. */ -export class CompositeControl implements Dialog { +export class CompositeControl implements Dialog { + /** The controls dialog set. */ + protected dialogs: DialogSet; /** * Creates a new `CompositeControl` instance. - * @param dialogs Controls dialog set. * @param dialogId ID of the root dialog that should be started anytime the control is started. - * @param defaultOptions (Optional) set of default options that should be passed to controls root dialog. These will be merged with arguments passed in by the caller. + * @param dialogs (Optional) set of existing dialogs the control should use. If omitted an empty set will be created. */ - constructor(protected dialogs: DialogSet, protected dialogId: string, protected defaultOptions?: O) { } + constructor(protected dialogId: string, dialogs?: DialogSet) { + this.dialogs = dialogs || new DialogSet(); + } /** * Starts the control. Depending on the control, its possible for the control to finish @@ -150,9 +154,9 @@ export class CompositeControl implements Dialog { * @param state A state object that the control will use to persist its current state. This should be an empty object which the control will populate. The bot should persist this with its other conversation state for as long as the control is still active. * @param options (Optional) additional options supported by the control. */ - public begin(context: TurnContext, state: object, options?: O): Promise> { + public begin(context: C, state: object, options?: O): Promise> { const cdc = this.dialogs.createContext(context, state); - return cdc.begin(this.dialogId, Object.assign({}, this.defaultOptions, options)) + return cdc.begin(this.dialogId, options) .then(() => cdc.dialogResult); } @@ -172,16 +176,16 @@ export class CompositeControl implements Dialog { * @param context Context for the current turn of the conversation with the user. * @param state A state object that was previously initialized by a call to [begin()](#begin). */ - public continue(context: TurnContext, state: object): Promise> { + public continue(context: C, state: object): Promise> { const cdc = this.dialogs.createContext(context, state); return cdc.continue() .then(() => cdc.dialogResult); } - public dialogBegin(dc: DialogContext, dialogArgs?: any): Promise { + public dialogBegin(dc: DialogContext, dialogArgs?: any): Promise { // Start the controls entry point dialog. const cdc = this.dialogs.createContext(dc.context, dc.instance.state); - return cdc.begin(this.dialogId, Object.assign({}, this.defaultOptions, dialogArgs)).then(() => { + return cdc.begin(this.dialogId, Object.assign({}, dialogArgs)).then(() => { // End if the controls dialog ends. if (!cdc.dialogResult.active) { return dc.end(cdc.dialogResult.result); @@ -189,7 +193,7 @@ export class CompositeControl implements Dialog { }); } - public dialogContinue(dc: DialogContext): Promise { + public dialogContinue(dc: DialogContext): Promise { // Continue controls dialog stack. const cdc = this.dialogs.createContext(dc.context, dc.instance.state); return cdc.continue().then(() => { diff --git a/libraries/botbuilder-dialogs/src/dialogContext.ts b/libraries/botbuilder-dialogs/src/dialogContext.ts index f27159586f..7d4954838c 100644 --- a/libraries/botbuilder-dialogs/src/dialogContext.ts +++ b/libraries/botbuilder-dialogs/src/dialogContext.ts @@ -73,7 +73,7 @@ export class DialogContext { * * ```JavaScript * const dc = dialogs.createContext(context, stack); - * return dc.begin('greeting', user); + * await dc.begin('greeting', user); * ``` * @param dialogId ID of the dialog to start. * @param dialogArgs (Optional) additional argument(s) to pass to the dialog being started. @@ -105,7 +105,7 @@ export class DialogContext { * **Example usage:** * * ```JavaScript - * return dc.prompt('confirmPrompt', `Are you sure you'd like to quit?`); + * await dc.prompt('confirmPrompt', `Are you sure you'd like to quit?`); * ``` * @param O (Optional) type of options expected by the prompt. * @param dialogId ID of the prompt to start. @@ -130,7 +130,7 @@ export class DialogContext { * const dc = dialogs.createContext(context, dialogStack); * return dc.continue().then(() => { * if (!context.responded) { - * return dc.begin('fallback'); + * await dc.begin('fallback'); * } * }); * ``` @@ -178,7 +178,7 @@ export class DialogContext { * function (dc) { * const elapsed = new Date().getTime() - started; * dc.batch.reply(`I've been running for ${elapsed / 1000} seconds.`); - * return dc.end(elapsed); + * await dc.end(elapsed); * } * ]); * const started = new Date().getTime(); @@ -243,7 +243,7 @@ export class DialogContext { * dialogs.add('loop', [ * function (dc, args) { * dc.instance.state = args; - * return dc.begin(args.dialogId); + * await dc.begin(args.dialogId); * }, * function (dc) { * const args = dc.instance.state; diff --git a/libraries/botbuilder-dialogs/src/dialogSet.ts b/libraries/botbuilder-dialogs/src/dialogSet.ts index bf36986c8e..66c71067bc 100644 --- a/libraries/botbuilder-dialogs/src/dialogSet.ts +++ b/libraries/botbuilder-dialogs/src/dialogSet.ts @@ -34,17 +34,17 @@ import { DialogContext } from './dialogContext'; * dialogs.add('fillProfile', [ * async function (dc, options) { * dc.instance.state = {}; - * return dc.prompt('textPrompt', `What's your name?`); + * await dc.prompt('textPrompt', `What's your name?`); * }, * async function (dc, name) { * dc.instance.state.name = name; - * return dc.prompt('textPrompt', `What's your phone number?`); + * await dc.prompt('textPrompt', `What's your phone number?`); * }, * async function (dc, phone) { * dc.instance.state.phone = phone; * * // Return completed profile - * return dc.end(dc.instance.state); + * await dc.end(dc.instance.state); * } * ]); * @@ -113,7 +113,7 @@ export class DialogSet { * dialogs.add('greeting', [ * async function (dc) { * await dc.context.sendActivity(`Hello world!`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` diff --git a/libraries/botbuilder-dialogs/src/prompts/attachmentPrompt.ts b/libraries/botbuilder-dialogs/src/prompts/attachmentPrompt.ts index df66dc3258..8b16047fce 100644 --- a/libraries/botbuilder-dialogs/src/prompts/attachmentPrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/attachmentPrompt.ts @@ -36,11 +36,11 @@ import * as prompts from 'botbuilder-prompts'; * * dialogs.add('uploadImage', [ * async function (dc) { - * return dc.prompt('attachmentPrompt', `Send me image(s)`); + * await dc.prompt('attachmentPrompt', `Send me image(s)`); * }, * async function (dc, attachments) { * await dc.context.sendActivity(`Processing ${attachments.length} images.`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` @@ -50,7 +50,7 @@ import * as prompts from 'botbuilder-prompts'; * alternate prompt to send by passing in additional options: * * ```JavaScript - * return dc.prompt('attachmentPrompt', `Send me image(s)`, { retryPrompt: `I didn't get anything. Send me an image.` }); + * await dc.prompt('attachmentPrompt', `Send me image(s)`, { retryPrompt: `I didn't get anything. Send me an image.` }); * ``` * * The prompts retry logic can also be completely customized by passing the prompts constructor a diff --git a/libraries/botbuilder-dialogs/src/prompts/choicePrompt.ts b/libraries/botbuilder-dialogs/src/prompts/choicePrompt.ts index 8b2375e6e6..6ce8f91c8f 100644 --- a/libraries/botbuilder-dialogs/src/prompts/choicePrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/choicePrompt.ts @@ -46,12 +46,12 @@ export interface ChoicePromptOptions extends PromptOptions { * * dialogs.add('colorPrompt', [ * async function (dc) { - * return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue']); + * await dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue']); * }, * async function (dc, choice) { * const color = choice.value; * await dc.context.sendActivity(`I like ${color} too!`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` @@ -61,7 +61,7 @@ export interface ChoicePromptOptions extends PromptOptions { * alternate prompt to send by passing in additional options: * * ```JavaScript - * return dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue'], { retryPrompt: `I didn't catch that. Select a color from the list.` }); + * await dc.prompt('choicePrompt', `Select a color`, ['red', 'green', 'blue'], { retryPrompt: `I didn't catch that. Select a color from the list.` }); * ``` * * ### Control Usage diff --git a/libraries/botbuilder-dialogs/src/prompts/confirmPrompt.ts b/libraries/botbuilder-dialogs/src/prompts/confirmPrompt.ts index a5aae03097..172ede6b41 100644 --- a/libraries/botbuilder-dialogs/src/prompts/confirmPrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/confirmPrompt.ts @@ -37,13 +37,13 @@ import * as prompts from 'botbuilder-prompts'; * * dialogs.add('confirmCancel', [ * async function (dc) { - * return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`); + * await dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`); * }, * async function (dc, cancel) { * if (cancel) { * await dc.context.sendActivity(`Order cancelled.`); * } - * return dc.end(); + * await dc.end(); * } * ]); * ``` @@ -53,7 +53,7 @@ import * as prompts from 'botbuilder-prompts'; * alternate prompt to send by passing in additional options: * * ```JavaScript - * return dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`, { retryPrompt: `Please answer "yes" or "no".` }); + * await dc.prompt('confirmPrompt', `This will cancel your order. Are you sure?`, { retryPrompt: `Please answer "yes" or "no".` }); * ``` * * The prompts retry logic can also be completely customized by passing the prompts constructor a diff --git a/libraries/botbuilder-dialogs/src/prompts/datetimePrompt.ts b/libraries/botbuilder-dialogs/src/prompts/datetimePrompt.ts index 63a9f66163..0d85694b18 100644 --- a/libraries/botbuilder-dialogs/src/prompts/datetimePrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/datetimePrompt.ts @@ -37,11 +37,11 @@ import * as prompts from 'botbuilder-prompts'; * * dialogs.add('setAlarmTime', [ * async function (dc) { - * return dc.prompt('datetimePrompt', `What time should I set your alarm for?`); + * await dc.prompt('datetimePrompt', `What time should I set your alarm for?`); * }, * async function (dc, time) { * await dc.context.sendActivity(`Alarm time set`); - * return dc.end(); + * await dc.end(); * } * ]); * diff --git a/libraries/botbuilder-dialogs/src/prompts/numberPrompt.ts b/libraries/botbuilder-dialogs/src/prompts/numberPrompt.ts index 99f12ea065..a9ee08dfda 100644 --- a/libraries/botbuilder-dialogs/src/prompts/numberPrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/numberPrompt.ts @@ -36,7 +36,7 @@ import * as prompts from 'botbuilder-prompts'; * * dialogs.add('askAge', [ * async function (dc) { - * return dc.prompt('agePrompt', `How old are you?`); + * await dc.prompt('agePrompt', `How old are you?`); * }, * async function (dc, age) { * if (age < 40) { @@ -44,7 +44,7 @@ import * as prompts from 'botbuilder-prompts'; * } else { * await dc.context.sendActivity(`I hear ${age} is the new ${age - 10} :)`); * } - * return dc.end(); + * await dc.end(); * } * ]); * ``` diff --git a/libraries/botbuilder-dialogs/src/prompts/oauthPrompt.ts b/libraries/botbuilder-dialogs/src/prompts/oauthPrompt.ts index 26f6b00b99..b1b76dff7c 100644 --- a/libraries/botbuilder-dialogs/src/prompts/oauthPrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/oauthPrompt.ts @@ -67,14 +67,14 @@ export interface OAuthPromptSettingsWithTimeout extends prompts.OAuthPromptSetti * * dialogs.add('taskNeedingLogin', [ * async function (dc) { - * return dc.begin('loginPrompt'); + * await dc.begin('loginPrompt'); * }, * async function (dc, token) { * if (token) { * // Continue with task needing access token * } else { * await dc.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`); - * return dc.end(); + * await dc.end(); * } * } * ]); diff --git a/libraries/botbuilder-dialogs/src/prompts/textPrompt.ts b/libraries/botbuilder-dialogs/src/prompts/textPrompt.ts index 0096b2d582..496b64c788 100644 --- a/libraries/botbuilder-dialogs/src/prompts/textPrompt.ts +++ b/libraries/botbuilder-dialogs/src/prompts/textPrompt.ts @@ -36,11 +36,11 @@ import * as prompts from 'botbuilder-prompts'; * * dialogs.add('askName', [ * async function (dc) { - * return dc.prompt('namePrompt', `What's your name?`); + * await dc.prompt('namePrompt', `What's your name?`); * }, * async function (dc, name) { * await dc.context.sendActivity(`Hi ${name}!`); - * return dc.end(); + * await dc.end(); * } * ]); * ``` diff --git a/libraries/botbuilder-dialogs/tests/compositeControl.test.js b/libraries/botbuilder-dialogs/tests/compositeControl.test.js index e659acea67..dea156d405 100644 --- a/libraries/botbuilder-dialogs/tests/compositeControl.test.js +++ b/libraries/botbuilder-dialogs/tests/compositeControl.test.js @@ -29,7 +29,7 @@ describe('CompositeControl', function() { done(); } ]); - const control = new CompositeControl(cDialogs, 'start'); + const control = new CompositeControl('start', cDialogs); const dialogs = new DialogSet(); dialogs.add('control', control); @@ -47,7 +47,7 @@ describe('CompositeControl', function() { return dc.end(120); } ]); - const control = new CompositeControl(cDialogs, 'start'); + const control = new CompositeControl('start', cDialogs); const dialogs = new DialogSet(); dialogs.add('control', control); @@ -76,7 +76,7 @@ describe('CompositeControl', function() { return dc.end(120); } ]); - const control = new CompositeControl(cDialogs, 'start'); + const control = new CompositeControl('start', cDialogs); const dialogs = new DialogSet(); dialogs.add('control', control); @@ -110,25 +110,7 @@ describe('CompositeControl', function() { done(); } ]); - const control = new CompositeControl(cDialogs, 'start'); - - const state = {}; - const context = new TestContext(beginMessage); - control.begin(context, state, { foo: 'bar' }); - }); - - it('should merge options passed to begin() with default options.', function (done) { - const cDialogs = new DialogSet(); - cDialogs.add('start', [ - function (dc, args) { - assert(dc); - assert(typeof args === 'object'); - assert(args.foo === 'bar'); - assert(args.bar === 'foo'); - done(); - } - ]); - const control = new CompositeControl(cDialogs, 'start', { bar: 'foo' }); + const control = new CompositeControl('start', cDialogs); const state = {}; const context = new TestContext(beginMessage); @@ -148,7 +130,7 @@ describe('CompositeControl', function() { return dc.end(120); } ]); - const control = new CompositeControl(cDialogs, 'start'); + const control = new CompositeControl('start', cDialogs); const state = {}; const context = new TestContext(beginMessage);