This class encapsulates a form parsed out of an HTML page. Each type of input fields 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']
Character encoding of form data (i.e. UTF-8)
Content-Type for form data (i.e. application/x-www-form-urlencoded)
When true, character encoding errors will never be never raised on form submission. Default is false
# 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
Fetch the value set in the input field ‘name’
puts form['name']
# File lib/mechanize/form.rb, line 146 def [](field_name) f = field(field_name) f && f.value end
Set the value of the first input field with the name passed in
Set the value in the input field ‘name’ to “Aaron”
form['name'] = 'Aaron'
# File lib/mechanize/form.rb, line 155 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 103 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 206 def build_query(buttons = []) query = [] @mech.log.info("form encoding: #{encoding}") if @mech && @mech.log successful_controls = [] (fields + checkboxes).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 => %rwoo/).check
# File lib/mechanize/form.rb, line 382
Find all checkboxes that match criteria
Example:
form.checkboxes_with(:name => %rwoo/).each do |field| field.check end
# File lib/mechanize/form.rb, line 391 elements_with :checkbox, :checkboxes
Removes all fields with name field_name
.
# File lib/mechanize/form.rb, line 299 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 98 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 89 def dom_id form_node['id'] end
Find one field that matches criteria
Example:
form.field_with(:id => "exact_field_id").value = 'hello'
# File lib/mechanize/form.rb, line 310
Find all fields that match criteria
Example:
form.fields_with(:value => %rfoo/).each do |field| field.value = 'hello!' end
# File lib/mechanize/form.rb, line 319 elements_with :field
Find one file upload field that matches criteria
Example:
form.file_upload_with(:file_name => %rpicture/).value = 'foo'
# File lib/mechanize/form.rb, line 346
Find all file upload fields that match criteria
Example:
form.file_uploads_with(:file_name => %rpicutre/).each do |field| field.value = 'foo!' end
# File lib/mechanize/form.rb, line 355 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
# File lib/mechanize/form.rb, line 63 def has_value?(value) fields.find { |f| f.value == value } end
# File lib/mechanize/form.rb, line 76 def keygens ; @keygens ||= fields.select { |f| f.class == Keygen }; end
# File lib/mechanize/form.rb, line 67 def keys; fields.map { |f| f.name }; end
Treat form fields like accessors.
# File lib/mechanize/form.rb, line 165 def method_missing(meth, *args) method = meth.to_s.gsub(%r=$/, '') 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 274 def request_data query_params = build_query() case @enctype.downcase when %r^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
# File lib/mechanize/form.rb, line 72 def resets ; @resets ||= buttons.select { |f| f.class == Reset }; 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 121 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 this form with the button passed in
# File lib/mechanize/form.rb, line 177 def submit button=nil, headers = {} @mech.submit(self, button, headers) end
# File lib/mechanize/form.rb, line 71 def submits ; @submits ||= buttons.select { |f| f.class == Submit }; end
# File lib/mechanize/form.rb, line 80 def text_field?(field_name) texts.find{|f| f.name == field_name}; end
# File lib/mechanize/form.rb, line 82 def textarea_field?(field_name) textareas.find{|f| f.name == field_name}; end
# File lib/mechanize/form.rb, line 75 def textareas; @textareas ||= fields.select { |f| f.class == Textarea }; end
# File lib/mechanize/form.rb, line 73 def texts ; @texts ||= fields.select { |f| f.class == Text }; end
# File lib/mechanize/form.rb, line 69 def values; fields.map { |f| f.value }; end