Class: Premailer

Inherits:
Object
  • Object
show all
Includes:
CssParser, HtmlToPlainText, Warnings
Defined in:
lib/premailer.rb

Overview

Premailer processes HTML and CSS to improve e-mail deliverability.

Premailer’s main function is to render all CSS as inline style attributes using the CssParser. It can also convert relative links to absolute links and check the ‘safety’ of CSS properties against a CSS support chart.

Example

premailer = Premailer.new(html_file, :warn_level => Premailer::Warnings::SAFE)
premailer.parse!
puts premailer.warnings.length.to_s + ' warnings found'

Defined Under Namespace

Modules: Warnings

Constant Summary collapse

CLIENT_SUPPORT_FILE = 
File.dirname(__FILE__) + '/../misc/client_support.yaml'
RE_UNMERGABLE_SELECTORS = 
/(\:(visited|active|hover|focus|after|before|selection|target|first\-(line|letter))|^\@)/i
WARN_LABEL = 
%w(NONE SAFE POOR RISKY)

Constants included from Warnings

Warnings::NONE, Warnings::POOR, Warnings::RISKY, Warnings::SAFE

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from HtmlToPlainText

#convert_to_text

Constructor Details

#initialize(uri, options = {}) ⇒ Premailer

Create a new Premailer object.

uri is the URL of the HTML file to process. Should be a string.

Options

line_length

Line length used by to_plain_text. Boolean, default is 65.

warn_level

What level of CSS compatibility warnings to show (see Warnings).

link_query_string

A string to append to every <a href=“”> link.



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/premailer.rb', line 61

def initialize(uri, options = {})
  @options = {:warn_level => Warnings::SAFE, :line_length => 65, :link_query_string => nil, :base_url => nil, :shorten_urls => false}.merge(options)
  @html_file = uri

  
  @is_local_file = true
  if uri =~ /^(http|https|ftp)\:\/\//i
    @is_local_file = false
  end


  @css_warnings = []

  @css_parser = CssParser::Parser.new({:absolute_paths => true,
                                       :import => true,
                                       :io_exceptions => false
                                      })
  
  @doc, @html_charset = load_html(@html_file)
  
  if @is_local_file and @options[:base_url]
    @doc = convert_inline_links(@doc, @options[:base_url])
  elsif not @is_local_file
    @doc = convert_inline_links(@doc, @html_file)
  end
  load_css_from_html!
end

Instance Attribute Details

#html_file ⇒ Object (readonly)

URI of the HTML file used



41
42
43
 
# File 'lib/premailer.rb', line 41

def html_file
  @html_file
end

Instance Method Details

#to_inline_css ⇒ Object

Merge CSS into the HTML document.

Returns a string.



119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/premailer.rb', line 119

def to_inline_css
  doc = @doc
  unmergable_rules = CssParser::Parser.new
  
  # Give all styles already in style attributes a specificity of 1000 
  # per http://www.w3.org/TR/CSS21/cascade.html#specificity
  doc.search("*[@style]").each do |el| 
    el['style'] = '[SPEC=1000[' + el.attributes['style'] + ']]'
  end

  # Iterate through the rules and merge them into the HTML
  @css_parser.each_selector(:all) do |selector, declaration, specificity|
    # Save un-mergable rules separately
    selector.gsub!(/:link([\s]|$)+/i, '')

    # Convert element names to lower case
    selector.gsub!(/([\s]|^)([\w]+)/) {|m| $1.to_s + $2.to_s.downcase }

    if selector =~ RE_UNMERGABLE_SELECTORS
      unmergable_rules.add_rule_set!(RuleSet.new(selector, declaration))
    else
      
      doc.search(selector) do |el|
        if el.elem?
          # Add a style attribute or append to the existing one  
          block = "[SPEC=#{specificity}[#{declaration}]]"
          el['style'] = (el.attributes['style'] ||= '') + ' ' + block
        end
      end
    end
  end

  # Read <style> attributes and perform folding
  doc.search("*[@style]").each do |el|
    style = el.attributes['style'].to_s
    
    declarations = []

    style.scan(/\[SPEC\=([\d]+)\[(.[^\]\]]*)\]\]/).each do |declaration|
      rs = RuleSet.new(nil, declaration[1].to_s, declaration[0].to_i)
      declarations << rs
    end

    # Perform style folding and save
    merged = CssParser.merge(declarations)

    el['style'] = Premailer.escape_string(merged.declarations_to_s)
  end

  doc = write_unmergable_css_rules(doc, unmergable_rules)
  
  #doc = add_body_imposter(doc)
  
  doc.to_html
end

#to_plain_text ⇒ Object

Returns the document with all HTML tags removed.



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

def to_plain_text
  html_src = ''
  begin
    html_src = @doc.search("body").innerHTML
  rescue
    html_src = @doc.to_html
  end
if @options[:shorten_urls]
  	convert_to_text(html_src, @options[:line_length], @html_charset, true)
else
	convert_to_text(html_src, @options[:line_length], @html_charset, false)
end
end

#to_s ⇒ Object

Returns the original HTML as a string.



97
98
99
 
# File 'lib/premailer.rb', line 97

def to_s
  @doc.to_html
end

#warnings ⇒ Object

Array containing a hash of CSS warnings.



90
91
92
93
94
 
# File 'lib/premailer.rb', line 90

def warnings
  return [] if @options[:warn_level] == Warnings::NONE
  @css_warnings = check_client_support if @css_warnings.empty?
  @css_warnings
end