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


292
293
294
295
296
297
298
299
300
301
302
303
304
 
# File 'lib/watir-classic/element.rb', line 292

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 =~ /^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.



279
280
281
282
 
# File 'lib/watir-classic/element.rb', line 279

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.



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

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.



241
242
243
244
 
# File 'lib/watir-classic/element.rb', line 241

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.



173
174
175
 
# File 'lib/watir-classic/element.rb', line 173

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.



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

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.



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

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"


197
198
199
 
# File 'lib/watir-classic/element.rb', line 197

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.



180
181
182
183
184
185
186
187
188
189
 
# File 'lib/watir-classic/element.rb', line 180

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.



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

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.



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

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.



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

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.



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

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:



110
111
112
113
 
# File 'lib/watir-classic/element.rb', line 110

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.



120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/watir-classic/element.rb', line 120

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.



136
137
138
139
 
# File 'lib/watir-classic/element.rb', line 136

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
 
# File 'lib/watir-classic/element.rb', line 88

def to_subtype
  assert_exists

  tag = tag_name
  if tag == "html"
    element(:ole_object => ole_object)
  elsif tag == "input"
    send(ole_object.invoke('type'), :ole_object => ole_object)
  elsif tag == "select"
    select_list(:ole_object => ole_object)
  elsif respond_to?(tag.downcase)
    send(tag.downcase, :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.



250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/watir-classic/element.rb', line 250

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