adzap-voice_form 0.1.1 → 0.2.0

data/History.txt

@@ -1,3 +1,6 @@
+== 0.2.0 2009-01-16
+* Updated to work with Adhearsion 0.8.0 release. Examples updated to match new usage.
+
 == 0.1.1 2008-11-12
 * refactored to auto include voice_form method in components, no more 'include VoiceForm'
 

data/README.markdown

@@ -33,7 +33,6 @@ command to play your sound files.
 
     class MyComponent
       include VoiceForm
-      add_call_context :as => :call_context
 
       voice_form do      
       
@@ -53,6 +52,10 @@ command to play your sound files.
             @age.to_i <= @max_age
           end
           
+          confirm(:accept => 1, :reject => 2, :timeout => 3, :attempts => 3) do
+            "You entered #{@age}. Press 1 to continue or 2 to try again."
+          end
+          
           invalid do
             call_context.speak "Your age must be less than #{@max_age}. Try again."
           end
@@ -72,8 +75,7 @@ command to play your sound files.
 In your dialplan:
 
     general {
-      my_component = new_my_component
-      my_component.start_voice_form
+      MyComponent.new.start_voice_form(self)
     }
 
 That covers most of the functionality, and hopefully it makes sense pretty much straight 
@@ -82,11 +84,14 @@ away.
 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 blocks (setup, validate, do_block etc.) are evaluated in the component scope so you can use 
-component methods and instance variables in them and they will work.
+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 
@@ -137,8 +142,72 @@ There can only be one `prompt` but you can have multiple `reprompt`s. When you a
 what the prompt is if there is input the first time or the input is invalid.
 
 
-TODO: Add specific info for callback and option.
+### 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.
+
+### 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 the input value is not of a valid length or the 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', @my_field.scan(/\d/), 'is-this-correct', 'press-1-accept-2-try-again'].flatten
+    end
+
+The above will `play` the array of audo 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 
 
 TODO: More docs
 

data/Rakefile

@@ -5,11 +5,11 @@ require 'date'
 require 'spec/rake/spectask'
 
 GEM = "voice_form"
-GEM_VERSION = "0.1.0"
+GEM_VERSION = "0.2.0"
 AUTHOR = "Adam Meehan"
 EMAIL = "adam.meehan@gmail.com"
 HOMEPAGE = "http://github.com/adzap/voice_form"
-SUMMARY = "A DSL for Adhearsion to create forms in the style of the VoiceXML form element."
+SUMMARY = "A plugin for Adhearsion to create forms in the style of the VoiceXML form element."
 
 spec = Gem::Specification.new do |s|
   s.name = GEM

data/examples/my_component.rb

@@ -1,6 +1,7 @@
 class MyComponent
   include VoiceForm
-  add_call_context :as => :call_context
+
+  delegate :play, :speak, :to => :call_context
 
   voice_form do      
     field(:age, :max_length => 3, :attempts => 3) do
@@ -12,20 +13,20 @@ class MyComponent
       validate { @age.to_i < @max_age }
       
       invalid do
-        call_context.speak "Your age must be less than #{@max_age}. Try again."
+        speak "Your age must be less than #{@max_age}. Try again."
       end
       
       success do
-        call_context.speak "You are #{@age} years old."
+        speak "You are #{@age} years old."
       end
       
       failure do
-        call_context.speak "You could not enter your age. Thats a bad sign."
+        speak "You could not enter your age. Thats a bad sign."
       end
     end
     
     do_block do
-      call_context.speak "Get ready for the next question."
+      speak "Get ready for the next question."
     end
     
     field(:postcode, :length => 4, :attempts => 5) do
@@ -35,19 +36,19 @@ class MyComponent
       
       invalid do
         if @postcode.size < 4
-          call_context.speak "Your postcode must 4 digits."
+          speak "Your postcode must 4 digits."
         else
-          call_context.speak "Your postcode cannot start with a 0."
+          speak "Your postcode cannot start with a 0."
         end
       end
       
       success do
-        call_context.speak "Your postcode is #{@postcode.scan(/\d/).join(', ')}."
+        speak "Your postcode is #{@postcode.scan(/\d/).join(', ')}."
       end
       
       failure do
         if @age.empty?
-          call_context.speak "Lets start over shall we."
+          speak "Lets start over shall we."
           form.restart
         end
       end

data/lib/voice_form.rb

@@ -1,11 +1,3 @@
 require 'voice_form/form_methods'
 require 'voice_form/form'
 require 'voice_form/form_field'
-
-Adhearsion::Components::Behavior.module_eval do
-  include VoiceForm::FormMethods
-end
-
-Adhearsion::Components::Behavior::ClassMethods.module_eval do
-  include VoiceForm::MacroMethods
-end

data/lib/voice_form/form.rb

@@ -6,22 +6,18 @@ module VoiceForm
     attr_accessor :form_stack
     attr_reader :current_field
     
-    def initialize(options={})
+    def initialize(options={}, &block)
       @options = options
-      
       @form_stack = []
       @stack_index = 0
+      self.instance_eval(&block)
     end
     
     def run(component)
       @component = component
       
-      alias_call_context
-      
       add_field_accessors
-      
       run_setup
-      
       run_form_stack
     end
     
@@ -92,15 +88,6 @@ module VoiceForm
       slot.is_a?(VoiceForm::FormField)
     end
     
-    def alias_call_context
-      # hack to avoid setting the call_context in each field for different context name
-      if context_name = @options[:call_context] && !@component.respond_to?(:call_context)
-        @component.class_eval do
-          alias_method :call_context, context_name
-        end
-      end
-    end
-    
   end
   
 end

data/lib/voice_form/form_field.rb

@@ -4,11 +4,12 @@ module VoiceForm
     attr_reader :name
     attr_accessor :prompts
 
-    def initialize(name, options, component)
+    def initialize(name, options, component, &block)
       @name, @options, @component = name, options, component
       @options.reverse_merge!(:attempts => 5, :call_context => 'call_context')
       @callbacks = {}
       @prompts = []
+      self.instance_eval(&block)
     end
 
     def prompt(options)

data/lib/voice_form/form_methods.rb

@@ -16,7 +16,7 @@ module VoiceForm
         include InstanceMethods
     
         cattr_accessor :voice_form_options
-        attr_accessor :form
+        attr_accessor :form, :call_context
       end
 
       self.voice_form_options = [options, block]
@@ -26,10 +26,11 @@ module VoiceForm
 
   module InstanceMethods
   
-    def start_voice_form
+    def start_voice_form(call)
       raise "No voice form defined" unless self.voice_form_options
-      self.form = VoiceForm::Form.new(self.class.voice_form_options[0])
-      self.form.instance_eval(&self.class.voice_form_options[1])
+      options, block = *self.class.voice_form_options
+      @call_context = call
+      self.form = VoiceForm::Form.new(options, &block)
       self.form.run(self)
     end
 
@@ -39,12 +40,11 @@ module VoiceForm
     
     # Can be used in a form or stand-alone in a component method
     def field(field_name, options={}, &block)
-      raise 'Field require a block' unless block_given?
+      raise "A field requires a block" unless block_given?
       
-      form_field = VoiceForm::FormField.new(field_name, options, self)
+      form_field = VoiceForm::FormField.new(field_name, options, self, &block)
       
-      form_field.instance_eval(&block)
-      raise 'At least one prompt is required' if form_field.prompts.empty?
+      raise 'A field requires a prompt to be defined' if form_field.prompts.empty?
       
       if self.class == VoiceForm::Form
         self.form_stack << form_field

data/spec/form_field_spec.rb

@@ -267,9 +267,7 @@ describe VoiceForm::FormField do
 
   def form_field(field, options={}, &block)
     self.class.class_eval { attr_accessor field }
-    item = VoiceForm::FormField.new(field, {:attempts => 3}.merge(options), self )
-
-    item.instance_eval(&block)
+    item = VoiceForm::FormField.new(field, {:attempts => 3}.merge(options), self, &block)
     item
   end
 end

data/spec/form_spec.rb

@@ -16,7 +16,7 @@ describe VoiceForm::Form do
    
     self.class.voice_form &call_me
    
-    start_voice_form
+    start_voice_form(@call_context)
   end
 
   it "should call setup block" do
@@ -203,8 +203,8 @@ describe VoiceForm::Form do
 
   def new_voice_form
     self.class.voice_form { }
-    self.form = VoiceForm::Form.new(self.class.voice_form_options[0])
-    self.form.instance_eval(&self.class.voice_form_options[1])
+    options, block = *self.class.voice_form_options
+    self.form = VoiceForm::Form.new(options, &block)
   end
   
   def run_form

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: adzap-voice_form
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors: 
 - Adam Meehan
@@ -9,11 +9,11 @@ autorequire: voice_form
 bindir: bin
 cert_chain: []
 
-date: 2008-11-11 00:00:00 -08:00
+date: 2009-01-16 00:00:00 -08:00
 default_executable: 
 dependencies: []
 
-description: A DSL for Adhearsion to create forms in the style of the VoiceXML form element.
+description: A plugin for Adhearsion to create forms in the style of the VoiceXML form element.
 email: adam.meehan@gmail.com
 executables: []
 
@@ -27,10 +27,12 @@ files:
 - Rakefile
 - lib/voice_form.rb
 - lib/voice_form
+- lib/voice_form/simple_menu.rb
 - lib/voice_form/form.rb
 - lib/voice_form/form_field.rb
 - lib/voice_form/form_methods.rb
 - spec/form_field_spec.rb
+- spec/simple_menu_spec.rb
 - spec/spec_helper.rb
 - spec/form_spec.rb
 - examples/my_component.rb
@@ -60,6 +62,6 @@ rubyforge_project:
 rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
-summary: A DSL for Adhearsion to create forms in the style of the VoiceXML form element.
+summary: A plugin for Adhearsion to create forms in the style of the VoiceXML form element.
 test_files: []