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) 


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

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


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

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 



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

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.



291
292
293
294
 
# File 'lib/watir-classic/element.rb', line 291

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.



168
169
170
171
 
# File 'lib/watir-classic/element.rb', line 168

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.



253
254
255
256
 
# File 'lib/watir-classic/element.rb', line 253

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.



185
186
187
 
# File 'lib/watir-classic/element.rb', line 185

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.



246
247
248
249
 
# File 'lib/watir-classic/element.rb', line 246

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.



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

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"


209
210
211
 
# File 'lib/watir-classic/element.rb', line 209

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.



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

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.



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

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.



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

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

#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

#inner_html ⇒ String, ...

Retrieve element’s inner_html from the innerHTML OLE method.

Returns:

  • (String, Boolean, Fixnum) —

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

  • (String) —

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

See Also:



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

attr_ole :inner_html, :innerHTML

#inspect ⇒ Object 



69
70
71
 
# File 'lib/watir-classic/element.rb', line 69

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.



65
66
67
 
# File 'lib/watir-classic/element.rb', line 65

def ole_object
  @o
end

#outer_html ⇒ String, ... Also known as: html

Retrieve element’s outer_html from the outerHTML OLE method.

Returns:

  • (String, Boolean, Fixnum) —

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

  • (String) —

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

See Also:



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

attr_ole :outer_html, :outerHTML

#parent ⇒ Element

Retrieve the element immediately containing self.

Returns:

  • (Element) —

    parent element of self.

  • (Element) —

    self when parent element does not exist.



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

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.



177
178
179
 
# File 'lib/watir-classic/element.rb', line 177

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:



122
123
124
125
 
# File 'lib/watir-classic/element.rb', line 122

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.



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

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.



80
81
82
83
 
# File 'lib/watir-classic/element.rb', line 80

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.



148
149
150
151
 
# File 'lib/watir-classic/element.rb', line 148

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 



73
74
75
76
 
# File 'lib/watir-classic/element.rb', line 73

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.



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

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.



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

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