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



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

def initialize(html)
  @keep_uninlinable_css = true
  @merge_media_queries = true
  @serialization_options =
    Nokogiri::XML::Node::SaveOptions::NO_DECLARATION |
    Nokogiri::XML::Node::SaveOptions::NO_EMPTY_TAGS
  @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



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

def after_transformation
  @after_transformation
end

#asset_providersObject

Returns the value of attribute asset_providers.



23
24
25
# File 'lib/roadie/document.rb', line 23

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



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

def before_transformation
  @before_transformation
end

#external_asset_providersObject

Returns the value of attribute external_asset_providers.



23
24
25
# File 'lib/roadie/document.rb', line 23

def external_asset_providers
  @external_asset_providers
end

#htmlObject (readonly)

Returns the value of attribute html.



23
24
25
# File 'lib/roadie/document.rb', line 23

def html
  @html
end

#keep_uninlinable_cssObject

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



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

def keep_uninlinable_css
  @keep_uninlinable_css
end

#merge_media_queriesObject

Merge media queries to increase performance and reduce email size if enabled. This will change specificity in some cases, like for example:

@media(max-width: 600px) { .col-6 { display: block; } }
@media(max-width: 400px) { .col-12 { display: inline-block; } }
@media(max-width: 600px) { .col-12 { display: block; } }

will become

@media(max-width: 600px) { .col-6 { display: block; } .col-12 { display: block; } }
@media(max-width: 400px) { .col-12 { display: inline-block; } }

which would change the styling on the page



43
44
45
# File 'lib/roadie/document.rb', line 43

def merge_media_queries
  @merge_media_queries
end

#modeObject

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



50
51
52
# File 'lib/roadie/document.rb', line 50

def mode
  @mode
end

#serialization_optionsObject

Integer representing a bitmap set of options used by Nokogiri during serialization. For the complete set of available options look into Nokogiri::XML::Node::SaveOptions.



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

def serialization_options
  @serialization_options
end

#url_optionsObject

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



27
28
29
# File 'lib/roadie/document.rb', line 27

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)


68
69
70
# File 'lib/roadie/document.rb', line 68

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

#transformString

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.



89
90
91
92
93
94
95
96
97
98
99
100
101
102
# File 'lib/roadie/document.rb', line 89

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_partialString

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.



124
125
126
127
128
129
130
131
132
133
134
135
# File 'lib/roadie/document.rb', line 124

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