ChoiceFactory class

  • Reference
Package:
botbuilder-dialogs

A set of utility functions to assist with the formatting a 'message' activity containing a list of choices.

Remarks

This example shows creating a message containing a list of choices that has been conditionally formatted based on the capabilities of the underlying channel:

const { ChoiceFactory } = require('botbuilder-choices');

const message = ChoiceFactory.forChannel(context, ['red', 'green', 'blue'], `Pick a color.`);
await context.sendActivity(message);

Methods

forChannel(string | TurnContext, string | Choice[], string, string, ChoiceFactoryOptions)

Returns a 'message' activity containing a list of choices that has been automatically formatted based on the capabilities of a given channel.
heroCard(string | Choice[], string, string)

Creates a message Activity that includes a Choice list that have been added as HeroCard's.
inline(string | Choice[], string, string, ChoiceFactoryOptions)

Returns a 'message' activity containing a list of choices that has been formatted as an inline list.
list(string | Choice[], string, string, ChoiceFactoryOptions)

Returns a 'message' activity containing a list of choices that has been formatted as an numbered or bulleted list.
suggestedAction(string | Choice[], string, string)

Returns a 'message' activity containing a list of choices that have been added as suggested actions.
toChoices(string | Choice[] | undefined)

Takes a mixed list of string and Choice based choices and returns them as a Choice[].

Method Details

forChannel(string | TurnContext, string | Choice[], string, string, ChoiceFactoryOptions)

Returns a 'message' activity containing a list of choices that has been automatically formatted based on the capabilities of a given channel.

static function forChannel(channelOrContext: string | TurnContext, choices: string | Choice[], text?: string, speak?: string, options?: ChoiceFactoryOptions): Partial<Activity>

Parameters

channelOrContext

string | TurnContext

Channel ID or context object for the current turn of conversation.

choices

string | Choice[]

List of choices to render.

text

string

(Optional) text of the message.

speak

string

(Optional) SSML to speak for the message.

options
ChoiceFactoryOptions

(Optional) formatting options to use when rendering as a list.

Returns

Partial<Activity>

The created message activity.

Remarks

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.

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);

heroCard(string | Choice[], string, string)

Creates a message Activity that includes a Choice list that have been added as HeroCard's.

static function heroCard(choices?: string | Choice[], text?: string, speak?: string): Activity

Parameters

choices

string | Choice[]

Optional. The Choice list to add.

text

string

Optional. Text of the message.

speak

string

Optional. SSML text to be spoken by the bot on a speech-enabled channel.

Returns

Activity

An Activity with choices as HeroCard with buttons.

inline(string | Choice[], string, string, ChoiceFactoryOptions)

Returns a 'message' activity containing a list of choices that has been formatted as an inline list.

static function inline(choices: string | Choice[], text?: string, speak?: string, options?: ChoiceFactoryOptions): Partial<Activity>

Parameters

choices

string | Choice[]

List of choices to render.

text

string

(Optional) text of the message.

speak

string

(Optional) SSML to speak for the message.

options
ChoiceFactoryOptions

(Optional) formatting options to tweak rendering of list.

Returns

Partial<Activity>

The created message activity.

Remarks

This 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);

list(string | Choice[], string, string, ChoiceFactoryOptions)

Returns a 'message' activity containing a list of choices that has been formatted as an numbered or bulleted list.

static function list(choices: string | Choice[], text?: string, speak?: string, options?: ChoiceFactoryOptions): Partial<Activity>

Parameters

choices

string | Choice[]

List of choices to render.

text

string

(Optional) text of the message.

speak

string

(Optional) SSML to speak for the message.

options
ChoiceFactoryOptions

(Optional) formatting options to tweak rendering of list.

Returns

Partial<Activity>

The created message activity.

Remarks

This example generates a message with the choices presented as a numbered list:

const message = ChoiceFactory.list(['red', 'green', 'blue'], `Pick a color:`);
await context.sendActivity(message);

suggestedAction(string | Choice[], string, string)

Returns a 'message' activity containing a list of choices that have been added as suggested actions.

static function suggestedAction(choices: string | Choice[], text?: string, speak?: string): Partial<Activity>

Parameters

choices

string | Choice[]

List of choices to add.

text

string

(Optional) text of the message.

speak

string

(Optional) SSML to speak for the message.

Returns

Partial<Activity>

An activity with choices as suggested actions.

Remarks

This example generates a message with the choices presented as suggested action buttons:

const message = ChoiceFactory.suggestedAction(['red', 'green', 'blue'], `Pick a color:`);
await context.sendActivity(message);

toChoices(string | Choice[] | undefined)

Takes a mixed list of string and Choice based choices and returns them as a Choice[].

static function toChoices(choices: string | Choice[] | undefined): Choice[]

Parameters

choices

string | Choice[] | undefined

List of choices to add.

Returns

Choice[]

A list of choices.

Remarks

This example converts a simple array of string based choices to a properly formated Choice[].

If the Choice has a Partial<CardAction> for Choice.action, .toChoices() will attempt to fill the Choice.action.

const choices = ChoiceFactory.toChoices(['red', 'green', 'blue']);