Microsoft.Bot.Builder.FormFlow.Json.FormBuilderJson Class Referenceabstract

Build a form by specifying messages, fields and confirmations through JSON Schema or programatically. More...

Inheritance diagram for Microsoft.Bot.Builder.FormFlow.Json.FormBuilderJson:

Public Member Functions

 FormBuilderJson (JObject schema)
 Create a JSON form builder. More...
 
override IFormBuilder< JObject > AddRemainingFields (IEnumerable< string > exclude=null)
 Add all fields not already added to the form. More...
 
override IForm< JObject > Build (Assembly resourceAssembly=null, string resourceName=null)
 Build the form based on the methods called on the builder. More...
 
virtual IFormBuilder< T > Confirm (string prompt, ActiveDelegate< T > condition=null, IEnumerable< string > dependencies=null)
 Add a confirmation step. More...
 
virtual IFormBuilder< T > Confirm (PromptAttribute prompt, ActiveDelegate< T > condition=null, IEnumerable< string > dependencies=null)
 Add a confirmation step. More...
 
virtual IFormBuilder< T > Confirm (MessageDelegate< T > generateMessage, ActiveDelegate< T > condition=null, IEnumerable< string > dependencies=null)
 Generate a confirmation using a delegate to dynamically build the message. More...
 
virtual IFormBuilder< T > Field (IField< T > field)
 Derfine a field step by supplying your own field definition. More...
 
override IFormBuilder< JObject > Field (string name, ActiveDelegate< JObject > active=null, ValidateAsyncDelegate< JObject > validate=null)
 
override IFormBuilder< JObject > Field (string name, string prompt, ActiveDelegate< JObject > active=null, ValidateAsyncDelegate< JObject > validate=null)
 
override IFormBuilder< JObject > Field (string name, PromptAttribute prompt, ActiveDelegate< JObject > active=null, ValidateAsyncDelegate< JObject > validate=null)
 
abstract IFormBuilder< T > Field (string name, ActiveDelegate< T > active=null, ValidateAsyncDelegate< T > validate=null)
 Define a step for filling in a particular value in the form state. More...
 
abstract IFormBuilder< T > Field (string name, string prompt, ActiveDelegate< T > active=null, ValidateAsyncDelegate< T > validate=null)
 Define a step for filling in a particular value in the form state. More...
 
abstract IFormBuilder< T > Field (string name, PromptAttribute prompt, ActiveDelegate< T > active=null, ValidateAsyncDelegate< T > validate=null)
 Define a step for filling in a particular value in the form state. More...
 
bool HasField (string name)
 Test to see if there is already a field with name . More...
 
virtual IFormBuilder< T > Message (string message, ActiveDelegate< T > condition=null, IEnumerable< string > dependencies=null)
 Show a message that does not require a response. More...
 
virtual IFormBuilder< T > Message (PromptAttribute prompt, ActiveDelegate< T > condition=null, IEnumerable< string > dependencies=null)
 Show a message with more format control that does not require a response. More...
 
virtual IFormBuilder< T > Message (MessageDelegate< T > generateMessage, ActiveDelegate< T > condition=null, IEnumerable< string > dependencies=null)
 Generate a message using a delegate to dynamically build the message. More...
 
virtual IFormBuilder< T > OnCompletion (OnCompletionAsyncDelegate< T > callback)
 Delegate to call when form is completed. More...
 
virtual IFormBuilder< T > Prompter (PromptAsyncDelegate< T > prompter)
 Delegate to send prompt to user. More...
 

Properties

FormConfiguration Configuration [get]
 
JObject Schema [get]
 

Detailed Description

Build a form by specifying messages, fields and confirmations through JSON Schema or programatically.

Define a form via JSON Schema with optional additional annotations that correspond to the attributes provided for C#. FormFlow makes use of a number of standard JSON Schema keywords include:

  • type – Defines the fields type.
  • enum – Defines the possible field values.
  • minimum – Defines the minimum allowed value as described in NumericAttribute.
  • maximum – Defines the maximum allowed value as described in NumericAttribute.
  • required – Defines what fields are required.
  • pattern – For string fields will be used to validate the entered pattern as described in PatternAttribute.

Templates and prompts use the same vocabulary as TemplateAttribute and PromptAttribute. The property names are the same and the values are the same as those in the underlying C# enumeration. For example to define a template to override the TemplateUsage.NotUnderstood template and specify a TemplateBaseAttribute.ChoiceStyle, you would put this in your schema:

"Templates":{ "NotUnderstood": { Patterns: ["I don't get it"], "ChoiceStyle":"Auto"}}

Extensions defined at the root fo the schema

Extensions defined at the root of a schema or as a peer of the "type" property.

  • Templates:{TemplateUsage: { Patterns:[string, ...], <args> }, ...} – Define templates.
  • Prompt: { Patterns:[string, ...] <args>} – Define a prompt.

Extensions that are found in a property description as peers to the "type" property of a JSON Schema.

  • DateTime:bool – Marks a field as being a DateTime field.
  • Describe:string – Description of a field as described in DescribeAttribute.
  • Terms:[string,...] – Regular expressions for matching a field value as described in TermsAttribute.
  • MaxPhrase:int – This will run your terms through Language.GenerateTerms(string, int) to expand them.
  • Values:{ string: {Describe:string, Terms:[string, ...], MaxPhrase}, ...} – The string must be found in the types "enum" and this allows you to override the automatically generated descriptions and terms. If MaxPhrase is specified the terms are passed through Language.GenerateTerms(string, int).
  • Active:script – C# script with arguments (JObject state)->bool to test to see if field/message/confirm is active.
  • Validate:script – C# script with arguments (JObject state, object value)->ValidateResult for validating a field value.
  • Define:script – C# script with arguments (JObject state, Field<JObject> field) for dynamically defining a field.
  • Before:[confirm|message, ...] – Messages or confirmations before the containing field.
  • After:[confirm|message, ...] – Messages or confirmations after the containing field.
  • {Confirm:script|[string, ...], ...templateArgs} – With Before/After define a confirmation through either C# script with argument (JObject state) or through a set of patterns that will be randomly selected with optional template arguments.
  • {Message:script|[string, ...] ...templateArgs} – With Before/After define a message through either C# script with argument (JObject state) or through a set of patterns that will be randomly selected with optional template arguments.
  • Dependencies:[string, ...]` – Fields that this field, message or confirm depends on.

Scripts can be any C# code you would find in a method body. You can add references through "References" and using through "Imports". Special global variables include:

  • choice – internal dispatch for script to execute.
  • state – JObject form state bound for all scripts.
  • ifieldIField<JObject> to allow reasoning over the current field for all scripts except Message/Confirm prompt builders.
  • value – object value to be validated for Validate.
  • fieldField<JObject> to allow dynamically updating a field in Define.
  • context – IDialogContext context to allow posting results in OnCompletion.

Fields defined through this class have the same ability to extend or override the definitions programatically as any other field. They can also be localized in the same way.

Definition at line 109 of file FormBuilderJson.cs.

Constructor & Destructor Documentation

Microsoft.Bot.Builder.FormFlow.Json.FormBuilderJson.FormBuilderJson ( JObject  schema)
inline

Create a JSON form builder.

Parameters
schemaJSON Schema that defines form.

Definition at line 115 of file FormBuilderJson.cs.

Member Function Documentation

override IFormBuilder<JObject> Microsoft.Bot.Builder.FormFlow.Json.FormBuilderJson.AddRemainingFields ( IEnumerable< string >  exclude = null)
inlinevirtual

Add all fields not already added to the form.

Parameters
excludeFields not to include.
Returns
Modified IFormBuilder.

This will add all fields defined in your form that have not already been added if the fields are supported.

Implements Microsoft.Bot.Builder.FormFlow.FormBuilderBase< JObject >.

Definition at line 193 of file FormBuilderJson.cs.

override IForm<JObject> Microsoft.Bot.Builder.FormFlow.Json.FormBuilderJson.Build ( Assembly  resourceAssembly = null,
string  resourceName = null 
)
inlinevirtual

Build the form based on the methods called on the builder.

Parameters
resourceAssemblyAssembly for localization resources.
resourceNameName of resources to use for localization.
Returns
The constructed form.

The default assembly is the one that contains T and the default resourceName if the name of that type.

Reimplemented from Microsoft.Bot.Builder.FormFlow.FormBuilderBase< JObject >.

Definition at line 122 of file FormBuilderJson.cs.

virtual IFormBuilder<T> Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.Confirm ( string  prompt,
ActiveDelegate< T >  condition = null,
IEnumerable< string >  dependencies = null 
)
inlinevirtualinherited

Add a confirmation step.

Parameters
promptPrompt to use for confirmation.
conditionDelegate to test if confirmation applies to the current form state.
dependenciesWhat fields this confirmation depends on.
Returns
Modified IFormBuilder.

If prompt is not supplied the Pattern Language element {*} will be used to confirm. Dependencies will by default be all active steps defined before this confirmation.

Definition at line 141 of file FormBuilder.cs.

virtual IFormBuilder<T> Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.Confirm ( PromptAttribute  prompt,
ActiveDelegate< T >  condition = null,
IEnumerable< string >  dependencies = null 
)
inlinevirtualinherited

Add a confirmation step.

Parameters
promptPrompt to use for confirmation.
conditionDelegate to test if confirmation applies to the current form state.
dependenciesWhat fields this confirmation depends on.
Returns
Modified IFormBuilder.

Dependencies will by default be all active steps defined before this confirmation.

Definition at line 146 of file FormBuilder.cs.

virtual IFormBuilder<T> Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.Confirm ( MessageDelegate< T >  generateMessage,
ActiveDelegate< T >  condition = null,
IEnumerable< string >  dependencies = null 
)
inlinevirtualinherited

Generate a confirmation using a delegate to dynamically build the message.

Parameters
generateMessageDelegate for building message.
conditionWhether or not this step is active.
dependenciesWhat fields this confirmation depends on.
Returns
Modified IFormBuilder.

Definition at line 157 of file FormBuilder.cs.

virtual IFormBuilder<T> Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.Field ( IField< T >  field)
inlinevirtualinherited

Derfine a field step by supplying your own field definition.

Parameters
fieldField definition to use.
Returns
Modified IFormBuilder.

You can provide your own implementation of IField<T> or you can use the Field<T> class to provide fluent values, FieldReflector<T> to use reflection or Json.FieldJson to use JSON Schema.

Definition at line 136 of file FormBuilder.cs.

override IFormBuilder<JObject> Microsoft.Bot.Builder.FormFlow.Json.FormBuilderJson.Field ( string  name,
ActiveDelegate< JObject >  active = null,
ValidateAsyncDelegate< JObject >  validate = null 
)
inline

Definition at line 162 of file FormBuilderJson.cs.

override IFormBuilder<JObject> Microsoft.Bot.Builder.FormFlow.Json.FormBuilderJson.Field ( string  name,
string  prompt,
ActiveDelegate< JObject >  active = null,
ValidateAsyncDelegate< JObject >  validate = null 
)
inline

Definition at line 173 of file FormBuilderJson.cs.

override IFormBuilder<JObject> Microsoft.Bot.Builder.FormFlow.Json.FormBuilderJson.Field ( string  name,
PromptAttribute  prompt,
ActiveDelegate< JObject >  active = null,
ValidateAsyncDelegate< JObject >  validate = null 
)
inline

Definition at line 178 of file FormBuilderJson.cs.

abstract IFormBuilder<T> Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.Field ( string  name,
ActiveDelegate< T >  active = null,
ValidateAsyncDelegate< T >  validate = null 
)
pure virtualinherited

Define a step for filling in a particular value in the form state.

Parameters
namePath in the form state to the value being filled in.
activeDelegate to test form state to see if step is active.
validateDelegate to validate the field value.
Returns
Modified IFormBuilder.
abstract IFormBuilder<T> Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.Field ( string  name,
string  prompt,
ActiveDelegate< T >  active = null,
ValidateAsyncDelegate< T >  validate = null 
)
pure virtualinherited

Define a step for filling in a particular value in the form state.

Parameters
namePath in the form state to the value being filled in.
promptSimple Pattern Language to describe prompt for field.
activeDelegate to test form state to see if step is active.n
validateDelegate to validate the field value.
Returns
Modified IFormBuilder.
abstract IFormBuilder<T> Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.Field ( string  name,
PromptAttribute  prompt,
ActiveDelegate< T >  active = null,
ValidateAsyncDelegate< T >  validate = null 
)
pure virtualinherited

Define a step for filling in a particular value in the form state.

Parameters
namePath in the form state to the value being filled in.
promptPrompt pattern with more formatting control to describe prompt for field.
activeDelegate to test form state to see if step is active.n
validateDelegate to validate the field value.
Returns
Modified IFormBuilder.
bool Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.HasField ( string  name)
inlineinherited

Test to see if there is already a field with name .

Parameters
name
Returns
True if field is already present.

Definition at line 113 of file FormBuilder.cs.

virtual IFormBuilder<T> Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.Message ( string  message,
ActiveDelegate< T >  condition = null,
IEnumerable< string >  dependencies = null 
)
inlinevirtualinherited

Show a message that does not require a response.

Parameters
messageA Pattern Language string to fill in and send.
conditionWhether or not this step is active.
dependenciesFields message depends on.
Returns
Modified IFormBuilder.

Definition at line 118 of file FormBuilder.cs.

virtual IFormBuilder<T> Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.Message ( PromptAttribute  prompt,
ActiveDelegate< T >  condition = null,
IEnumerable< string >  dependencies = null 
)
inlinevirtualinherited

Show a message with more format control that does not require a response.

Parameters
promptMessage to fill in and send.
conditionWhether or not this step is active.
dependenciesFields message depends on.
Returns
Modified IFormBuilder.

Definition at line 124 of file FormBuilder.cs.

virtual IFormBuilder<T> Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.Message ( MessageDelegate< T >  generateMessage,
ActiveDelegate< T >  condition = null,
IEnumerable< string >  dependencies = null 
)
inlinevirtualinherited

Generate a message using a delegate to dynamically build the message.

Parameters
generateMessageDelegate for building message.
conditionWhether or not this step is active.
dependenciesFields message depends on.
Returns
Modified IFormBuilder.

Definition at line 130 of file FormBuilder.cs.

virtual IFormBuilder<T> Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.OnCompletion ( OnCompletionAsyncDelegate< T >  callback)
inlinevirtualinherited

Delegate to call when form is completed.

Parameters
callbackDelegate to call on completion.
Returns
Modified IFormBuilder.

This should only be used for side effects such as calling your service with the form state results. In any case the completed form state will be passed to the parent dialog.

Definition at line 168 of file FormBuilder.cs.

virtual IFormBuilder<T> Microsoft.Bot.Builder.FormFlow.FormBuilderBase< T >.Prompter ( PromptAsyncDelegate< T >  prompter)
inlinevirtualinherited

Delegate to send prompt to user.

Parameters
prompterDelegate.
Returns
Modified IFormBuilder.

Definition at line 174 of file FormBuilder.cs.

Property Documentation

Definition at line 111 of file FormBuilder.cs.

JObject Microsoft.Bot.Builder.FormFlow.Json.FormBuilderJson.Schema
get

Definition at line 210 of file FormBuilderJson.cs.


The documentation for this class was generated from the following file: