Class: Premailer

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

Defined Under Namespace

Modules: Adapter, Warnings

Constant Summary collapse

VERSION =

Premailer version.

'1.8.2'.freeze
CLIENT_SUPPORT_FILE = 
File.dirname(__FILE__) + '/../../misc/client_support.yaml'
RE_UNMERGABLE_SELECTORS =

Unmergable selectors regexp.

/(\:(visited|active|hover|focus|after|before|selection|target|first\-(line|letter))|^\@)/i
RE_RESET_SELECTORS =

Reset selectors regexp.

/^(\:\#outlook|body.*|\.ReadMsgBody|\.ExternalClass|img|\#backgroundTable)$/
HTML_ENTITIES =

list of HTMLEntities to fix source: http://stackoverflow.com/questions/2812781/how-to-convert-webpage-apostrophe-8217-to-ascii-39-in-ruby-1-

{
  "’" => "'",
  "…" => "...",
  "‘" => "'",
  "‚" => ',',
  "‛" => "'",
  "“" => '"',
  "”" => '"',
  "‐" => '-',
  "–" => '-',
  "—" => '--',
  "―" => '--'
}
{
  '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',
    'background-image' => 'background',
    '-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'
  },
  'img' => {'float' => 'align'}
}
WARN_LABEL =

Waning level names

%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.

Parameters:

  • 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 (Hash) (defaults to: {}) —

    the options to handle html with.

Options Hash (options):

  • :line_length (FixNum) —

    Line length used by to_plain_text. Default is 65.

  • :warn_level (FixNum) —

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

  • :link_query_string (String) —

    A string to append to every a href="" link. Do not include the initial ?.

  • :base_url (String) —

    Used to calculate absolute URLs for local files.

  • :css (Array(String)) —

    Manually specify CSS stylesheets.

  • :css_to_attributes (Boolean) —

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

  • :css_string (String) —

    Pass CSS as a string

  • :remove_ids (Boolean) —

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

  • :remove_classes (Boolean) —

    Remove class attributes. Default is false.

  • :remove_comments (Boolean) —

    Remove html comments. Default is false.

  • :remove_scripts (Boolean) —

    Remove script elements. Default is true.

  • :preserve_styles (Boolean) —

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

  • :preserve_reset (Boolean) —

    Whether to preserve styles associated with the MailChimp reset code. Default is true.

  • :with_html_string (Boolean) —

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

  • :verbose (Boolean) —

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

  • :include_link_tags (Boolean) —

    Whether to include css from link rel=stylesheet tags. Default is true.

  • :include_style_tags (Boolean) —

    Whether to include css from style tags. Default is true.

  • :input_encoding (String) —

    Manually specify the source documents encoding. This is a good idea. Default is ASCII-8BIT.

  • :replace_html_entities (Boolean) —

    Convert HTML entities to actual characters. Default is false.

  • :escape_url_attributes (Boolean) —

    URL Escapes href, src, and background attributes on elements. Default is true.

  • :adapter (Symbol) —

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

  • :output_encoding (String) —

    Output encoding option for Nokogiri adapter. Should be set to "US-ASCII" to output HTML entities instead of Unicode characters.



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
 
# File 'lib/premailer/premailer.rb', line 170

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,
              :remove_scripts => true,
              :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,
              :include_link_tags => true,
              :include_style_tags => true,
              :input_encoding => 'ASCII-8BIT',
              :output_encoding => nil,
              :replace_html_entities => false,
              :escape_url_attributes => true,
              :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 ⇒ String (readonly)

base directory used to resolve links for local files

Returns:

  • (String) —

    base directory



114
115
116
 
# File 'lib/premailer/premailer.rb', line 114

def base_dir
  @base_dir
end

#base_url ⇒ Object (readonly)

base URL used to resolve links



110
111
112
 
# File 'lib/premailer/premailer.rb', line 110

def base_url
  @base_url
end

#doc ⇒ Object (readonly)

source HTML document (Hpricot/Nokogiri)



123
124
125
 
# File 'lib/premailer/premailer.rb', line 123

def doc
  @doc
end

#html_file ⇒ Object (readonly)

URI of the HTML file used



107
108
109
 
# File 'lib/premailer/premailer.rb', line 107

def html_file
  @html_file
end

#processed_doc ⇒ Object (readonly)

processed HTML document (Hpricot/Nokogiri)



120
121
122
 
# File 'lib/premailer/premailer.rb', line 120

def processed_doc
  @processed_doc
end

#unmergable_rules ⇒ Object (readonly)

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



117
118
119
 
# File 'lib/premailer/premailer.rb', line 117

def unmergable_rules
  @unmergable_rules
end

Class Method Details

.canonicalize(uri) ⇒ Object

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



488
489
490
491
492
493
494
495
496
497
498
 
# File 'lib/premailer/premailer.rb', line 488

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

.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) 


480
481
482
483
484
485
 
# File 'lib/premailer/premailer.rb', line 480

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

Instance Method Details

#append_query_string(doc, qs) ⇒ Object 



338
339
340
341
342
343
344
345
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
 
# File 'lib/premailer/premailer.rb', line 338

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



501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
 
# File 'lib/premailer/premailer.rb', line 501

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

  warnings
end

#convert_inline_links(doc, base_uri) ⇒ Object

Convert relative links to absolute links.

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.



403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
 
# File 'lib/premailer/premailer.rb', line 403

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] || ''
  escape_attrs = @options[:escape_url_attributes]

  ['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:|cid:)/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
            next unless escape_attrs
            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) 


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

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

#warnings ⇒ Array(Hash)

CSS warnings.

Returns:

  • (Array(Hash)) —

    Array of warnings.



237
238
239
240
241
 
# File 'lib/premailer/premailer.rb', line 237

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