Module: Document

Extended by:
Situated::Viewport
Defined in:
lib/source/redshift/document.rb

Overview

The Document object enables access to top-level HTML elements like <head>, <html>, and <body>.

Document also provides “DOM-ready” functionality with Document.ready? and element-finding functionality through the powerful Document.[] method.

Class Method Summary collapse

Methods included from Situated::Viewport

coordinates, position, scroll, scroll_size, size

Methods included from Situated::PositionAndSize

#height, #left, #scroll_height, #scroll_left, #scroll_top, #scroll_width, #top, #width

Class Method Details

.[](*args) ⇒ Object

call-seq:

Document["#id"]      -> element or nil
Document["selector"] -> [element, ...]
Document[str, ...]   -> [element, ...]

The first form returns the Element identified by the id str (e.g. ‘#my_id’), or nil if no such element is found. The second form returns the array of elements identified by the selector str. The third form returns the array of elements found by calling Document.[] on each arg. The fourth form returns element unchanged.

The first form returns the Element identified by the string “#id”, or nil if no such element is found.

Document['#content']    #=> #<Element: DIV id="content">

The second form returns the array of Element objects that match the string “selector”, which takes the format of a CSS3 selector. See www.w3.org/TR/css3-selectors/ for details.

Available Selectors Document in its second form takes a selector string and scans the document returing an array of any elements that match the selector string.

The selectors string takes the format of a CSS3 selector: www.w3.org/TR/css3-selectors/

Class Selector Returns an array of elements that have the specified class name Document #=> [#<Element: DIV class=“my_class”>, #<Element: DIV class=“my_class”>, #<Element: SPAN class=“my_class”>]

Tag Selector Returns an array of elements that have the specified tag Document #=> [#<Element: A href=“/foo/bar”>, #<Element: A href=“/foo/baz”>, #<Element: A href=“/foo/bat”>]



54
55
56
57
58
59
60
61
62
63
 
# File 'lib/source/redshift/document.rb', line 54

def self.[](*args)
  if args.length == 1
    return self.find_by_string(args[0])
  else
    args.map do |str|
      Document[str]
    end.compact
    #return self.find_many_with_array(args.unshift(obj))
  end
end

.body ⇒ Object

call-seq:

Document.body -> element

Returns the <body> element of the current page.

Document.body   #=> #<Element: BODY>



72
73
74
 
# File 'lib/source/redshift/document.rb', line 72

def self.body
  `$E(document.body)`
end

.document ⇒ Object

:nodoc



213
214
215
 
# File 'lib/source/redshift/document.rb', line 213

def self.document # :nodoc
  self
end

.execute_js(str) ⇒ Object

call-seq:

Document.execute_js(str) -> str

Executes str as JavaScript, then returns str.



81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/source/redshift/document.rb', line 81

def self.execute_js(str)
  return str if str == ''
  if `window.execScript`
    `window.execScript(str.__value__)`
  else
    `scriptElement = document.createElement('script')`
    `scriptElement.setAttribute('type','text/javascript')`
    `scriptElement.text = str`
    `document.head.appendChild(scriptElement)`
    `document.head.removeChild(scriptElement)`
  end
  return str
end

.find_all_by_selector(selector) ⇒ Object

Uses the Selector library to find native elements and retrun an array of extended elements



149
150
151
 
# File 'lib/source/redshift/document.rb', line 149

def self.find_all_by_selector(selector) # :nodoc:
  `Array.fromCollection(Selectors.Utils.search(document, selector.__value__, {}));`
end

.find_by_id(str) ⇒ Object

Uses the browser’s native getElementById to find an element. Returns an extended element.



154
155
156
 
# File 'lib/source/redshift/document.rb', line 154

def self.find_by_id(str) # :nodoc:
  `$E(document.getElementById(str.__value__))`
end

.find_by_string(str) ⇒ Object

Finds an element from a provided string. If the string is a represents a single id (‘#my_id’) calls self.find_all_by_id, otherwise calls self.find_all_by_selector



160
161
162
 
# File 'lib/source/redshift/document.rb', line 160

def self.find_by_string(str) # :nodoc:
  `str.__value__.match(/^#[a-zA-z_]*$/)` ? self.find_by_id(`$q(str.__value__.replace('#',''))`) : self.find_all_by_selector(str)
end

.find_many_with_array(ary) ⇒ Object

:nodoc:



164
165
166
167
 
# File 'lib/source/redshift/document.rb', line 164

def self.find_many_with_array(ary) # :nodoc:
  `for(var i=0,l=ary.length,result=[];i<l;++i){var el=#{Document[`ary[i]`]};if($T(el)){result.push(el);};}`
  return `result`.flatten
end

.head ⇒ Object

call-seq:

Document.head -> element

Returns the <head> element of the current page.

Document.head   #=> #<Element: HEAD>



102
103
104
 
# File 'lib/source/redshift/document.rb', line 102

def self.head
  `$E(document.head)`
end

.html ⇒ Object

call-seq:

Document.html -> element

Returns the <html> element of the current page.

Document.html   #=> #<Element: HTML>



113
114
115
 
# File 'lib/source/redshift/document.rb', line 113

def self.html
  `$E(document.html)`
end

.ready?(&block) ⇒ Boolean

call-seq:

Document.ready? { block } -> nil

When the DOM is finished loading, executes the given block, then returns nil.

Document.ready? do
  puts self.title
end

produces:

"RDoc Documentation"

Returns:

  • (Boolean) 


131
132
133
134
135
 
# File 'lib/source/redshift/document.rb', line 131

def self.ready?(&block)
  @proc = block
  `document.addEventListener('DOMContentLoaded', function(){document.__loaded__=true;#{@proc.call};}.m$(this), false)`
  return nil
end

.title ⇒ Object

call-seq:

Document.title -> string

Returns the title of the current page.

Document.title    #=> "RDoc Documentation"



144
145
146
 
# File 'lib/source/redshift/document.rb', line 144

def self.title
  `$q(document.title)`
end

.walk(element, path, startRelation, matchSelector, all) ⇒ Object

Walks the DOM from a particular element. The first step it talks in the walk with either be the specified start_relation or the specified path. If ‘all’ is set to false, the walk will termiante and return the single element. Otherwise, it will continue the walk until it has reached the end of the specified path. The walk will then termiante and return an array of all elements on the path.

if an optional <tt>match_selector<tt> is provided, only element(s) that match the selector can be returned

Examples: Document.walk(my_element, ‘parentNode’, nil, nil, false) will go down the parentNode path of my_element, starting at the my_element, and return just a single element

Document.walk(my_element, ‘parentNode’, nil, nil, true) will go down the parentNode path of my_element, starting at my_element, and return an array of all elements on the parentNode path

Document.walk(my_element, ‘nextSibling’, ‘firstChild’, nil, true) will go down the nextSibling path of my_element, starting at my_element’s firstChild and return an array of all elements on the nextSibling path from that starting point.

Document.walk(my_element, ‘nextSibling’, ‘firstChild’, ‘.my_class’, true) will go down the nextSibling path of my_element, starting at my_element’s firstChild and return an array of all elements on the nextSibling path from that starting point that have the class ‘my_class’



196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/source/redshift/document.rb', line 196

def self.walk(element, path, startRelation, matchSelector, all) # :nodoc
  `if(startRelation){startRelation = startRelation.__value__;};
  var el = element.__native__[startRelation || path.__value__],elements = [];
  while (el){
    if (el.nodeType == 1 && (#{!matchSelector} || Element.match(el, #{matchSelector}))){
      if (!all) {return $E(el);}
      elements.push($E(el));
    }
    el = el[path.__value__];
  }`
  return `(all) ? elements : nil`
end

.window ⇒ Object

:nodoc:



209
210
211
 
# File 'lib/source/redshift/document.rb', line 209

def self.window # :nodoc:
  Window
end