class Roadie::Document

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.

@attr [#call] #before_transformation Callback to call just before {#transform}ation begins. Will be called with the parsed DOM tree and the {Document} instance. @attr [#call] #after_transformation Callback to call just before {#transform}ation is completed. Will be called with the current DOM tree and the {Document} instance.

Attributes

after_transformation[RW]
asset_providers[R]
before_transformation[RW]
external_asset_providers[R]
html[R]
keep_uninlinable_css[RW]

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

url_options[RW]

URL options. If none are given no URL rewriting will take place. @see UrlGenerator#initialize

Public Class Methods

new(html) click to toggle source

@param [String] html the input HTML

# File lib/roadie/document.rb, line 31
def initialize(html)
  @keep_uninlinable_css = true
  @html = html
  @asset_providers = ProviderList.wrap(FilesystemProvider.new)
  @external_asset_providers = ProviderList.empty
  @css = ""
end

Public Instance Methods

add_css(new_css) click to toggle source

Append additional CSS to the document's internal stylesheet. @param [String] new_css

# File lib/roadie/document.rb, line 41
def add_css(new_css)
  @css << "\n\n" << new_css
end
asset_providers=(list) click to toggle source

Assign new normal asset providers. The supplied list will be wrapped in a {ProviderList} using {ProviderList.wrap}.

# File lib/roadie/document.rb, line 75
def asset_providers=(list)
  @asset_providers = ProviderList.wrap(list)
end
external_asset_providers=(list) click to toggle source

Assign new external asset providers. The supplied list will be wrapped in a {ProviderList} using {ProviderList.wrap}.

# File lib/roadie/document.rb, line 80
def external_asset_providers=(list)
  @external_asset_providers = ProviderList.wrap(list)
end
transform() click to toggle source

Transform the input HTML and returns the processed HTML.

Before the transformation begins, the {#before_transformation} callback will be called with the parsed HTML tree and the {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.

@see MarkupImprover MarkupImprover (improves the markup of the DOM) @see Inliner Inliner (inlines the stylesheets) @see UrlRewriter UrlRewriter (rewrites URLs and makes them absolute)

@return [String] the transformed HTML

# File lib/roadie/document.rb, line 59
def transform
  dom = Nokogiri::HTML.parse html

  callback before_transformation, dom

  improve dom
  inline dom
  rewrite_urls dom

  callback after_transformation, dom

  # #dup is called since it fixed a few segfaults in certain versions of Nokogiri
  dom.dup.to_html
end

Private Instance Methods

callback(callable, dom) click to toggle source
# File lib/roadie/document.rb, line 110
def callback(callable, dom)
  if callable.respond_to?(:call)
    # Arity checking is to support the API without bumping a major version.
    # TODO: Remove on next major version (v4.0)
    if !callable.respond_to?(:parameters) || callable.parameters.size == 1
      callable.(dom)
    else
      callable.(dom, self)
    end
  end
end
improve(dom) click to toggle source
# File lib/roadie/document.rb, line 89
def improve(dom)
  MarkupImprover.new(dom, html).improve
end
inline(dom) click to toggle source
# File lib/roadie/document.rb, line 93
def inline(dom)
  dom_stylesheets = AssetScanner.new(dom, asset_providers, external_asset_providers).extract_css
  Inliner.new(dom_stylesheets + [stylesheet], dom).inline(keep_uninlinable_css)
end
make_url_rewriter() click to toggle source
# File lib/roadie/document.rb, line 102
def make_url_rewriter
  if url_options
    UrlRewriter.new(UrlGenerator.new(url_options))
  else
    NullUrlRewriter.new
  end
end
rewrite_urls(dom) click to toggle source
# File lib/roadie/document.rb, line 98
def rewrite_urls(dom)
  make_url_rewriter.transform_dom(dom)
end
stylesheet() click to toggle source
# File lib/roadie/document.rb, line 85
def stylesheet
  Stylesheet.new "(Document styles)", @css
end