Input widgets are specialized controls which can be presented to the user at any time, as part of the conversation.
For example, when your conversation needs to get a user’s location, it is nice to present a specialized location picker widget for sending the location, which includes a map and the user’s current position:
In another dialog, you might require the user to make a multiple-choice selection using checkboxes. You could use the item picker widget for this case.
Lastly, we might want to present an entire form to the user at once. We can use the form input method for that, which looks like this:
Note: input widgets are currently only supported on the web platform. Other platforms do not show these widgets.
Input widgets in Bubblescript
Input widgets are triggered by passing a special input method value to the
expecting: clause of the
The choices variable here is filled using the
function, which takes the input widget type as the first argument, and
the configuration of the widget as the second argument.
Defining input widgets in data files
Instead of defining the widget in code like this, it is often easier to cleaner to create a YAML file and put the configuration in there:
ask "Which positions are you interesed in?", expecting: input_method("item_picker", @item_picker)
item_picker.yaml file contains:
caption: Please select mode: multiple items: - title: Frontend developer value: frontend - title: Backend developer value: backend - title: Marketing manager value: marketing
Input method reference
input_method(method, options) constructs a data
structure which triggers the showing of an input widget. It validates
the given options at runtime, to ensure that the widgets can be
presented in a sensible manner.
# construct the item picker input widget choices = input_method("item_picker", items: ["A", "B", "C"]) # feed it to 'ask' ask "Pick one item:", expecting: choices
Supported input methods are
"form". The options to these are described below.
All input widgets have some options shared between them:
required— Whether we require a value from the user or not. When the input is not required, a close button is shown in the top-right corner, allowing the user to cancel the interaction.
default_value— The preset value for the widget
height— A string, describing the desired height of the widget. Either
full. Defaults to
caption— An optional caption which is displayed as a title bar on top of the widget.
class— An optional CSS class which is set on the input widget. Can be used to tweak the styling for a particular widget.
item_picker input method is a versatile widget which can be used
in single and multiple selection mode.
multiple; defaults to
confirm— In the case of
single, this is a boolean value which can be set to
trueto show a confirmation button to confirm selection of the item. Otherwise, clicking the item immediately picks it.
items— The array of items that the user can choose from. The list can be either a list of plain strings, or it can be a list of maps with
titleelements (and optionally a
location input method takes the following options:
center— lat/lng coordinate that sets the initial position on the map
zoom— the initial zoom level, a number between 1 and 20. defaults to 12.
When triggered, the location selector asks permission to retrieve the
user’s location, and centers the map on that location. The
option is only used as fallback when the user has denied this
form input method presents an entire form to the user inside the
conversation. This can be used to let the user answer multiple
questions at once, for instance, to ask somebody for his address
Under the hood, this uses the React JSON Schema Form library. So most options described there are functional and usable in this input widget. The Form customization section especially, goes into detail on the available customization options.
form input method takes the following options:
schema— The JSON schema that the form adheres to.
ui_schema— Extra user interface options for the schema, see Form customization.
An example of a form input (as it is depicted in the image further up) is the following:
ask "Please enter your address", expecting: input_method("form", @address)
caption: Shipping address height: tall schema: type: object properties: street: type: string title: Street city: type: string title: City method: type: string title: "Shipping method" enum: ["Airplane", "Boat"] comments: type: string title: "Note" required: ["street", "city"] ui_schema: ui:order: - street - city - "*" comments: ui:widget: textarea