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



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

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>



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

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

.document ⇒ Object

:nodoc



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

def self.document # :nodoc
  self
end

.execute_js(str) ⇒ Object

call-seq:

Document.execute_js(str) -> str

Executes str as JavaScript, then returns str.



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

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



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

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.



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

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



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

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:



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

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>



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

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>



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

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) 


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

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"



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

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’



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

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:



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

def self.window # :nodoc:
  Window
end