Class: Premailer

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

Overview

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

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: Adapter, Warnings

Constant Summary collapse

VERSION = 
'1.7.3'
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
RE_RESET_SELECTORS = 
/^(\:\#outlook|body.*|\.ReadMsgBody|\.ExternalClass|img|\#backgroundTable)$/
{
  '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',
    '-premailer-width' => 'width',
    '-premailer-height' => 'height',
    '-premailer-cellpadding' => 'cellpadding',
    '-premailer-cellspacing' => 'cellspacing',
  },
  'tr' => {
    'text-align' => 'align',
    'background-color' => 'bgcolor',
    '-premailer-height' => 'height'
  },
  'th' => {
    'text-align' => 'align',
    'background-color' => 'bgcolor',
    'vertical-align' => 'valign',
    '-premailer-width' => 'width',
    '-premailer-height' => 'height'
  },
  'td' => {
    'text-align' => 'align',
    'background-color' => 'bgcolor',
    'vertical-align' => 'valign',
    '-premailer-width' => 'width',
    '-premailer-height' => 'height',
    '-premailer-colspan' => 'colspan'
  },
  '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, #word_wrap

Constructor Details

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

Create a new Premailer object.

html is the HTML data to process. It can be either an IO object, the URL of a remote file, a local path or a raw HTML string. If passing an HTML string you must set the :with_html_string option to true.

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 CSS stylesheets.

css_to_attributes

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

css_string

Pass CSS as a string

remove_ids

Remove ID attributes whenever possible and convert IDs used as anchors to hashed to avoid collisions in webmail programs. Default is false.

remove_classes

Remove class attributes. Default is false.

remove_comments

Remove html comments. Default is false.

preserve_styles

Whether to preserve any link rel=stylesheet and style elements. Default is false.

preserve_reset

Whether to preserve styles associated with the MailChimp reset code

with_html_string

Whether the html param should be treated as a raw string.

verbose

Whether to print errors and warnings to $stderr. Default is false.

adapter

Which HTML parser to use, either :nokogiri or :hpricot. Default is :hpricot.



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
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/premailer/premailer.rb', line 136

def initialize(html, options = {})
  @options = {:warn_level => Warnings::SAFE,
              :line_length => 65,
              :link_query_string => nil,
              :base_url => nil,
              :remove_classes => false,
              :remove_ids => false,
              :remove_comments => false,
              :css => [],
              :css_to_attributes => true,
              :with_html_string => false,
              :css_string => nil,
              :preserve_styles => false,
              :preserve_reset => true,
              :verbose => false,
              :debug => false,
              :io_exceptions => false,
              :adapter => Adapter.use}.merge(options)

  @html_file = html
  @is_local_file = @options[:with_html_string] || Premailer.local_data?(html)

  @css_files = [@options[:css]].flatten

  @css_warnings = []

  @base_url = nil
  @base_dir = nil
  @unmergable_rules = nil

  if @options[:base_url]
    @base_url = URI.parse(@options.delete(:base_url))
  elsif not @is_local_file
    @base_url = URI.parse(@html_file)
  end

  @css_parser = CssParser::Parser.new({
    :absolute_paths => true,
    :import => true,
    :io_exceptions => @options[:io_exceptions]
  })

  @adapter_class = Adapter.find @options[:adapter]

  self.class.send(:include, @adapter_class)

  @doc = load_html(@html_file)

  @processed_doc = @doc
  @processed_doc = convert_inline_links(@processed_doc, @base_url) if @base_url
  if options[:link_query_string]
    @processed_doc = append_query_string(@processed_doc, options[:link_query_string])
  end
  load_css_from_options!
  load_css_from_html!
end

Instance Attribute Details

#base_dir ⇒ Object (readonly)

base directory used to resolve links for local files



93
94
95
 
# File 'lib/premailer/premailer.rb', line 93

def base_dir
  @base_dir
end

#base_url ⇒ Object (readonly)

base URL used to resolve links



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

def base_url
  @base_url
end

#doc ⇒ Object (readonly)

source HTML document (Hpricot/Nokogiri)



102
103
104
 
# File 'lib/premailer/premailer.rb', line 102

def doc
  @doc
end

#html_file ⇒ Object (readonly)

URI of the HTML file used



87
88
89
 
# File 'lib/premailer/premailer.rb', line 87

def html_file
  @html_file
end

#processed_doc ⇒ Object (readonly)

processed HTML document (Hpricot/Nokogiri)



99
100
101
 
# File 'lib/premailer/premailer.rb', line 99

def processed_doc
  @processed_doc
end

#unmergable_rules ⇒ Object (readonly)

unmergeable CSS rules to be preserved in the head (CssParser)



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

def unmergable_rules
  @unmergable_rules
end

Class Method Details

.canonicalize(uri) ⇒ Object

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



422
423
424
425
426
427
428
429
430
431
432
 
# File 'lib/premailer/premailer.rb', line 422

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

:nodoc:



390
391
392
 
# File 'lib/premailer/premailer.rb', line 390

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) 


415
416
417
418
419
 
# File 'lib/premailer/premailer.rb', line 415

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

.resolve_link(path, base_path) ⇒ Object

:nodoc:



394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
 
# File 'lib/premailer/premailer.rb', line 394

def self.resolve_link(path, base_path) # :nodoc:
  path.strip!
  resolved = nil
  if path =~ /(http[s]?|ftp):\/\//i
    resolved = path
    Premailer.canonicalize(resolved)
  elsif base_path.kind_of?(URI)
    resolved = base_path.merge(path)
    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)
    Premailer.canonicalize(resolved)
  else
    File.expand_path(path, File.dirname(base_path))
  end
end

Instance Method Details

#append_query_string(doc, qs) ⇒ Object 



281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/premailer/premailer.rb', line 281

def append_query_string(doc, qs)
  return doc if qs.nil?

  qs.to_s.gsub!(/^[\?]*/, '').strip!
  return doc if qs.empty?

  begin
    current_host = @base_url.host
  rescue
    current_host = nil
  end

  $stderr.puts "Attempting to append_query_string: #{qs}" if @options[:verbose]

  doc.search('a').each do|el|
    href = el.attributes['href'].to_s.strip
    next if href.nil? or href.empty?
    
    next if href[0,1] =~ /[\#\{\[\<\%]/ # don't bother with anchors or special-looking links

    begin
      href = URI.parse(href)

      if current_host and href.host != nil and href.host != current_host
        $stderr.puts "Skipping append_query_string for: #{href.to_s} because host is no good" if @options[:verbose]
        next
      end

      if href.scheme and href.scheme != 'http' and href.scheme != 'https'
        puts "Skipping append_query_string for: #{href.to_s} because scheme is no good" if @options[:verbose]
        next
      end

      if href.query and not href.query.empty?
        href.query = href.query + '&amp;' + qs
      else
        href.query = qs
      end

      el['href'] = href.to_s
    rescue URI::Error => e
      $stderr.puts "Skipping append_query_string for: #{href.to_s} (#{e.message})" if @options[:verbose]
      next
    end

  end
  doc
end

#check_client_support ⇒ Object

Check CLIENT_SUPPORT_FILE for any CSS warnings



435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
 
# File 'lib/premailer/premailer.rb', line 435

def check_client_support # :nodoc:
  @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[data['support']],
          :clients => data['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[data['support']],
          :clients => data['unsupported_in'].join(', ')})
    end
  end

  return warnings
end

#convert_inline_links(doc, base_uri) ⇒ Object

Processes href src and background attributes as well as CSS url() declarations found in inline style attributes.

doc is an Hpricot document and base_uri is either a string or a URI.

Returns an Hpricot document.



346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
 
# File 'lib/premailer/premailer.rb', line 346

def convert_inline_links(doc, base_uri) # :nodoc:
  base_uri = URI.parse(base_uri) unless base_uri.kind_of?(URI)

  append_qs = @options[:link_query_string] || ''

  ['href', 'src', 'background'].each do |attribute|
    tags = doc.search("*[@#{attribute}]")

    next if tags.empty?

    tags.each do |tag|
      # skip links that look like they have merge tags
      # and mailto, ftp, etc...
      if tag.attributes[attribute].to_s =~ /^([\%\<\{\#\[]|data:|tel:|file:|sms:|callto:|facetime:|mailto:|ftp:|gopher:)/i
        next
      end

      if tag.attributes[attribute].to_s =~ /^http/i
        begin
          merged = URI.parse(tag.attributes[attribute])
        rescue; next; end
      else
        begin
          merged = Premailer.resolve_link(tag.attributes[attribute].to_s, base_uri)
        rescue
          begin
            merged = Premailer.resolve_link(URI.escape(tag.attributes[attribute].to_s), base_uri)
          rescue; end
        end
      end

      # make sure 'merged' is a URI
      merged = URI.parse(merged.to_s) unless merged.kind_of?(URI)
      tag[attribute] = merged.to_s
    end # end of each tag
  end # end of each attrs

  doc.search("*[@style]").each do |el|
    el['style'] = CssParser.convert_uris(el.attributes['style'].to_s, base_uri)
  end
  doc
end

#is_xhtml? ⇒ Boolean

Check for an XHTML doctype

Returns:

  • (Boolean) 


331
332
333
334
335
336
 
# File 'lib/premailer/premailer.rb', line 331

def is_xhtml?
  intro = @doc.to_html.strip.split("\n")[0..2].join(' ')
  is_xhtml = !!(intro =~ /w3c\/\/[\s]*dtd[\s]+xhtml/i)
  $stderr.puts "Is XHTML? #{is_xhtml.inspect}\nChecked:\n#{intro}" if @options[:debug]
  is_xhtml
end

#local_uri?(uri) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


267
268
269
270
 
# File 'lib/premailer/premailer.rb', line 267

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

#media_type_ok?(media_types) ⇒ Boolean

here be instance methods

Returns:

  • (Boolean) 


274
275
276
277
278
279
 
# File 'lib/premailer/premailer.rb', line 274

def media_type_ok?(media_types) # :nodoc:
  return true if media_types.nil? or media_types.empty?
  media_types.split(/[\s]+|,/).any? { |media_type| media_type.strip =~ /screen|handheld|all/i }
rescue
  true
end

#warnings ⇒ Object

Array containing a hash of CSS warnings.



194
195
196
197
198
 
# File 'lib/premailer/premailer.rb', line 194

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