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/cached_rule_set.rb,
lib/premailer/adapter/nokogiri.rb,
lib/premailer/adapter/nokogumbo.rb,
lib/premailer/adapter/nokogiri_fast.rb

Defined Under Namespace

Modules: Adapter, Warnings Classes: CachedRuleSet

Constant Summary collapse

VERSION =

Premailer version.

'1.27.0'
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: 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' => {
    '-premailer-align' => 'align',
    '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',
    '-premailer-width' => 'width',
    '-premailer-height' => 'height'
  }
}
WARN_LABEL =

Waning level names

['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, default is Warnings::SAFE).

  • :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). Default is true.

  • :preserve_style_attribute (Boolean) —

    Preserve original style attribute

  • :css_string (String) —

    Pass CSS as a string

  • :rgb_to_hex_attributes (Boolean) —

    Convert RBG to Hex colors. Default is false.

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

  • :reset_contenteditable (Boolean) —

    Remove contenteditable attributes. 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.

  • :io_exceptions (Boolean) —

    Throws exceptions on I/O errors. Default is false.

  • :rule_set_exceptions (Boolean) —

    Throws exceptions on invalid values in CSS Parser rule sets. Default is true.

  • :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, :nokogiri, :nokogiri_fast or :nokogumbo. Default is :nokogiri.

  • :output_encoding (String) —

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

  • :create_shorthands (Boolean) —

    Combine several properties into a shorthand one, e.g. font: style weight size. Default is true.

  • :html_fragment (Boolean) —

    Handle HTML fragment without any HTML content wrappers. Default is false.

  • :drop_unmergeable_css_rules (Boolean) —

    Do not include unmergeable css rules in a <tt><style><tt> tag. Default is false.



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

def initialize(html, options = {})
  @options = {:warn_level => Warnings::SAFE,
              :line_length => 65,
              :link_query_string => nil,
              :base_url => nil,
              :rgb_to_hex_attributes => true,
              :remove_classes => false,
              :remove_ids => false,
              :remove_comments => false,
              :remove_scripts => true,
              :reset_contenteditable => true,
              :css => [],
              :css_to_attributes => true,
              :preserve_style_attribute => false,
              :with_html_string => false,
              :css_string => nil,
              :preserve_styles => false,
              :preserve_reset => true,
              :verbose => false,
              :debug => false,
              :io_exceptions => false,
              :rule_set_exceptions => true,
              :include_link_tags => true,
              :include_style_tags => true,
              :input_encoding => 'ASCII-8BIT',
              :output_encoding => nil,
              :replace_html_entities => false,
              :escape_url_attributes => true,
              :unescaped_ampersand => false,
              :create_shorthands => true,
              :html_fragment => false,
              :adapter => Adapter.use,
              :drop_unmergeable_css_rules => false}.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 = Addressable::URI.parse(@options.delete(:base_url))
  elsif not @is_local_file
    @base_url = Addressable::URI.parse(@html_file)
  end

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

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

  self.extend(@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



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

def base_dir
  @base_dir
end

#base_url ⇒ Object (readonly)

base URL used to resolve links



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

def base_url
  @base_url
end

#doc ⇒ Object (readonly)

source HTML document (Nokogiri/Nokogumbo)



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

def doc
  @doc
end

#html_file ⇒ Object (readonly)

URI of the HTML file used



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

def html_file
  @html_file
end

#processed_doc ⇒ Object (readonly)

processed HTML document (Nokogiri/Nokogumbo)



126
127
128
 
# File 'lib/premailer/premailer.rb', line 126

def processed_doc
  @processed_doc
end

#unmergable_rules ⇒ Object (readonly)

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



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

def unmergable_rules
  @unmergable_rules
end

Class Method Details

.canonicalize(uri) ⇒ Object

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



504
505
506
507
508
 
# File 'lib/premailer/premailer.rb', line 504

def self.canonicalize(uri) # :nodoc:
  u = uri.kind_of?(Addressable::URI) ? uri : Addressable::URI.parse(uri.to_s)
  u.normalize!
  u.to_s
end

.is_media_query?(media_types) ⇒ Boolean

Returns:

  • (Boolean) 


471
472
473
 
# File 'lib/premailer/premailer.rb', line 471

def self.is_media_query?(media_types)
  media_types && media_types.any?{|mt| mt.to_s.count('()') >= 2 }
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) 


498
499
500
501
 
# File 'lib/premailer/premailer.rb', line 498

def self.local_data?(data)
  return false  if data.kind_of?(String) && data =~ /\A(?:(https?|ftp):)\/\//i
  true
end

.resolve_link(path, base_path) ⇒ Object 



476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
 
# File 'lib/premailer/premailer.rb', line 476

def self.resolve_link(path, base_path) # :nodoc:
  path = +path
  path.strip!
  resolved = nil
  if /\A(?:(https?|ftp|file):)\/\//i.match?(path)
    resolved = path
    Premailer.canonicalize(resolved)
  elsif base_path.kind_of?(Addressable::URI)
    resolved = base_path.join(path)
    Premailer.canonicalize(resolved)
  elsif base_path.kind_of?(String) and base_path =~ /\A(?:(?:https?|ftp|file):)\/\//i
    resolved = Addressable::URI.parse(base_path)
    resolved = resolved.join(path)
    Premailer.canonicalize(resolved)
  else
    File.expand_path(path, File.dirname(base_path))
  end
end

Instance Method Details

#append_query_string(doc, queries) ⇒ Object 



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
394
395
396
397
398
399
400
401
402
403
404
405
406
407
 
# File 'lib/premailer/premailer.rb', line 358

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

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

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

  $stderr.puts "Attempting to append_query_string: #{queries}" 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 /[\#\{\[\<\%]/.match?(href[0,1]) # don't bother with anchors or special-looking links

    begin
      href = Addressable::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?
        amp = @options[:unescaped_ampersand] ? '&' : '&amp;'
        href.query = href.query + amp + queries
      else
        href.query = queries
      end

      el['href'] = href.to_s
    rescue Addressable::URI::InvalidURIError => 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



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
549
550
551
552
553
554
555
556
557
 
# File 'lib/premailer/premailer.rb', line 511

def check_client_support # :nodoc:
  kwargs = Psych::VERSION >= '4' ? { aliases: true } : {}
  @client_support ||= Psych.load(File.open(CLIENT_SUPPORT_FILE), **kwargs)

  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 a document and base_uri is either a string or a URI.

Returns a document.



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
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
 
# File 'lib/premailer/premailer.rb', line 425

def convert_inline_links(doc, base_uri) # :nodoc:
  base_uri = Addressable::URI.parse(base_uri) unless base_uri.kind_of?(Addressable::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 /^([\%\<\{\#\[]|data:|tel:|file:|sms:|callto:|facetime:|mailto:|ftp:|gopher:|cid:)/i.match?(tag.attributes[attribute].to_s)
        next
      end

      if /^http/i.match?(tag.attributes[attribute].to_s)
        begin
          merged = Addressable::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(Addressable::URI.escape(tag.attributes[attribute].to_s), base_uri)
          rescue; end
        end
      end

      # make sure 'merged' is a URI
      merged = Addressable::URI.parse(merged.to_s) unless merged.kind_of?(Addressable::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) 


410
411
412
413
414
415
 
# File 'lib/premailer/premailer.rb', line 410

def is_xhtml?
  intro = @doc.to_xhtml.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

Deprecated.

Returns:

  • (Boolean) 


344
345
346
347
 
# File 'lib/premailer/premailer.rb', line 344

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

Returns:

  • (Boolean) 


352
353
354
355
356
 
# File 'lib/premailer/premailer.rb', line 352

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

#warnings ⇒ Array(Hash)

CSS warnings.

Returns:

  • (Array(Hash)) —

    Array of warnings.



259
260
261
262
263
 
# File 'lib/premailer/premailer.rb', line 259

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