Returns a form object with the passed in args, which can be a text selector, options and/or a possible block. All of which are optional.

When given a block the form object will be passed into the the block which can be used to set values on the form. The block will NOT submit the form. To submit the form you must call submit on ther returned form.

Options

 * xhr - can be true or false. This sets the type of request to be
         made when the form is submitted. default is false
 * :submit_value - a string. When selecting a form with multiple submit
         buttons this can be used to specify the value of which submit
         button to use.

Examples

  # select the first form
  form = select_form

  # select the form with the id 'form_id'
  form = select_form "form_id"

  # select form#form_id and tell it that it will make an xhr call
  form = select_form "form_id", :xhr => true

  # select form#form_id and
  form = select_form "form_id", :submit_value => "yes"

  # select the first form and tell it that it will make an xhr call
  form = select_form :xhr => true

  # accesing elements whose HTML names were in a basic format like "name"
  form.name = "joe"
  form.name  # => "joe"

  # accessing elements whose HTML names were in a format like "user[name]"
  form.user.name = "joe"
  form.user.name  # => "joe"

[Source]

    # File lib/form_methods.rb, line 44
44:     def select_form(*args)
45:       options = args.extract_options!
46:       text = args.first
47:       xhr = options.delete(:xhr)
48:       submit_value = options.delete(:submit_value)
49:       @html_document = nil # So it always grabs the latest response
50:     
51:       forms = if text.nil?
52:         select_first_form
53:       elsif submit_value.nil?
54:         select_form_with_id_or_action text
55:       else
56:         select_form_with_id_or_action_and_a_submit_value(text, submit_value)
57:       end
58:     
59:       returning Form.new(forms.first, self, :submit_value => submit_value, :xhr => xhr ) do |form|
60:         if block_given?
61:           yield form
62:         end
63:       end
64:     end

Alias for select_form when called with a block. Shortcut for select_form(name).submit(args) without block.

Example

  # selecting a form, setting a value for a field and submitting it
  submit_form "form_id" do |form|
    form.user.name = "joe"
  end

[Source]

    # File lib/form_methods.rb, line 74
74:     def submit_form(*args, &block)
75:       if block_given?
76:         select_form(*args, &block).submit
77:       else
78:         options = args.extract_options!
79:         selector = args.empty? ? nil : args
80:         
81:         submit_value = options.delete(:submit_value)
82:         xhr = options.delete(:xhr)
83:         
84:         select_form(selector, :xhr => xhr, :submit_value => submit_value).submit(options)
85:       end
86:     end