Skip to content

Stevenic/docs #211

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Apr 26, 2018
Merged

Stevenic/docs #211

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e54b802
Reference docs for botbuilder-choices
Stevenic Apr 21, 2018
b50d910
Updated botbuilder-prompts docs
Stevenic Apr 22, 2018
ce7c4b3
updated docs for dialogs and prompts
Stevenic Apr 25, 2018
ad875d1
updated dialog docs
Stevenic Apr 25, 2018
01440f1
Updated composite control
Stevenic Apr 25, 2018
1fdd22e
Merge branch 'master' into stevenic/docs
Stevenic Apr 26, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 90 additions & 18 deletions doc/botbuilder-choices/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)[]

Expand All @@ -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. |



Expand All @@ -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:**
Expand Down Expand Up @@ -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. |



Expand All @@ -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. |



Expand All @@ -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. |



Expand Down
106 changes: 81 additions & 25 deletions doc/botbuilder-choices/classes/botbuilder_choices.choicefactory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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. |



Expand All @@ -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. |



Expand All @@ -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. |



Expand All @@ -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. |



Expand All @@ -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. |



Expand Down
Loading