Class: Watir::Element

Inherits:
Object
  • Object
show all
Includes:
Comparable, Container, DragAndDropHelper, ElementExtensions, Exception
Defined in:
lib/watir-classic/element.rb

Overview

Base class for html elements. This is not a class that users would normally access.

Instance Attribute Summary collapse

Attributes included from Container

#page_container

Instance Method Summary collapse

Methods included from DragAndDropHelper

#drag_and_drop_by, #drag_and_drop_on

Methods included from Container

#a, #abbr, #address, #alert, #area, #article, #aside, #audio, #b, #base, #bdi, #bdo, #blockquote, #body, #br, #button, #canvas, #caption, #checkbox, #cite, #code, #col, #colgroup, #command, #data, #datalist, #dd, #del, #details, #dfn, #div, #dl, #dt, #element, #em, #embed, #fieldset, #figcaption, #figure, #file_field, #font, #footer, #form, #frame, #frameset, #h1, #h2, #h3, #h4, #h5, #h6, #head, #header, #hgroup, #hidden, #hr, #i, #img, #input, #ins, #kbd, #keygen, #label, #legend, #li, #map, #mark, #menu, #meta, #meter, #modal_dialog, #nav, #noscript, #object, #ol, #optgroup, #option, #output, #p, #param, #pre, #progress, #q, #radio, #rp, #rt, #ruby, #s, #samp, #script, #section, #select, #small, #source, #span, #strong, #sub, #summary, #sup, #table, #tbody, #td, #text_field, #textarea, #tfoot, #th, #thead, #time, #tr, #track, #u, #ul, #var, #video, #wbr

Methods included from Exception

message_for_unable_to_locate

Methods included from ElementExtensions

#present?, #wait_until_present, #wait_while_present, #when_present

Constructor Details

#initialize(container, specifiers) ⇒ Element

Returns a new instance of Element.

Raises:

  • (ArgumentError) 


45
46
47
48
49
50
51
 
# File 'lib/watir-classic/element.rb', line 45

def initialize(container, specifiers)
  set_container container
  raise ArgumentError, "#{specifiers.inspect} has to be Hash" unless specifiers.is_a?(Hash)

  @o = specifiers[:ole_object]
  @specifiers = specifiers
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method_name, *args, &block) ⇒ Object

Make it possible to use *_no_wait commands and retrieve element html5 data-attribute values.

Examples:

Use click without waiting:

browser.button.click_no_wait

Retrieve html5 data attribute value:

browser.div.data_model # => value of data-model="foo" html attribute


302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/watir-classic/element.rb', line 302

def method_missing(method_name, *args, &block)
  meth = method_name.to_s
  if meth =~ /(.*)_no_wait/ && self.respond_to?($1)
    perform_action do
      ruby_code = generate_ruby_code(self, $1, *args)
      system(spawned_no_wait_command(ruby_code))
    end
  elsif meth =~ /^(aria|data)_(.+)$/
    self.send(:attribute_value, meth.gsub("_", "-")) || ''
  else
    super
  end
end

Instance Attribute Details

#container ⇒ Object

Returns the value of attribute container.



11
12
13
 
# File 'lib/watir-classic/element.rb', line 11

def container
  @container
end

Instance Method Details

#<=>(other) ⇒ Object 



53
54
55
56
57
 
# File 'lib/watir-classic/element.rb', line 53

def <=> other
  assert_exists
  other.assert_exists
  ole_object.sourceindex <=> other.ole_object.sourceindex
end

#attribute_value(attribute_name) ⇒ String, Object

Get attribute value for any attribute of the element.

Returns:

  • (String) —

    the value of the attribute.

  • (Object) —

    nil if the attribute does not exist.



289
290
291
292
 
# File 'lib/watir-classic/element.rb', line 289

def attribute_value(attribute_name)
  assert_exists
  ole_object.getAttribute(attribute_name)
end

#class_name ⇒ String, ...

Retrieve element’s class_name from the className OLE method.

Returns:

  • (String, Boolean, Fixnum) —

    element’s “class_name” attribute value. Return type depends of the attribute type.

  • (String) —

    an empty String if the “class_name” attribute does not exist.

See Also:



37
 
# File 'lib/watir-classic/element.rb', line 37

attr_ole :class_name, :className

#click ⇒ Object

Performs a left click on the element. Will wait automatically until browser is ready after the click if page load was triggered for example.



166
167
168
169
 
# File 'lib/watir-classic/element.rb', line 166

def click
  click!
  @container.wait
end

#disabled? ⇒ Boolean

Returns true if the element is disabled, false otherwise.

Returns:

  • (Boolean) —

    true if the element is disabled, false otherwise.



251
252
253
254
 
# File 'lib/watir-classic/element.rb', line 251

def disabled?
  assert_exists
  false
end

#double_click ⇒ Object

Performs a double click on the element. Will wait automatically until browser is ready after the click if page load was triggered for example.



183
184
185
 
# File 'lib/watir-classic/element.rb', line 183

def double_click
  perform_action {fire_event("ondblclick"); @container.wait}
end

#enabled? ⇒ Boolean

Returns true if the element is enabled, false otherwise.

Returns:

  • (Boolean) —

    true if the element is enabled, false otherwise.



244
245
246
247
 
# File 'lib/watir-classic/element.rb', line 244

def enabled?
  assert_exists
  !disabled?
end

#exists? ⇒ Boolean Also known as: exist?

Returns true when element exists, false otherwise.

Returns:

  • (Boolean) —

    true when element exists, false otherwise.



231
232
233
234
235
236
237
238
 
# File 'lib/watir-classic/element.rb', line 231

def exists?
  begin
    locate
  rescue WIN32OLERuntimeError, UnknownObjectException
    @o = nil
  end
  !!@o
end

#fire_event(event) ⇒ Object

Executes a user defined “fireEvent” for element with JavaScript events.

Examples:

Fire a onchange event on select_list:

browser.select_list.fire_event "onchange"


207
208
209
 
# File 'lib/watir-classic/element.rb', line 207

def fire_event(event)
  perform_action {dispatch_event(event); @container.wait}
end

#flash(number = 10) ⇒ Object

Flash the element the specified number of times for troubleshooting purposes.

Parameters:

  • number (Fixnum) (defaults to: 10) —

    Number times to flash the element.



190
191
192
193
194
195
196
197
198
199
 
# File 'lib/watir-classic/element.rb', line 190

def flash(number=10)
  assert_exists
  number.times do
    set_highlight
    sleep 0.05
    clear_highlight
    sleep 0.05
  end
  self
end

#focus ⇒ Object

Set focus on the element.



214
215
216
217
218
219
 
# File 'lib/watir-classic/element.rb', line 214

def focus
  assert_exists
  assert_enabled
  @container.focus
  ole_object.focus(0)
end

#focused? ⇒ Boolean

Returns true when element is in focus, false otherwise.

Returns:

  • (Boolean) —

    true when element is in focus, false otherwise.



224
225
226
227
228
 
# File 'lib/watir-classic/element.rb', line 224

def focused?
  assert_exists
  assert_enabled
  @page_container.document.activeElement.uniqueNumber == unique_number
end

#html ⇒ String, ...

Retrieve element’s html from the outerHTML OLE method.

Returns:

  • (String, Boolean, Fixnum) —

    element’s “html” attribute value. Return type depends of the attribute type.

  • (String) —

    an empty String if the “html” attribute does not exist.

See Also:



39
 
# File 'lib/watir-classic/element.rb', line 39

attr_ole :html, :outerHTML

#id ⇒ String, ...

Retrieve element’s id from the OLE method.

Returns:

  • (String, Boolean, Fixnum) —

    element’s “id” attribute value. Return type depends of the attribute type.

  • (String) —

    an empty String if the “id” attribute does not exist.

See Also:



35
 
# File 'lib/watir-classic/element.rb', line 35

attr_ole :id

#inspect ⇒ Object 



67
68
69
 
# File 'lib/watir-classic/element.rb', line 67

def inspect
  '#<%s:0x%x located=%s specifiers=%s>' % [self.class, hash*2, !!ole_object, @specifiers.inspect]
end

#ole_object ⇒ WIN32OLE

Returns OLE object of the element, allowing any methods of the DOM that Watir doesn’t support to be used.

Returns:

  • (WIN32OLE) —

    OLE object of the element, allowing any methods of the DOM that Watir doesn’t support to be used.



63
64
65
 
# File 'lib/watir-classic/element.rb', line 63

def ole_object
  @o
end

#parent ⇒ Element

Retrieve the element immediately containing self.

Returns:

  • (Element) —

    parent element of self.

  • (Element) —

    self when parent element does not exist.



155
156
157
158
159
160
 
# File 'lib/watir-classic/element.rb', line 155

def parent
  assert_exists
  parent_element = ole_object.parentelement
  return unless parent_element
  Element.new(self, :ole_object => parent_element).to_subtype
end

#right_click ⇒ Object

Performs a right click on the element. Will wait automatically until browser is ready after the click if page load was triggered for example.



175
176
177
 
# File 'lib/watir-classic/element.rb', line 175

def right_click
  perform_action {fire_event("oncontextmenu"); @container.wait}
end

#send_keys(*keys) ⇒ Object

Send keys to the element

Examples:

browser.text_field.send_keys "hello", [:control, "a"], :backspace

Parameters:

  • keys (String, Array<Symbol, String>, Symbol) —

    Keys to send to the element.

See Also:



120
121
122
123
 
# File 'lib/watir-classic/element.rb', line 120

def send_keys(*keys)
  focus
  page_container.send_keys *keys
end

#style(property = nil) ⇒ String

Retrieve element’s css style.

Parameters:

  • property (String) (defaults to: nil) —

    When property is specified then only css for that property is returned.

Returns:

  • (String) —

    css style as a one long String.

  • (String) —

    css style for specified property if property parameter is specified.



130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/watir-classic/element.rb', line 130

def style(property=nil)
  assert_exists
  css = ole_object.style.cssText

  if property
    properties = Hash[css.downcase.split(";").map { |p| p.split(":").map(&:strip) }]
    properties[property]
  else
    css
  end
end

#tag_name ⇒ String

Returns element’s html tag name in downcase.

Returns:

  • (String) —

    element’s html tag name in downcase.



78
79
80
81
 
# File 'lib/watir-classic/element.rb', line 78

def tag_name
  assert_exists
  @o.tagName.downcase
end

#text ⇒ String

The text value of the element between html tags.

Returns:

  • (String) —

    element’s text.

  • (String) —

    empty String when element is not visible.



146
147
148
149
 
# File 'lib/watir-classic/element.rb', line 146

def text
  assert_exists
  visible? ? ole_object.innerText.strip : ""
end

#title ⇒ String, ...

Retrieve element’s title from the OLE method.

Returns:

  • (String, Boolean, Fixnum) —

    element’s “title” attribute value. Return type depends of the attribute type.

  • (String) —

    an empty String if the “title” attribute does not exist.

See Also:



36
 
# File 'lib/watir-classic/element.rb', line 36

attr_ole :title

#to_s ⇒ Object 



71
72
73
74
 
# File 'lib/watir-classic/element.rb', line 71

def to_s
  assert_exists
  string_creator.join("\n")
end

#to_subtype ⇒ Element

Cast Watir::Element into specific subclass.

Examples:

Convert div element to Div class:

browser.element(:tag_name => "div").to_subtype # => Watir::Div

Returns:

  • (Element) —

    element casted into specific sub-class of Element.



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/watir-classic/element.rb', line 88

def to_subtype
  assert_exists

  tag = tag_name.downcase
  if tag == "html"
    element(:ole_object => ole_object)
  elsif tag == "input"
    input_type = case ole_object.invoke("type")
      when *%w[button reset submit image]
        "button"
      when "checkbox"
        "checkbox"
      when "radio"
        "radio"
      when "file"
        "file_field"
      else
        "text_field"
      end
      send(input_type, :ole_object => ole_object)
  elsif respond_to?(tag)
    send(tag, :ole_object => ole_object)
  else
    self
  end
end

#unique_number ⇒ String, ...

Retrieve element’s unique_number from the uniqueNumber OLE method.

Returns:

  • (String, Boolean, Fixnum) —

    element’s “unique_number” attribute value. Return type depends of the attribute type.

  • (String) —

    an empty String if the “unique_number” attribute does not exist.

See Also:



38
 
# File 'lib/watir-classic/element.rb', line 38

attr_ole :unique_number, :uniqueNumber

#visible? ⇒ Boolean

Retrieve the status of element’s visibility. When any parent element is not also visible then the current element is determined as not visible too.

Returns:

  • (Boolean) —

    true if element is visible, false otherwise.



260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/watir-classic/element.rb', line 260

def visible?
  # Now iterate up the DOM element tree and return false if any
  # parent element isn't visible
  assert_exists
  visible_child = false
  object = @o
  while object
    begin
      visibility = object.currentstyle.invoke('visibility')
      if visibility =~ /^visible$/i
        visible_child = true
      elsif !visible_child && visibility =~ /^hidden$/i
        return false
      end

      if object.currentstyle.invoke('display') =~ /^none$/i
        return false
      end
    rescue WIN32OLERuntimeError
    end
    object = object.parentElement
  end
  true
end