Class: Mechanize::Form

Inherits:
Object
  • Object
show all
Extended by:
ElementMatcher
Defined in:
lib/mechanize/form.rb

Overview

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']

Defined Under Namespace

Classes: Button, CheckBox, Field, FileUpload, Hidden, ImageButton, Keygen, MultiSelectList, Option, RadioButton, Reset, SelectList, Submit, Text, Textarea

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from ElementMatcher

elements_with

Constructor Details

#initialize(node, mech = nil, page = nil) ⇒ Form

Returns a new instance of Form.



41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# 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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(meth, *args) ⇒ Object

Treat form fields like accessors.



209
210
211
212
213
214
215
216
217
218
 
# 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

Instance Attribute Details

#action ⇒ Object

Returns the value of attribute action.



22
23
24
 
# File 'lib/mechanize/form.rb', line 22

def action
  @action
end

#buttons ⇒ Object (readonly)

Returns the value of attribute buttons.



24
25
26
 
# File 'lib/mechanize/form.rb', line 24

def buttons
  @buttons
end

#checkboxes ⇒ Object (readonly)

Returns the value of attribute checkboxes.



24
25
26
 
# File 'lib/mechanize/form.rb', line 24

def checkboxes
  @checkboxes
end

#encoding ⇒ Object

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



30
31
32
 
# File 'lib/mechanize/form.rb', line 30

def encoding
  @encoding
end

#enctype ⇒ Object

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



27
28
29
 
# File 'lib/mechanize/form.rb', line 27

def enctype
  @enctype
end

#fields ⇒ Object (readonly) Also known as: elements

Returns the value of attribute fields.



24
25
26
 
# File 'lib/mechanize/form.rb', line 24

def fields
  @fields
end

#file_uploads ⇒ Object (readonly)

Returns the value of attribute file_uploads.



24
25
26
 
# File 'lib/mechanize/form.rb', line 24

def file_uploads
  @file_uploads
end

#form_node ⇒ Object (readonly)

Returns the value of attribute form_node.



38
39
40
 
# File 'lib/mechanize/form.rb', line 38

def form_node
  @form_node
end

#ignore_encoding_error ⇒ Object

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



34
35
36
 
# File 'lib/mechanize/form.rb', line 34

def ignore_encoding_error
  @ignore_encoding_error
end

#method ⇒ Object

Returns the value of attribute method.



22
23
24
 
# File 'lib/mechanize/form.rb', line 22

def method
  @method
end

#name ⇒ Object

Returns the value of attribute name.



22
23
24
 
# File 'lib/mechanize/form.rb', line 22

def name
  @name
end

#page ⇒ Object (readonly)

Returns the value of attribute page.



39
40
41
 
# File 'lib/mechanize/form.rb', line 39

def page
  @page
end

#radiobuttons ⇒ Object (readonly)

Returns the value of attribute radiobuttons.



24
25
26
 
# File 'lib/mechanize/form.rb', line 24

def radiobuttons
  @radiobuttons
end

Instance Method Details

#[](field_name) ⇒ Object

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

puts form['name']



192
193
194
195
 
# File 'lib/mechanize/form.rb', line 192

def [](field_name)
  f = field(field_name)
  f && f.value
end

#[]=(field_name, value) ⇒ Object

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

form['name'] = 'Aaron'



199
200
201
202
203
204
205
206
 
# 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) ⇒ Object

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



321
322
323
324
325
326
327
328
329
330
331
 
# 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) ⇒ Object

Add a field with field_name and value



152
153
154
 
# 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 = []) ⇒ Object

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.



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
 
# 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 ⇒ Object

:method: buttons_with(criteria)

Find all buttons that match criteria Example:

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



417
 
# File 'lib/mechanize/form.rb', line 417

elements_with :button

#checkbox ⇒ Object

:method: checkboxes_with(criteria)

Find all checkboxes that match criteria Example:

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



489
 
# File 'lib/mechanize/form.rb', line 489

elements_with :checkbox,   :checkboxes

#click_button(button = buttons.first) ⇒ Object

Submit form using button. Defaults to the first button.



228
229
230
 
# File 'lib/mechanize/form.rb', line 228

def click_button(button = buttons.first)
  submit(button)
end

#delete_field!(field_name) ⇒ Object

Removes all fields with name field_name.



367
368
369
 
# File 'lib/mechanize/form.rb', line 367

def delete_field!(field_name)
  @fields.delete_if{ |f| f.name == field_name}
end

#dom_class ⇒ Object

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")



147
148
149
 
# File 'lib/mechanize/form.rb', line 147

def dom_class
  form_node['class']
end

#dom_id ⇒ Object

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")



138
139
140
 
# File 'lib/mechanize/form.rb', line 138

def dom_id
  form_node['id']
end

#field ⇒ Object

:method: fields_with(criteria)

Find all fields that match criteria Example:

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



393
 
# File 'lib/mechanize/form.rb', line 393

elements_with :field

#file_upload ⇒ Object

:method: file_uploads_with(criteria)

Find all file upload fields that match criteria Example:

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



441
 
# File 'lib/mechanize/form.rb', line 441

elements_with :file_upload

#has_field?(field_name) ⇒ Boolean Also known as: has_key?

Returns whether or not the form contains a field with field_name

Returns:

  • (Boolean) 


57
58
59
 
# File 'lib/mechanize/form.rb', line 57

def has_field?(field_name)
  fields.find { |f| f.name == field_name }
end

#has_value?(value) ⇒ Boolean

Returns whether or not the form contains a field with value

Returns:

  • (Boolean) 


64
65
66
 
# File 'lib/mechanize/form.rb', line 64

def has_value?(value)
  fields.find { |f| f.value == value }
end

#hidden_field?(field_name) ⇒ Boolean

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

Returns:

  • (Boolean) 


124
125
126
 
# File 'lib/mechanize/form.rb', line 124

def hidden_field?(field_name)
  hiddens.find { |f| f.name == field_name }
end

#hiddens ⇒ Object

Returns all fields of type Hidden



94
95
96
 
# File 'lib/mechanize/form.rb', line 94

def hiddens
  @hiddens ||= fields.select { |f| f.class == Hidden }
end

#keygens ⇒ Object

Returns all fields of type Keygen



104
105
106
 
# File 'lib/mechanize/form.rb', line 104

def keygens
  @keygens ||= fields.select { |f| f.class == Keygen }
end

#keys ⇒ Object

Returns all field names (keys) for this form



69
70
71
 
# File 'lib/mechanize/form.rb', line 69

def keys
  fields.map { |f| f.name }
end

#pretty_print(q) ⇒ Object

:nodoc:



491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
 
# File 'lib/mechanize/form.rb', line 491

def pretty_print(q) # :nodoc:
  q.object_group(self) {
    q.breakable; q.group(1, '{name', '}') { q.breakable; q.pp name }
    q.breakable; q.group(1, '{method', '}') { q.breakable; q.pp method }
    q.breakable; q.group(1, '{action', '}') { q.breakable; q.pp action }
    q.breakable; q.group(1, '{fields', '}') {
      fields.each do |field|
        q.breakable
        q.pp field
      end
    }
    q.breakable; q.group(1, '{radiobuttons', '}') {
      radiobuttons.each { |b| q.breakable; q.pp b }
    }
    q.breakable; q.group(1, '{checkboxes', '}') {
      checkboxes.each { |b| q.breakable; q.pp b }
    }
    q.breakable; q.group(1, '{file_uploads', '}') {
      file_uploads.each { |b| q.breakable; q.pp b }
    }
    q.breakable; q.group(1, '{buttons', '}') {
      buttons.each { |b| q.breakable; q.pp b }
    }
  }
end

#radiobutton ⇒ Object

:method: radiobuttons_with(criteria)

Find all radio buttons that match criteria Example:

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



465
 
# File 'lib/mechanize/form.rb', line 465

elements_with :radiobutton

#request_data ⇒ Object

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,



343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/mechanize/form.rb', line 343

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|
      "--#{boundary}\r\n#{part.force_encoding(Encoding::ASCII_8BIT)}"
    end.join('') +
      "--#{boundary}--\r\n"
  else
    Mechanize::Util.build_query_string(query_params)
  end
end

#reset ⇒ Object

This method allows the same form to be submitted second time with the different submit button being clicked.



335
336
337
338
 
# File 'lib/mechanize/form.rb', line 335

def reset
  # In the future, should add more functionality here to reset the form values to their defaults.
  @clicked_buttons = []
end

#reset_button?(button_name) ⇒ Boolean

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

Returns:

  • (Boolean) 


114
115
116
 
# File 'lib/mechanize/form.rb', line 114

def reset_button?(button_name)
  resets.find { |f| f.name == button_name }
end

#resets ⇒ Object

Returns all buttons of type Reset



84
85
86
 
# File 'lib/mechanize/form.rb', line 84

def resets
  @resets ||= buttons.select { |f| f.class == Reset }
end

#save_hash_field_order ⇒ Object

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



308
309
310
311
312
313
314
315
316
317
 
# 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 = {}) ⇒ Object

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' }



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# 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 = {}) ⇒ Object

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



222
223
224
 
# File 'lib/mechanize/form.rb', line 222

def submit button = nil, headers = {}
  @mech.submit(self, button, headers)
end

#submit_button?(button_name) ⇒ Boolean

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

Returns:

  • (Boolean) 


109
110
111
 
# File 'lib/mechanize/form.rb', line 109

def submit_button?(button_name)
  submits.find { |f| f.name == button_name }
end

#submits ⇒ Object

Returns all buttons of type Submit



79
80
81
 
# File 'lib/mechanize/form.rb', line 79

def submits
  @submits ||= buttons.select { |f| f.class == Submit }
end

#text_field?(field_name) ⇒ Boolean

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

Returns:

  • (Boolean) 


119
120
121
 
# File 'lib/mechanize/form.rb', line 119

def text_field?(field_name)
  texts.find { |f| f.name == field_name }
end

#textarea_field?(field_name) ⇒ Boolean

Returns whether or not the form contains a Textarea named field_name

Returns:

  • (Boolean) 


129
130
131
 
# File 'lib/mechanize/form.rb', line 129

def textarea_field?(field_name)
  textareas.find { |f| f.name == field_name }
end

#textareas ⇒ Object

Returns all fields of type Textarea



99
100
101
 
# File 'lib/mechanize/form.rb', line 99

def textareas
  @textareas ||= fields.select { |f| f.class == Textarea }
end

#texts ⇒ Object

Returns all fields of type Text



89
90
91
 
# File 'lib/mechanize/form.rb', line 89

def texts
  @texts ||= fields.select { |f| f.class == Text }
end

#values ⇒ Object

Returns all field values for this form



74
75
76
 
# File 'lib/mechanize/form.rb', line 74

def values
  fields.map { |f| f.value }
end