Class: Premailer

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

Overview

Premailer by Alex Dunae (dunae.ca, e-mail ‘code’ at the same domain), 2008-09

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

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

Example

premailer = Premailer.new('http://example.com/myfile.html', :warn_level => Premailer::Warnings::SAFE)

# Write the HTML output
fout = File.open("output.html", "w")
fout.puts premailer.to_inline_css
fout.close

# Write the plain-text output
fout = File.open("ouput.txt", "w")
fout.puts premailer.to_plain_text
fout.close

# List any CSS warnings
puts premailer.warnings.length.to_s + ' warnings found'
premailer.warnings.each do |w|
  puts "#{w[:message]} (#{w[:level]}) may not render properly in #{w[:clients]}"
end

premailer = Premailer.new(html_file, :warn_level => Premailer::Warnings::SAFE)
puts premailer.to_inline_css

Defined Under Namespace

Modules: Warnings

Constant Summary collapse

VERSION = 
'1.5.5'
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
{ 
  'h1' => {'text-align' => 'align'},
  'h2' => {'text-align' => 'align'},
  'h3' => {'text-align' => 'align'},
  'h4' => {'text-align' => 'align'},
  'h5' => {'text-align' => 'align'},
  'h6' => {'text-align' => 'align'},
  'p' => {'text-align' => 'align'},
  'div' => {'text-align' => 'align'},
  'blockquote' => {'text-align' => 'align'},
  'body' => {'background-color' => 'bgcolor'},
  'table' => {'background-color' => 'bgcolor'},
  'tr' => {'text-align' => 'align', 'background-color' => 'bgcolor'},
  'th' => {'text-align' => 'align', 'background-color' => 'bgcolor', 'vertical-align' => 'valign'},
  'td' => {'text-align' => 'align', 'background-color' => 'bgcolor', 'vertical-align' => 'valign'},
  'img' => {'float' => 'align'}
}
WARN_LABEL = 
%w(NONE SAFE POOR RISKY)

Constants included from Warnings

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from HtmlToPlainText

#convert_to_text

Constructor Details

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

Create a new Premailer object.

html is the HTML data to process. Can be either an IO object, the URL of a remote file or a local path.

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. Do not include the initial ?.

base_url

Used to calculate absolute URLs for local files.

css

Manually specify a CSS stylesheet.

css_to_attributes

Copy related CSS attributes into HTML attributes (e.g. background-color to bgcolor)



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/premailer/premailer.rb', line 95

def initialize(html, options = {})
  @options = {:warn_level => Warnings::SAFE, 
              :line_length => 65, 
              :link_query_string => nil, 
              :base_url => nil,
              :remove_classes => false,
              :css => [],
              :css_to_attributes => true,
              :verbose => false,
              :io_exceptions => false}.merge(options)
  @html_file = html
 
  @is_local_file = Premailer.local_data?(html)

  @css_files = @options[:css]

  @css_warnings = []

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

Instance Attribute Details

#doc ⇒ Object (readonly)

source HTML document (Nokogiri)



71
72
73
 
# File 'lib/premailer/premailer.rb', line 71

def doc
  @doc
end

#html_file ⇒ Object (readonly)

URI of the HTML file used



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

def html_file
  @html_file
end

#processed_doc ⇒ Object (readonly)

processed HTML document (Nokogiri)



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

def processed_doc
  @processed_doc
end

Class Method Details

.canonicalize(uri) ⇒ Object

from www.ruby-forum.com/topic/140101



444
445
446
447
448
449
450
451
452
453
454
 
# File 'lib/premailer/premailer.rb', line 444

def self.canonicalize(uri) # :nodoc:
u = uri.kind_of?(URI) ? uri : URI.parse(uri.to_s)
u.normalize!
newpath = u.path
while newpath.gsub!(%r{([^/]+)/\.\./?}) { |match|
    $1 == '..' ? match : ''
  } do end
  newpath = newpath.gsub(%r{/\./}, '/').sub(%r{/\.\z}, '/')
  u.path = newpath
  u.to_s
end

.escape_string(str) ⇒ Object

here be instance methods



407
408
409
 
# File 'lib/premailer/premailer.rb', line 407

def self.escape_string(str) # :nodoc:
  str.gsub(/"/, "'")
end

.local_data?(data) ⇒ Boolean

Test the passed variable to see if we are in local or remote mode.

IO objects return true, as do strings that look like URLs.

Returns:

  • (Boolean) 


433
434
435
436
437
438
439
440
441
 
# File 'lib/premailer/premailer.rb', line 433

def self.local_data?(data)
  if data.is_a?(IO) || data.is_a?(StringIO)
    return true
  elsif data =~ /^(http|https|ftp)\:\/\//i
    return false
  else
    return true
  end
end

.resolve_link(path, base_path) ⇒ Object

:nodoc:



411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
 
# File 'lib/premailer/premailer.rb', line 411

def self.resolve_link(path, base_path) # :nodoc:
  path.strip!
  resolved = nil
  if path =~ /(http[s]?|ftp):\/\//i
    resolved = path
    return Premailer.canonicalize(resolved)
  elsif base_path.kind_of?(URI)
    resolved = base_path.merge(path)
    return Premailer.canonicalize(resolved)    
  elsif base_path.kind_of?(String) and base_path =~ /^(http[s]?|ftp):\/\//i
    resolved = URI.parse(base_path)
    resolved = resolved.merge(path)
    return Premailer.canonicalize(resolved)
  else

    return File.expand_path(path, File.dirname(base_path))
  end
end

Instance Method Details

#check_client_support ⇒ Object

Check CLIENT_SUPPORT_FILE for any CSS warnings



457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
 
# File 'lib/premailer/premailer.rb', line 457

def check_client_support # :nodoc:
  @client_support = @client_support ||= YAML::load(File.open(CLIENT_SUPPORT_FILE))

  warnings = []
  properties = []

  # Get a list off CSS properties
  @processed_doc.search("*[@style]").each do |el|
    style_url = el.attributes['style'].to_s.gsub(/([\w\-]+)[\s]*\:/i) do |s|
      properties.push($1)
    end
  end

  properties.uniq!

  property_support = @client_support['css_properties']
  properties.each do |prop|
    if property_support.include?(prop) and
        property_support[prop].include?('support') and
        property_support[prop]['support'] >= @options[:warn_level]
      warnings.push({:message => "#{prop} CSS property",
          :level => WARN_LABEL[property_support[prop]['support']],
          :clients => property_support[prop]['unsupported_in'].join(', ')})
    end
  end

  @client_support['attributes'].each do |attribute, data|
    next unless data['support'] >= @options[:warn_level]
    if @doc.search("*[@#{attribute}]").length > 0
      warnings.push({:message => "#{attribute} HTML attribute",
          :level => WARN_LABEL[property_support[prop]['support']],
          :clients => property_support[prop]['unsupported_in'].join(', ')})
    end
  end

  @client_support['elements'].each do |element, data|
    next unless data['support'] >= @options[:warn_level]
    if @doc.search("element").length > 0
      warnings.push({:message => "#{element} HTML element",
          :level => WARN_LABEL[property_support[prop]['support']],
          :clients => property_support[prop]['unsupported_in'].join(', ')})
    end
  end

  return warnings
end

#local_uri?(uri) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


400
401
402
403
 
# File 'lib/premailer/premailer.rb', line 400

def local_uri?(uri) # :nodoc:
  warn "[DEPRECATION] `local_uri?` is deprecated.  Please use `Premailer.local_data?` instead."
  Premailer.local_data?(uri)
end

#to_inline_css ⇒ Object

Merge CSS into the HTML document.

Returns a string.



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/premailer/premailer.rb', line 160

def to_inline_css
  doc = @processed_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.css(selector).each do |el|
        if el.elem?
          # Add a style attribute or append to the existing one  
          block = "[SPEC=#{specificity}[#{declaration}]]"
          el['style'] = (el.attributes['style'].to_s ||= '') + ' ' + 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
    merged = CssParser.merge(declarations)
    merged.expand_shorthand!
    
    #if @options[:prefer_cellpadding] and (el.name == 'td' or el.name == 'th') and el['cellpadding'].nil?
    #  if cellpadding = equivalent_cellpadding(merged)
    #    el['cellpadding'] = cellpadding
    #    merged['padding-left'] = nil
    #    merged['padding-right'] = nil
    #    merged['padding-top'] = nil
    #    merged['padding-bottom'] = nil
    #  end
    #end
    
    # Duplicate CSS attributes as HTML attributes
    if RELATED_ATTRIBUTES.has_key?(el.name)       
      RELATED_ATTRIBUTES[el.name].each do |css_att, html_att|
        el[html_att] = merged[css_att].gsub(/;$/, '').strip if el[html_att].nil? and not merged[css_att].empty?
      end
    end
    
    merged.create_dimensions_shorthand!

    # write the inline STYLE attribute
    el['style'] = Premailer.escape_string(merged.declarations_to_s)
  end

  doc = write_unmergable_css_rules(doc, unmergable_rules)

  doc.search('*').remove_class if @options[:remove_classes]  

  @processed_doc = doc

  doc.to_html
end

#to_plain_text ⇒ Object

Converts the HTML document to a format suitable for plain-text e-mail.

Returns a string.



147
148
149
150
151
152
153
154
155
 
# File 'lib/premailer/premailer.rb', line 147

def to_plain_text
  html_src = ''
  begin
    html_src = @doc.search("body").inner_html
  rescue
    html_src = @doc.to_html
  end
  convert_to_text(html_src, @options[:line_length], @html_charset)
end

#to_s ⇒ Object

Returns the original HTML as a string.



140
141
142
 
# File 'lib/premailer/premailer.rb', line 140

def to_s
  @doc.to_html
end

#warnings ⇒ Object

Array containing a hash of CSS warnings.



133
134
135
136
137
 
# File 'lib/premailer/premailer.rb', line 133

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