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.7.8'.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-

{
  "1.8" => {
    "\342\200\231" => "'",
    "\342\200\246" => "...",
    "\342\200\176" => "'",
    "\342\200\177" => "'",
    "\342\200\230" => "'",
    "\342\200\231" => "'",
    "\342\200\232" => ',',
    "\342\200\233" => "'",
    "\342\200\234" => '"',
    "\342\200\235" => '"',
    "\342\200\041" => '-',
    "\342\200\174" => '-',
    "\342\200\220" => '-',
    "\342\200\223" => '-',
    "\342\200\224" => '--',
    "\342\200\225" => '--',
    "\342\200\042" => '--'
  },
  "1.9" => {
    "’" => "'",
    "…" => "...",
    "‘" => "'",
    "‚" => ',',
    "‛" => "'",
    "“" => '"',
    "”" => '"',
    "‐" => '-',
    "–" => '-',
    "—" => '--',
    "―" => '--'
  }
}
{
  '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.

  • :with_html_string (Boolean) —

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

  • :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.

  • :replace_html_entities (Boolean) —

    Convert HTML entities to actual characters. Default is false.

  • :adapter (Symbol) —

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



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
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/premailer/premailer.rb', line 189

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',
              :replace_html_entities => 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 ⇒ String (readonly)

base directory used to resolve links for local files

Returns:

  • (String) —

    base directory



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

def base_dir
  @base_dir
end

#base_url ⇒ Object (readonly)

base URL used to resolve links



131
132
133
 
# File 'lib/premailer/premailer.rb', line 131

def base_url
  @base_url
end

#doc ⇒ Object (readonly)

source HTML document (Hpricot/Nokogiri)



144
145
146
 
# File 'lib/premailer/premailer.rb', line 144

def doc
  @doc
end

#html_file ⇒ Object (readonly)

URI of the HTML file used



128
129
130
 
# File 'lib/premailer/premailer.rb', line 128

def html_file
  @html_file
end

#processed_doc ⇒ Object (readonly)

processed HTML document (Hpricot/Nokogiri)



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

def processed_doc
  @processed_doc
end

#unmergable_rules ⇒ Object (readonly)

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



138
139
140
 
# File 'lib/premailer/premailer.rb', line 138

def unmergable_rules
  @unmergable_rules
end

Class Method Details

.canonicalize(uri) ⇒ Object

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



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

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) 


482
483
484
485
486
487
 
# File 'lib/premailer/premailer.rb', line 482

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 



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
388
389
390
391
392
393
 
# File 'lib/premailer/premailer.rb', line 346

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



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

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

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.



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
447
448
449
450
451
452
 
# File 'lib/premailer/premailer.rb', line 411

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


396
397
398
399
400
401
 
# File 'lib/premailer/premailer.rb', line 396

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.



254
255
256
257
258
 
# File 'lib/premailer/premailer.rb', line 254

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