Class: Roadie::Document

Inherits:
Object
  • Object
show all
Defined in:
lib/roadie/document.rb

Overview

The main entry point for Roadie. A document represents a working unit and is built with the input HTML and the configuration options you need.

A Document must never be used from two threads at the same time. Reusing Documents is discouraged.

Stylesheets are added to the HTML from three different sources:

  1. Stylesheets inside the document ( <style> elements)

  2. Stylesheets referenced by the DOM ( <link> elements)

  3. The internal stylesheet (see #add_css)

The internal stylesheet is used last and gets the highest priority. The rest is used in the same order as browsers are supposed to use them.

The execution methods are #transform and #transform_partial.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(html) ⇒ Document

Returns a new instance of Document.

Parameters:

  • html (String) —

    the input HTML



36
37
38
39
40
41
42
43
 
# File 'lib/roadie/document.rb', line 36

def initialize(html)
  @keep_uninlinable_css = true
  @html = html
  @asset_providers = ProviderList.wrap(FilesystemProvider.new)
  @external_asset_providers = ProviderList.empty
  @css = ""
  @mode = :html
end

Instance Attribute Details

#after_transformation ⇒ #call

Callback to call just before #transformation is completed. Will be called with the current DOM tree and the Roadie::Document instance.

Returns:

  • (#call) —

    the current value of after_transformation



20
21
22
 
# File 'lib/roadie/document.rb', line 20

def after_transformation
  @after_transformation
end

#asset_providers ⇒ Object

Returns the value of attribute asset_providers.



21
22
23
 
# File 'lib/roadie/document.rb', line 21

def asset_providers
  @asset_providers
end

#before_transformation ⇒ #call

Callback to call just before #transformation begins. Will be called with the parsed DOM tree and the Roadie::Document instance.

Returns:

  • (#call) —

    the current value of before_transformation



20
21
22
 
# File 'lib/roadie/document.rb', line 20

def before_transformation
  @before_transformation
end

#external_asset_providers ⇒ Object

Returns the value of attribute external_asset_providers.



21
22
23
 
# File 'lib/roadie/document.rb', line 21

def external_asset_providers
  @external_asset_providers
end

#html ⇒ Object (readonly)

Returns the value of attribute html.



21
22
23
 
# File 'lib/roadie/document.rb', line 21

def html
  @html
end

#keep_uninlinable_css ⇒ Object

Should CSS that cannot be inlined be kept in a new ‘<style>` element in `<head>`?



30
31
32
 
# File 'lib/roadie/document.rb', line 30

def keep_uninlinable_css
  @keep_uninlinable_css
end

#mode ⇒ Object

The mode to generate markup in. Valid values are ‘:html` (default) and `:xhtml`.



33
34
35
 
# File 'lib/roadie/document.rb', line 33

def mode
  @mode
end

#url_options ⇒ Object

URL options. If none are given no URL rewriting will take place.

See Also:



25
26
27
 
# File 'lib/roadie/document.rb', line 25

def url_options
  @url_options
end

Instance Method Details

#add_css(new_css) ⇒ Object

Append additional CSS to the document’s internal stylesheet.

Parameters:

  • new_css (String) 


47
48
49
 
# File 'lib/roadie/document.rb', line 47

def add_css(new_css)
  @css << "\n\n" << new_css
end

#transform ⇒ String

Transform the input HTML as a full document and returns the processed HTML.

Before the transformation begins, the #before_transformation callback will be called with the parsed HTML tree and the Roadie::Document instance, and after all work is complete the #after_transformation callback will be invoked in the same way.

Most of the work is delegated to other classes. A list of them can be seen below.

Returns:

  • (String) —

    the transformed HTML

See Also:



68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/roadie/document.rb', line 68

def transform
  dom = Nokogiri::HTML.parse html

  callback before_transformation, dom

  improve dom
  inline dom, keep_uninlinable_in: :head
  rewrite_urls dom

  callback after_transformation, dom

  remove_ignore_markers dom
  serialize_document dom
end

#transform_partial ⇒ String

Transform the input HTML as a HTML fragment/partial and returns the processed HTML.

Before the transformation begins, the #before_transformation callback will be called with the parsed HTML tree and the Roadie::Document instance, and after all work is complete the #after_transformation callback will be invoked in the same way.

The main difference between this and #transform is that this does not treat the HTML as a full document and does not try to fix it by adding doctypes, <head> elements, etc.

Most of the work is delegated to other classes. A list of them can be seen below.

Returns:

  • (String) —

    the transformed HTML

See Also:



103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/roadie/document.rb', line 103

def transform_partial
  dom = Nokogiri::HTML.fragment html

  callback before_transformation, dom

  inline dom, keep_uninlinable_in: :root
  rewrite_urls dom

  callback after_transformation, dom

  serialize_document dom
end