Class: Ferrum::Frame

Inherits:
Object
  • Object
show all
Includes:
DOM, Runtime
Defined in:
lib/ferrum/frame.rb,
lib/ferrum/frame/dom.rb,
lib/ferrum/frame/runtime.rb

Defined Under Namespace

Modules: DOM, Runtime

Constant Summary collapse

STATE_VALUES = 
i[
  started_loading
  navigated
  stopped_loading
].freeze

Constants included from Runtime

Runtime::INTERMITTENT_ATTEMPTS, Runtime::INTERMITTENT_SLEEP

Constants included from DOM

DOM::LINK_TAG, DOM::SCRIPT_SRC_TAG, DOM::SCRIPT_TEXT_TAG, DOM::STYLE_TAG

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Runtime

#evaluate, #evaluate_async, #evaluate_func, #evaluate_on, #execute

Methods included from DOM

#add_script_tag, #add_style_tag, #at_css, #at_xpath, #body, #css, #current_title, #current_url, #doctype, #frame_element, #xpath

Constructor Details

#initialize(id, page, parent_id = nil) ⇒ Frame

Returns a new instance of Frame.



42
43
44
45
46
47
 
# File 'lib/ferrum/frame.rb', line 42

def initialize(id, page, parent_id = nil)
  @id = id
  @page = page
  @parent_id = parent_id
  @execution_id = Concurrent::MVar.new
end

Instance Attribute Details

#id ⇒ String

The Frame’s unique id.

Returns:

  • (String) 


20
21
22
 
# File 'lib/ferrum/frame.rb', line 20

def id
  @id
end

#name ⇒ String?

If frame was given a name it should be here.

Returns:

  • (String, nil) 


25
26
27
 
# File 'lib/ferrum/frame.rb', line 25

def name
  @name
end

#page ⇒ Page (readonly)

The page the frame belongs to.

Returns:



30
31
32
 
# File 'lib/ferrum/frame.rb', line 30

def page
  @page
end

#parent_id ⇒ String? (readonly)

Parent frame id if this one is nested in another one.

Returns:

  • (String, nil) 


35
36
37
 
# File 'lib/ferrum/frame.rb', line 35

def parent_id
  @parent_id
end

#state ⇒ :started_loading, ...

One of the states frame’s in.

Returns:

  • (:started_loading, :navigated, :stopped_loading, nil) 


40
41
42
 
# File 'lib/ferrum/frame.rb', line 40

def state
  @state
end

Instance Method Details

#content=(html) ⇒ Object Also known as: set_content

Sets a content of a given frame.

Examples:

browser.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
frame = browser.frames[1]
frame.body # <html lang="en"><head><style>body {transition: opacity ease-in 0.2s; }...
frame.content = "<html><head></head><body><p>lol</p></body></html>"
frame.body # => <html><head></head><body><p>lol</p></body></html>

Parameters:

  • html (String) 


126
127
128
129
130
131
132
133
134
 
# File 'lib/ferrum/frame.rb', line 126

def content=(html)
  evaluate_async(%(
    document.open();
    document.write(arguments[0]);
    document.close();
    arguments[1](true);
  ), @page.timeout, html)
  @page.document_node_id
end

#execution_id ⇒ Integer?

Execution context id which is used by JS, each frame has it’s own context in which JS evaluates.

Returns:

  • (Integer, nil) 


160
161
162
163
164
165
 
# File 'lib/ferrum/frame.rb', line 160

def execution_id
  value = @execution_id.value
  return if value.instance_of?(Object)

  value
end

#execution_id! ⇒ Integer

Execution context id which is used by JS, each frame has it’s own context in which JS evaluates. Locks for a page timeout and raises an error if an execution id hasn’t been set yet, if id is set returns immediately.

Returns:

  • (Integer)

Raises:



147
148
149
150
151
152
 
# File 'lib/ferrum/frame.rb', line 147

def execution_id!
  value = @execution_id.borrow(@page.timeout, &:itself)
  raise NoExecutionContextError if value.instance_of?(Object)

  value
end

#execution_id=(value) ⇒ Object 



167
168
169
170
171
172
173
 
# File 'lib/ferrum/frame.rb', line 167

def execution_id=(value)
  if value.nil?
    @execution_id.try_take!
  else
    @execution_id.try_put!(value)
  end
end

#inspect ⇒ Object 



175
176
177
178
179
180
181
182
 
# File 'lib/ferrum/frame.rb', line 175

def inspect
  "#<#{self.class} " \
    "@id=#{@id.inspect} " \
    "@parent_id=#{@parent_id.inspect} " \
    "@name=#{@name.inspect} " \
    "@state=#{@state.inspect} " \
    "@execution_id=#{@execution_id.inspect}>"
end

#main? ⇒ Boolean

If current frame is the main frame of the page (top of the tree).

Examples:

browser.go_to("https://www.w3schools.com/tags/tag_frame.asp")
frame = browser.frame_by(id: "C09C4E4404314AAEAE85928EAC109A93")
frame.main? # => false

Returns:

  • (Boolean) 


93
94
95
 
# File 'lib/ferrum/frame.rb', line 93

def main?
  @parent_id.nil?
end

#parent ⇒ Frame?

Returns the parent frame if this frame is nested in another one.

Examples:

browser.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
frame = browser.frames.last
frame.url # => "https://www.openstreetmap.org/export/embed.html?bbox=-0.004017949104309083%2C51.47612752641776%2C0.00030577182769775396%2C51.478569861898606&layer=mapnik"
frame.parent.main? # => false
frame.parent.parent.main? # => false
frame.parent.parent.parent.main? # => true

Returns:



110
111
112
 
# File 'lib/ferrum/frame.rb', line 110

def parent
  @page.frame_by(id: @parent_id) if @parent_id
end

#title ⇒ String

Returns current frame’s title.

Examples:

browser.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
frame = browser.frames[1]
frame.title # => HTML Demo: <iframe>

Returns:

  • (String) 


79
80
81
 
# File 'lib/ferrum/frame.rb', line 79

def title
  evaluate("document.title")
end

#url ⇒ String

Returns current frame’s ‘location.href`.

Examples:

browser.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
frame = browser.frames[1]
frame.url # => https://interactive-examples.mdn.mozilla.net/pages/tabbed/iframe.html

Returns:

  • (String) 


65
66
67
 
# File 'lib/ferrum/frame.rb', line 65

def url
  evaluate("document.location.href")
end