Class: Mechanize::Form

### Home Classes Methods

### In Files

- lib/mechanize/form.rb

### Parent

Object

### Namespace

- CLASS Mechanize::Form::Button
- CLASS Mechanize::Form::CheckBox
- CLASS Mechanize::Form::Field
- CLASS Mechanize::Form::FileUpload
- CLASS Mechanize::Form::Hidden
- CLASS Mechanize::Form::ImageButton
- CLASS Mechanize::Form::Keygen
- CLASS Mechanize::Form::MultiSelectList
- CLASS Mechanize::Form::Option
- CLASS Mechanize::Form::RadioButton
- CLASS Mechanize::Form::Reset
- CLASS Mechanize::Form::SelectList
- CLASS Mechanize::Form::Submit
- CLASS Mechanize::Form::Text
- CLASS Mechanize::Form::Textarea

### Methods

- ::new
- #[]
- #[]=
- #add_button_to_query
- #add_field!
- #build_query
- #button_with(criteria)
- #buttons_with(criteria)
- #checkbox_with(criteria)
- #checkboxes_with(criteria)
- #click_button
- #delete_field!
- #dom_class
- #dom_id
- #field_with(criteria)
- #fields_with(criteria)
- #file_upload_with(criteria)
- #file_uploads_with(criteria)
- #has_field?
- #has_key?
- #has_value?
- #hidden_field?
- #hiddens
- #keygens
- #keys
- #method_missing
- #radiobutton_with(criteria)
- #radiobuttons_with(criteria)
- #request_data
- #reset_button?
- #resets
- #save_hash_field_order
- #set_fields
- #submit
- #submit_button?
- #submits
- #text_field?
- #textarea_field?
- #textareas
- #texts
- #values

### Files

- EXAMPLES.rdoc
- GUIDE.rdoc
- LICENSE.rdoc
- Manifest.txt
- README.rdoc

### Class/Module Index

Quicksearch

- Mechanize
- Mechanize::ChunkedTerminationError
- Mechanize::ContentTypeError
- Mechanize::Cookie
- Mechanize::CookieCMethods
- Mechanize::CookieDeprecated
- Mechanize::CookieIMethods
- Mechanize::CookieJar
- Mechanize::CookieJarIMethods
- Mechanize::DirectorySaver
- Mechanize::Download
- Mechanize::ElementMatcher
- Mechanize::Error
- Mechanize::File
- Mechanize::FileConnection
- Mechanize::FileRequest
- Mechanize::FileResponse
- Mechanize::FileSaver
- Mechanize::Form
- Mechanize::Form::Button
- Mechanize::Form::CheckBox
- Mechanize::Form::Field
- Mechanize::Form::FileUpload
- Mechanize::Form::Hidden
- Mechanize::Form::ImageButton
- Mechanize::Form::Keygen
- Mechanize::Form::MultiSelectList
- Mechanize::Form::Option
- Mechanize::Form::RadioButton
- Mechanize::Form::Reset
- Mechanize::Form::SelectList
- Mechanize::Form::Submit
- Mechanize::Form::Text
- Mechanize::Form::Textarea
- Mechanize::HTTP
- Mechanize::HTTP::Agent
- Mechanize::HTTP::AuthChallenge
- Mechanize::HTTP::AuthRealm
- Mechanize::HTTP::AuthStore
- Mechanize::HTTP::ContentDispositionParser
- Mechanize::HTTP::WWWAuthenticateParser
- Mechanize::Headers
- Mechanize::History
- Mechanize::Image
- Mechanize::Page
- Mechanize::Page::Base
- Mechanize::Page::Frame
- Mechanize::Page::Image
- Mechanize::Page::Label
- Mechanize::Page::Link
- Mechanize::Page::MetaRefresh
- Mechanize::Parser
- Mechanize::PluggableParser
- Mechanize::Prependable
- Mechanize::RedirectLimitReachedError
- Mechanize::RedirectNotGetOrHeadError
- Mechanize::ResponseCodeError
- Mechanize::ResponseReadError
- Mechanize::RobotsDisallowedError
- Mechanize::TestCase
- Mechanize::UnauthorizedError
- Mechanize::UnsupportedSchemeError
- Mechanize::Util
- Mechanize::XmlFile
- HTTP
- HTTP::CookieJar

No matching classes.

# Mechanize::Form

This class encapsulates a form parsed out of an HTML page. Each type of input field available in a form can be accessed through this object.

## Examples

Find a form and print out its fields

    form = page.forms.first # => Mechanize::Form
    form.fields.each { |f| puts f.name }

Set the input field 'name' to "Aaron"

    form['name'] = 'Aaron'
    puts form['name']

### Attributes

action[RW]
buttons[R]
checkboxes[R]
elements[R]
encoding[RW]

Character encoding of form data (i.e. UTF-8)

enctype[RW]

Content-Type for form data (i.e. application/x-www-form-urlencoded)

fields[R]
file_uploads[R]
form_node[R]
ignore_encoding_error[RW]

When true, character encoding errors will never be never raised on form submission. Default is false

method[RW]
name[RW]
page[R]
radiobuttons[R]

### Public Class Methods

new(node, mech = nil, page = nil) click to toggle source

    # File lib/mechanize/form.rb, line 41
    def initialize(node, mech = nil, page = nil)
      @enctype = node['enctype'] || 'application/x-www-form-urlencoded'
      @form_node        = node
      @action           = Mechanize::Util.html_unescape(node['action'])
      @method           = (node['method'] || 'GET').upcase
      @name             = node['name']
      @clicked_buttons  = []
      @page             = page
      @mech             = mech

      @encoding = node['accept-charset'] || (page && page.encoding) || nil
      @ignore_encoding_error = false
      parse
    end

### Public Instance Methods

[](field_name) click to toggle source

Fetch the value of the first input field with the name passed in. Example:

    puts form['name']

    # File lib/mechanize/form.rb, line 192
    def [](field_name)
      f = field(field_name)
      f && f.value
    end

[]=(field_name, value) click to toggle source

Set the value of the first input field with the name passed in. Example:

    form['name'] = 'Aaron'

    # File lib/mechanize/form.rb, line 199
    def []=(field_name, value)
      f = field(field_name)
      if f
        f.value = value
      else
        add_field!(field_name, value)
      end
    end

add_button_to_query(button) click to toggle source

This method adds a button to the query. If the form needs to be submitted with multiple buttons, pass each button to this method.

    # File lib/mechanize/form.rb, line 321
    def add_button_to_query(button)
      unless button.node.document == @form_node.document then
        message =
          "#{button.inspect} does not belong to the same page as "          "the form #{@name.inspect} in #{@page.uri}"

        raise ArgumentError, message
      end

      @clicked_buttons << button
    end

add_field!(field_name, value = nil) click to toggle source

Add a field with `field_name` and `value`

    # File lib/mechanize/form.rb, line 152
    def add_field!(field_name, value = nil)
      fields << Field.new({'name' => field_name}, value)
    end

build_query(buttons = []) click to toggle source

This method builds an array of arrays that represent the query parameters to be used with this form. The return value can then be used to create a query string for this form.

    # File lib/mechanize/form.rb, line 251
    def build_query(buttons = [])
      query = []
      @mech.log.info("form encoding: #{encoding}") if @mech && @mech.log

      save_hash_field_order

      successful_controls = []

      (fields + checkboxes).reject do |f|
        f.node["disabled"]
      end.sort.each do |f|
        case f
        when Mechanize::Form::CheckBox
          if f.checked
            successful_controls << f
          end
        when Mechanize::Form::Field
          successful_controls << f
        end
      end

      radio_groups = {}
      radiobuttons.each do |f|
        fname = from_native_charset(f.name)
        radio_groups[fname] ||= []
        radio_groups[fname] << f
      end

      # take one radio button from each group
      radio_groups.each_value do |g|
        checked = g.select {|f| f.checked}

        if checked.uniq.size > 1 then
          values = checked.map { |button| button.value }.join(', ').inspect
          name = checked.first.name.inspect
          raise Mechanize::Error,
                "radiobuttons #{values} are checked in the #{name} group, "                "only one is allowed"
        else
          successful_controls << checked.first unless checked.empty?
        end
      end

      @clicked_buttons.each { |b|
        successful_controls << b
      }

      successful_controls.sort.each do |ctrl| # DOM order
        qval = proc_query(ctrl)
        query.push(*qval)
      end

      query
    end

button_with(criteria) click to toggle source

Find one button that matches `criteria` Example:

    form.button_with(:value => /submit/).value = 'hello'

    # File lib/mechanize/form.rb, line 390

buttons_with(criteria) click to toggle source

Find all buttons that match `criteria` Example:

    form.buttons_with(:value => /submit/).each do |button|
      button.value = 'hello!'
    end

    # File lib/mechanize/form.rb, line 399
    elements_with :button

checkbox_with(criteria) click to toggle source

Find one checkbox that matches `criteria` Example:

    form.checkbox_with(:name => /woo/).check

    # File lib/mechanize/form.rb, line 444

checkboxes_with(criteria) click to toggle source

Find all checkboxes that match `criteria` Example:

    form.checkboxes_with(:name => /woo/).each do |field|
      field.check
    end

    # File lib/mechanize/form.rb, line 453
    elements_with :checkbox,   :checkboxes

click_button(button = buttons.first) click to toggle source

Submit form using `button`. Defaults to the first button.

    # File lib/mechanize/form.rb, line 228
    def click_button(button = buttons.first)
      submit(button)
    end

delete_field!(field_name) click to toggle source

Removes all fields with name `field_name`.

    # File lib/mechanize/form.rb, line 361
    def delete_field!(field_name)
      @fields.delete_if{ |f| f.name == field_name}
    end

dom_class() click to toggle source

This method is a shortcut to get form's DOM class. Common usage:

    page.form_with(:dom_class => "foorm")

Note that you can also use `:class` to get to this method:

    page.form_with(:class => "foorm")

    # File lib/mechanize/form.rb, line 147
    def dom_class
      form_node['class']
    end

dom_id() click to toggle source

This method is a shortcut to get form's DOM id. Common usage:

    page.form_with(:dom_id => "foorm")

Note that you can also use `:id` to get to this method:

    page.form_with(:id => "foorm")

    # File lib/mechanize/form.rb, line 138
    def dom_id
      form_node['id']
    end

field_with(criteria) click to toggle source

Find one field that matches `criteria` Example:

    form.field_with(:id => "exact_field_id").value = 'hello'

    # File lib/mechanize/form.rb, line 372

fields_with(criteria) click to toggle source

Find all fields that match `criteria` Example:

    form.fields_with(:value => /foo/).each do |field|
      field.value = 'hello!'
    end

    # File lib/mechanize/form.rb, line 381
    elements_with :field

file_upload_with(criteria) click to toggle source

Find one file upload field that matches `criteria` Example:

    form.file_upload_with(:file_name => /picture/).value = 'foo'

    # File lib/mechanize/form.rb, line 408

file_uploads_with(criteria) click to toggle source

Find all file upload fields that match `criteria` Example:

    form.file_uploads_with(:file_name => /picutre/).each do |field|
      field.value = 'foo!'
    end

    # File lib/mechanize/form.rb, line 417
    elements_with :file_upload

has_field?(field_name) click to toggle source

Returns whether or not the form contains a field with `field_name`

    # File lib/mechanize/form.rb, line 57
    def has_field?(field_name)
      fields.find { |f| f.name == field_name }
    end

Also aliased as: has_key?
has_key?(field_name) click to toggle source
Alias for: has_field?
has_value?(value) click to toggle source

Returns whether or not the form contains a field with `value`

    # File lib/mechanize/form.rb, line 64
    def has_value?(value)
      fields.find { |f| f.value == value }
    end

hidden_field?(field_name) click to toggle source

Returns whether or not the form contains a Hidden field named `field_name`

    # File lib/mechanize/form.rb, line 124
    def hidden_field?(field_name)
      hiddens.find { |f| f.name == field_name }
    end

hiddens() click to toggle source

Returns all fields of type Hidden

    # File lib/mechanize/form.rb, line 94
    def hiddens
      @hiddens ||= fields.select { |f| f.class == Hidden }
    end

keygens() click to toggle source

Returns all fields of type Keygen

    # File lib/mechanize/form.rb, line 104
    def keygens
      @keygens ||= fields.select { |f| f.class == Keygen }
    end

keys() click to toggle source

Returns all field names (keys) for this form

    # File lib/mechanize/form.rb, line 69
    def keys
      fields.map { |f| f.name }
    end

method_missing(meth, *args) click to toggle source

Treat form fields like accessors.

    # File lib/mechanize/form.rb, line 209
    def method_missing(meth, *args)
      method = meth.to_s.gsub(/=$/, '')

      if field(method)
        return field(method).value if args.empty?
        return field(method).value = args[0]
      end

      super
    end

radiobutton_with(criteria) click to toggle source

Find one radio button that matches `criteria` Example:

    form.radiobutton_with(:name => /woo/).check

    # File lib/mechanize/form.rb, line 426

radiobuttons_with(criteria) click to toggle source

Find all radio buttons that match `criteria` Example:

    form.radiobuttons_with(:name => /woo/).each do |field|
      field.check
    end

    # File lib/mechanize/form.rb, line 435
    elements_with :radiobutton

request_data() click to toggle source

This method calculates the request data to be sent back to the server for this form, depending on if this is a regular post, get, or a multi-part post,

    # File lib/mechanize/form.rb, line 336
    def request_data
      query_params = build_query()

      case @enctype.downcase
      when /^multipart\/form-data/
        boundary = rand_string(20)
        @enctype = "multipart/form-data; boundary=#{boundary}"

        params = query_params.map do |k,v|
          param_to_multipart(k, v) if k
        end.compact

        params.concat @file_uploads.map { |f| file_to_multipart(f) }

        params.map do |part|
          part.force_encoding('ASCII-8BIT') if part.respond_to? :force_encoding
          "--#{boundary}\r\n#{part}"
        end.join('') +
          "--#{boundary}--\r\n"
      else
        Mechanize::Util.build_query_string(query_params)
      end
    end

reset_button?(button_name) click to toggle source

Returns whether or not the form contains a Reset button named `button_name`

    # File lib/mechanize/form.rb, line 114
    def reset_button?(button_name)
      resets.find { |f| f.name == button_name }
    end

resets() click to toggle source

Returns all buttons of type Reset

    # File lib/mechanize/form.rb, line 84
    def resets
      @resets ||= buttons.select { |f| f.class == Reset }
    end

save_hash_field_order() click to toggle source

This method adds an index to all fields that have Hash nodes. This enables field sorting to maintain order.

    # File lib/mechanize/form.rb, line 308
    def save_hash_field_order
      index = 0

      fields.each do |field|
        if Hash === field.node
          field.index = index
          index += 1
        end
      end
    end

set_fields(fields = {}) click to toggle source

This method sets multiple fields on the form. It takes a list of `fields` which are name, value pairs.

If there is more than one field found with the same name, this method will set the first one found. If you want to set the value of a duplicate field, use a value which is a Hash with the key as the index in to the form. The index is zero based.

For example, to set the second field named 'foo', you could do the following:

    form.set_fields :foo => { 1 => 'bar' }

    # File lib/mechanize/form.rb, line 169
    def set_fields fields = {}
      fields.each do |name, v|
        case v
        when Hash
          v.each do |index, value|
            self.fields_with(:name => name.to_s)[index].value = value
          end
        else
          value = nil
          index = 0

          [v].flatten.each do |val|
            index = val.to_i if value
            value = val unless value
          end

          self.fields_with(:name => name.to_s)[index].value = value
        end
      end
    end

submit(button = nil, headers = {}) click to toggle source

Submit the form. Does not include the `button` as a form parameter. Use `click_button` or provide button as a parameter.

    # File lib/mechanize/form.rb, line 222
    def submit button = nil, headers = {}
      @mech.submit(self, button, headers)
    end

submit_button?(button_name) click to toggle source

Returns whether or not the form contains a Submit button named `button_name`

    # File lib/mechanize/form.rb, line 109
    def submit_button?(button_name)
      submits.find { |f| f.name == button_name }
    end

submits() click to toggle source

Returns all buttons of type Submit

    # File lib/mechanize/form.rb, line 79
    def submits
      @submits ||= buttons.select { |f| f.class == Submit }
    end

text_field?(field_name) click to toggle source

Returns whether or not the form contains a Text field named `field_name`

    # File lib/mechanize/form.rb, line 119
    def text_field?(field_name)
      texts.find { |f| f.name == field_name }
    end

textarea_field?(field_name) click to toggle source

Returns whether or not the form contains a Textarea named `field_name`

    # File lib/mechanize/form.rb, line 129
    def textarea_field?(field_name)
      textareas.find { |f| f.name == field_name }
    end

textareas() click to toggle source

Returns all fields of type Textarea

    # File lib/mechanize/form.rb, line 99
    def textareas
      @textareas ||= fields.select { |f| f.class == Textarea }
    end

texts() click to toggle source

Returns all fields of type Text

    # File lib/mechanize/form.rb, line 89
    def texts
      @texts ||= fields.select { |f| f.class == Text }
    end

values() click to toggle source

Returns all field values for this form

    # File lib/mechanize/form.rb, line 74
    def values
      fields.map { |f| f.value }
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.