Forms

The creation of a chat session can result in need to display an unavailable chat, or a pre-chat form.

All unavailable, pre and even post-chat have a common representation of forms, called BCForm. A form consist of a list of form fields, represented by BCFormField class.

BCFormField has the following properties:

type: The display style of the field.
- BCFormFieldTypeText: A text input.
- BCFormFieldTypeSelect, BCFormFieldTypeRadio: A selector input that selects from options in options property.
- BCFormFieldTypeRating: One to five star rating input.
- BCFormFieldTypePhone: Phone number input.
- BCFormFieldTypeEmail: Email address input.
key: The key of the field. The answers refer to this key.
isMultiline: If the type is Text, this field needs to be displayed as a multiline text input.
label: Not localized (English) title of the field.
labelBrandingKey: Branding key of the title of the fields. The branding dictionary can be obtained from chatSession.branding.
isRequired: Required to be filled. The submission returns an error if a required field is not filled.
isVisible: The field is visible, needs to be shown. The language selector can be set to be hidden.
isDepartmentStatusVisible: This field is an option list of departments. If set the availability status of the department needs to be shown with its name.
defaultValue: The default value of the field.
options: if the type is Select or Radio, the option is a list of BCFormFieldOption class objects.
defaultOption: if a default option is set it holds the pointer to it.
value: The answer for the field needs to be put here, when the form is submitted. It is the text the user typed, the number of stars or the value of the option selected.

If the type of a field is Select or Radio, the user can set a value from a predefined set of options in options property. Options is a list of BCFormFieldOption class objects. An option has the following properties:

name: Not localized name to be displayed.
value: The value that needs to be set as the container BCFormField value, if this option is selected.
nameBrandingKey: If branding is enabled it holds the branding key for the title of the option. The branding values are in chatSession.branding dictionary.
availableLabel: Localized text that describes the availability state of the option. It is used for displaying the availability state of departments. The available and unavailable text are also in the branding dictionary with api::department::available and api::department::unavailable keys.
isDefaultValue: It is the default option
isAvailable: If the field has availability settings(only departments have now), it holds the availability state of the option.
isAvailabilitySet: the availability of the field is defined.

The handling of forms is the following:

The BCForm is returned from the server for the current chat process state.
Present the form
Set the value fields of the form fields with the results from the user.
Submit the form with the filled values to the server.