VoiceForm
A plugin for Adhearsion to add form functionality and flow, similar to VoiceXML style forms.
By Adam Meehan (adam.meehan@gmail.com, http://duckpunching.com/)
Released under the MIT license.
Introduction
The plugin adds form features to Adhearsion components to quickly and semantically setup data input for your voice application. You define a form and form fields in which to collect data and setup callbacks to instruct the caller, give feedback, confirm input and validate input.
Install
sudo gem install voice_form
At the bottom your projects startup.rb file put
require 'voice_form'
Example
Here is the Adhearsion example Simon game redone using voice_form:
class SimonGame
include VoiceForm
voice_form do
setup do
@number = ''
end
field(:attempt, :attempts => 1) do
prompt :play => :current_number, :bargein => false, :timeout => 2
setup do
@number << random_number
end
validate do
@attempt == @number
end
success do
call.play 'good'
form.restart
end
failure do
call.play %W[#{@number.length-1} times wrong-try-again-smarty]
@number = ''
form.restart
end
end
end
def random_number
rand(10).to_s
end
def current_number
as_digits(@number)
end
end
That covers most of the functionality, and hopefully it makes sense pretty much straight away.
To start the form, in your dialplan:
For Adhearsion 0.7.999
general {
simon_game = new_simon_game
simon_game.start_voice_form(self)
}
For Adhearsion 0.8.x
general {
SimonGame.start_voice_form(self)
}
You don't have to start the form from the dialplan, but it makes it simple. You could start it from within a component method.
All callback blocks (setup, validate, timeout etc.) are evaluated in the component scope so you can use component methods and instance variables in them and they will work. You don't have to define any callbacks if the field is straight forward and only depends on its length.
For a more complete example see the examples folder.
Commands
voice_form
The flow of the form works like a stack. So each field and do_block are executed in order until the
end of the form is reached. You can jump around the stack by using form.goto :field_name
which
will move the stack pointer to the field after the current field is completed and move forward
through the form stack from that point, regardless whether a field has already been completed.
You can also use form.restart
to start the form over from the beginning.
The form setup block is only run once and is not executed again, even with a form.restart
.
field
This defines the field with the name given to collect on the form. The field method can be used
in a voice_form
or on its own inside a component method.
The options available are:
- :length - the number of digits to accept
- :min_length - minimum number of digits to accept
- :max_length - maximum number of digits to accept
- :attempts - number of tries to get a valid input
- :call - the method name for the call context if other than 'call'. Used for standalone fields not in a form.
All fields defined get an accessor method defined of the same name in the component class. This means you can access its value using the instance variable or the accessor method inside any of the field callbacks and in other fields on a form.
The prompt
and reprompt
methods are a wrapper around the input command. And as such is always
interruptable or you can bargein when you want to starting keying numbers. You pass in a
hash of options to control the prompt such as:
- :play - play one or more sound files
- :speak - play TTS text (needs my Adhearsion hack for speak in input command)
- :timeout - number of seconds to wait for input. Default is 5.
- :repeats - number of attempts to use this prompt until the next one is used
- :bargein - whether to allow caller to interrupt prompt. Default is true.
The length expected for the input is taken from the options passed to the field
method.
You can only use one of :play or :speak.
There can only be one prompt
but you can have multiple reprompt
s. When you add a reprompt it changes
what the prompt is if there is input the first time or the input is invalid.
Callbacks
The available callbacks that can be defined for a field are as follows
- setup
- timeout
- validate
- invalid
- confirm
- success
- failure
Each of them takes a block which is executed as a specific point in the process of getting form input. All of them are optional. The block for a callback is evaluated in the scope of the component so any instance variables and component methods are available to use including the call context.
The details of each callback are as follows
setup
This is run once only for a field if defined before any prompts
timeout
This is run if no input is received or input is not of a valid length as defined by length or min_length field options.
validate
This is run after input of a valid length. The validate block is where you put validation logic of the
value just input by the user. The block should return true
if the value is valid or false
otherwise.
If the validate callback returns false then the invalid callback will be called next.
invalid
The invalid callback is called if validate block returns false.
confirm
The confirm callback is called after the input has been validated. The confirm callback is a little different from the others. Idea is that you return either an array or string of the audio files or TTS text, respectively, you want to play as the prompt for confirming the value entered. The confirm block also takes a few options:
- :accept - the number to press to accept the field value entered. Default is 1.
- :reject - the number to press the reject the field value entered and try again. Default is 2.
- :attempts - the number of attempts to try to get a confirmation response. Default is 3
- :timeout - the number of seconds to wait for input after the confirmation response. Default is 3.
The value returned from the block should form the complete list of audio files or TTS text to prompt the user including the values to accept of reject the value.
For example, in a field called my_field:
confirm(:accept => 1, :reject => 2, :attempts => 3) do
['you-entered', as_digits(@my_field), 'is-this-correct', 'press-1-accept-2-try-again'].flatten
end
The above will play
the array of audio files as the prompt for confirmation.
confirm(:accept => 1, :reject => 2, :attempts => 3) do
"You entered #{@my_field}. Is this correct? Press 1 to accept or 2 try again."
end
The above will speak
the string as the prompt for confirmation.
If no valid input is entered for the confirmation then another you will be reprompted to enter the field value.
Form methods
Inside a callback you have the form
method available. The returns the instance of the current form. The form
has some methods to allow you to perform form actions which manipulate the form stack. These actions are as follows:
form.goto
Inside any callback you can use the goto
command to designate which field the form should run after the
current field. Normally the form will progress through the fields in the order defined, but a goto with shift
the current form position to the field name pass to it like so:
failure do
form.goto :other_field_name
end
The form continues from the field in the goto run each subsequent field in order. If the goto field is above the current field then the current field will be executed again when it is reached in the stack. If the goto field is below the current field then form will continue there, skipping whatever fields may lie between the current and the goto field.
form.restart
The form may be restarted from the start at any point with form.restart
. This will go back to the top of the
form and proceed through each field again. The form setup will not be run again however.
form.exit
To exit the form after the current field is complete just execute form.exit
. The application will then be
returned to where the form was started, be it a dialplan or another form.
Credits
Adam Meehan (adam.meehan@gmail.com, http://duckpunching.com/)
Also thanks to Jay Phillips et al. for the brilliant work on Adhearsion (http://adhearsion.com)