Object
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.
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']
# 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
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
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 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
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
Find one checkbox that matches criteria Example:
form.checkbox_with(:name => /woo/).check
# File lib/mechanize/form.rb, line 468
Find all checkboxes that match criteria Example:
form.checkboxes_with(:name => /woo/).each do |field| field.check end
# File lib/mechanize/form.rb, line 483 elements_with :checkbox, :checkboxes
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
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
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
Same as field_with but raises an ElementNotFoundError if no field matches criteria
# File lib/mechanize/form.rb, line 378
Find one field that matches criteria Example:
form.field_with(:id => "exact_field_id").value = 'hello'
# File lib/mechanize/form.rb, line 372
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 387 elements_with :field
Find one file upload field that matches criteria Example:
form.file_upload_with(:file_name => /picture/).value = 'foo'
# File lib/mechanize/form.rb, line 420
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 435 elements_with :file_upload
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
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
Returns all fields of type Keygen
# File lib/mechanize/form.rb, line 104 def keygens @keygens ||= fields.select { |f| f.class == Keygen } end
Returns all field names (keys) for this form
# File lib/mechanize/form.rb, line 69 def keys fields.map { |f| f.name } end
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
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
Returns all buttons of type Reset
# File lib/mechanize/form.rb, line 84 def resets @resets ||= buttons.select { |f| f.class == Reset } end
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
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 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
Returns all buttons of type Submit
# File lib/mechanize/form.rb, line 79 def submits @submits ||= buttons.select { |f| f.class == Submit } end
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
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
Returns all fields of type Textarea
# File lib/mechanize/form.rb, line 99 def textareas @textareas ||= fields.select { |f| f.class == Textarea } end
Returns all fields of type Text
# File lib/mechanize/form.rb, line 89 def texts @texts ||= fields.select { |f| f.class == Text } end
Generated with the Darkfish Rdoc Generator 2.