botbuilder-formflow v0.5.0

Table of Contents

• botbuilder-formflow
  • Glossary
  • Overview
  • How To Create Form Flow
  • Field Attributes
  • Prompt Types
  • Basic Messaging
  • Built-in Complex Dialogs
    • SwitchDialog
    • MenuDialog
  • Examples
  • Installation
  • Tests
• Changelog

botbuilder-formflow

Messaging framework for Microsoft Bot Framework. Initially, allowed only to create formflows, but starting from version 0.4 could be used as a replacement for standard Waterfall dialogs.

Glossary

• MBB or BotBuilder - Microsoft Bot Builder Framework;
• FormFlow Form - as mentioned in MBF documentation for .NET. Dialogs are very powerful and flexible, but handling a guided conversation such as ordering a sandwich can require a lot of effort. At each point in the conversation, there are many possibilities of what will happen next. For example, you may need to clarify an ambiguity, provide help, go back, or show progress. By using FormFlow within the Bot Builder SDK for .NET, you can greatly simplify the process of managing a guided conversation like this. Typical form flows: registration form, authentification form and etc
• FormFlow Field - a single attribute in FormFlow Form result. Could identify a request for required value (with corresponding validator) or a route to another dialog or could be fully customized ( When attributes prompt, errorPrompt, validator, extractor defined)

• Waterwall - A waterfall is a specific type of dialog handler. A waterfall contains an array of functions where the results of the first function are passed as input to the next function and so on. Official documentation

• Prompt - A built-in dialog that handles an input from a user. The user's input returned by session.endDialogWithresult() call. Official MBF prompts are used as a basis for more complex ones;
  

• Propmt Type - A classification of built-in Prompts in this library. The library allows you to use them to build complex and comprehensive form dialogs.

Overview

So, this Library helps you to build conversation dialogs with the user. The library accepts a flow and transforms it into a standard waterfall dialog.

The Library features:

• Standard Prompts plus prompts for emails and urls;
• Validators, Prompts, Error Prompts and Value extractors could be customized by a developer;
• Subdialogs are supported;
• Standard text messages and endConversation message;

Installation

    npm install --save botbuilder-formflow

How To Create Form Flow

The Library provides a factory function create used to create FormFlows forms. This function will create and inject a Waterfall dialog into a bot. Typical usage: formFlow.create(bot, '/form', formConfig); Where:

• bot is an actual instance of UniversalBot;
• '/form' - a Id for FormFlow dialog;
• formFlow - an array, each item contains a configuration of prompt for a field;

FormFlow Items

• required type - (String) attribute used to identify validators and business logic.
• id - (String)
• prompt - (String|Function)
• errorPrompt or error - (String|Function) - that message will be displayed to a user in case, if users response failed validation
• validator - (String|Function|Object)
• response - (String|Function)
• extractor - (Function), a function which purpose to extract the response from dialog result. If extractor returns a Promise object, than resolved value of the promise will be treated as a result
• options - (Object), an object that will be passed into standard MBF Prompt dialog as options argument

Prompt Types

You can use predefined prompts or custom dialog wrappers around MBF prompts. Dialogs for each field evaluated separately and could be customized. Every type could bring its own default validation, custom behaviour and could require additional attributes.

• choices(string | Object | string[] | IChoice[]) - A wrapper around builder.Prompt.choice Prompt.
• confirm - A wrapper around builder.Prompts.confirm Prompt;
• custom - Use that type to inject your prompts;
• dialog - dialog (String|Array|Function) a route to a dialog or a constructor for Waterfall dialog. This option also requires next attributes to be defined:
  • dialog - (String|Array|Function) Waterfall dialog;
• email - A wrapper around /^\S+@\S+$/ RegExp
• number - A wrapper around builder.PromptRecognizers.recognizeNumbers() internal BotBuilder function;
• text - A wrapper around builder.Prompts.text Prompt;
• time - A wrapper around botbuilder.PromptRecognizers.recognizeTimes internal BotBuilder function;
• url - A wrapper around /^(ftp|http|https):\/\/[^ "]+$/ RegExp
• attachment - Use that prompt for requesting attachments from the user

Basic Messaging

If you want use standard messages (without prompts) in your flows, the Library allows that. At current moment, there are two type of messages supported:

• message - (String, Message, Function ) - sends a message to user, in case, if function passed as a value, than it should return a Promise object to signal the Library to continue execution;
• endConversation - (String|Null) - sends a endConversation message, if string value passed than the Library will send it a normal message;

Built-in Complex Dialogs

SwitchDialog

The purpose of this prompt to display list of choices and depending on user choice to forward conversation to selected dialog. List of choices is a key-value object where key is a label that will be displayed to user and value is id of the dialog or waterfall array, in that case SwitchDialog will register it in the bot automatically

Example

const FormFlow = require('botbuilder-formflow');

new FormFlow.SwitchDialog({
    id : 'subdialog',  // Results will be stored in `subdialog` propterty
    prompt : 'Please, select subdialog', // Prompt message for a user
    choices : {   
      'Add' : '/add',
      'Remove' : [
        function ( session ) {
          session.endDialogWithResult({
            "response":'Hello world!'
          });
        }
      ]
    }
  })

MenuDialog

This dialog provides a menu inside conversation. Menu items displayed as suggested actions for the user. Dialog supports pagination of the results and labels for prev/next messages could be customized.

Options for MenuDialog:

• prompt string required - Message text that will be delivered to a user
• items Object|Callback required:
  • key-value object, where key is a text of suggested action and value could be either an array (Waterfall Dialog) either string (dialog id)
  • Callback a function that should return a Promise. Session object passed to the callback as an argument. To display menu items the promise should be resolved with key-value object (described above)
• items_per_message int - amount of menu items to show per message
• prevLabel string - label for "prev" message
• nextLabel string - label for "next" message

Option with key-value configuration object:

const FormFlow = require('botbuilder-formflow');
new FormFlow.MenuDialog({
    message : '',
    items : {
        'make an order': '/order',
        'menu 1' : '/menu1',
        'menu 2' : '/menu2',
        'menu 3' : '/menu3',
        'exit' : [
            function (session) {
                session.endDialog()
            }
        ],
        'help' : '/help' 
    }
});

Full featured example:

new FormFlow.MenuDialog({
    "prompt": "Menu items",
    "items_per_message" : 5,
    "prevLabel" : "<-",
    "nextLabel" : "->",
    "items" : function (session) {
      return Promise.resolve({
        'make an order': '/order',
        'menu 1' : '/menu1',
      })
    }
  })

It is possible to have submenu dialogs:

new FormFlow.MenuDialog({
    "prompt": "Menu items",
    "retryPrompt" : "Fuck!",
    "items" : {
      'submenu' : new FormFlow.MenuDialog({
        "prompt": "SubMenu items",
        "items" : {
          'submenu 0' : '/submenu0',
          'submenu 1' : '/submenu1'
        }
      }),
      'menu 0': '/menu0'
    }
  })

How To Extend the Library

You could extend steps library with your own. The object exposed by Library in its exports section is a instance of EventEmitter. You only need to subscribe on buildFieldDialog event. The event listener will accept four arguments:

• bot Object - Bot instance
• id string - dialog id
• stepConfig Object - configuration of the step
• steps array - contains array of steps that will be organized in a result dialog for the field.

const formFlow = require('botbuilder-formflow');

Examples

1. Simple registration form
2. Custom validator for a field
3. Form with a subform
4. List of validators for specific fields
5. Comperehensive menu

Changelog

• 0.5.0 - Extensions supported, Menu example prepared;
• 0.4.5 - Fixes for "MenuDialog";
• 0.4.4 - Updates for "MenuDialog";
• 0.4.3 - New custom dialog "MenuDialog";
• 0.4.2 - Fixes for SwitchDialog;
• 0.4.1 - Support for attachment prompt;
• 0.4.0 - Support for text messages and endConversation;
• 0.3.0 - SwitchDialog introduced, "init" step introduced