README.md in roadie-3.2.2 vs README.md in roadie-3.3.0
- old
+ new
@@ -3,11 +3,10 @@
[](http://travis-ci.org/#!/Mange/roadie)
[](https://codeclimate.com/github/Mange/roadie)
[](https://codecov.io/github/Mange/roadie?branch=master)
[](http://badge.fury.io/rb/roadie)
-[](https://gemnasium.com/Mange/roadie)
**Note: This README details the 3.x version of Roadie. You might be using 2.x, which is much older and only for Rails.**
> Making HTML emails comfortable for the Ruby rockstars
@@ -21,11 +20,15 @@
This gem makes this easier by automatically inlining stylesheets into the document. You give Roadie your CSS, or let it find it by itself from the `<link>` and `<style>` tags in the markup, and it will go through all of the selectors assigning the styles to the matching elements. Careful attention has been put into selectors being applied in the correct order, so it should behave just like in the browser.
"Dynamic" selectors (`:hover`, `:visited`, `:focus`, etc.), or selectors not understood by Nokogiri will be inlined into a single `<style>` element for those email clients that support it. This changes specificity a great deal for these rules, so it might not work 100% out of the box. (See more about this below)
-Roadie also rewrites all relative URLs in the email to an absolute counterpart, making images you insert and those referenced in your stylesheets work. No more headaches about how to write the stylesheets while still having them work with emails from your acceptance environments.
+Roadie also rewrites all relative URLs in the email to an absolute counterpart,
+making images you insert and those referenced in your stylesheets work. No more
+headaches about how to write the stylesheets while still having them work with
+emails from your acceptance environments. You can disable this on specific
+elements using a `data-roadie-ignore` marker.
Features
--------
* Writes CSS styles inline.
@@ -33,13 +36,16 @@
* Does not overwrite styles already present in the `style` attribute of tags.
* Supports the same CSS selectors as [Nokogiri](http://nokogiri.org/); use CSS3 selectors in your emails!
* Keeps `:hover` and friends around in a separate `<style>` element.
* Makes image urls absolute.
* Hostname and port configurable on a per-environment basis.
+ * Can be disabled on individual elements.
* Makes link `href`s and `img` `src`s absolute.
* Automatically adds proper HTML skeleton when missing; you don't have to create a layout for emails.
+ * Also supports HTML fragments / partial documents, where layout is not added.
* Allows you to inject stylesheets in a number of ways, at runtime.
+* Removes `data-roadie-ignore` markers before finishing the HTML.
Install & Usage
---------------
[Add this gem to your Gemfile as recommended by Rubygems](http://rubygems.org/gems/roadie) and run `bundle install`.
@@ -49,14 +55,21 @@
```
You can then create a new instance of a Roadie document:
```ruby
+# Transform full documents with the #transform method.
document = Roadie::Document.new "<html><body></body></html>"
document.add_css "body { color: green; }"
document.transform
# => "<html><body style=\"color:green;\"></body></html>"
+
+# Transform partial documents with #transform_partial.
+document = Roadie::Document.new "<div>Hello world!</div>"
+document.add_css "div { color: green; }"
+document.transform_partial
+ # => "<div style=\"color:green;\">Hello world!</div>"
```
Your document instance can be configured with several options:
* `url_options` - Dictates how absolute URLs should be built.
@@ -81,10 +94,18 @@
The following URLs will be rewritten for you:
* `a[href]` (HTML)
* `img[src]` (HTML)
* `url()` (CSS)
+You can disable individual elements by adding an `data-roadie-ignore` marker on
+them. CSS will still be inlined on those elements, but URLs will not be
+rewritten.
+
+```html
+<a href="|UNSUBSCRIBE_URL|" data-roadie-ignore>Unsubscribe</a>
+```
+
### Referenced stylesheets ###
By default, `style` and `link` elements in the email document's `head` are processed along with the stylesheets and removed from the `head`.
You can set a special `data-roadie-ignore` attribute on `style` and `link` tags that you want to ignore (the attribute will be removed, however). This is the place to put things like `:hover` selectors that you want to have for email clients allowing them.
@@ -175,11 +196,13 @@
The `NetHttpProvider` will download the URLs that is is given using Ruby's standard `Net::HTTP` library.
You can give it a whitelist of hosts that downloads are allowed from:
```ruby
-document.external_asset_providers << Roadie::NetHttpProvider.new(whitelist: ["myapp.com", "assets.myapp.com", "cdn.cdnnetwork.co.jp"])
+document.external_asset_providers << Roadie::NetHttpProvider.new(
+ whitelist: ["myapp.com", "assets.myapp.com", "cdn.cdnnetwork.co.jp"],
+)
document.external_asset_providers << Roadie::NetHttpProvider.new # Allows every host
```
#### `CachedProvider` ####
@@ -329,15 +352,22 @@
end
```
### Keeping CSS that is impossible to inline
-Some CSS is impossible to inline properly. `:hover` and `::after` comes to mind. Roadie tries its best to keep these around by injecting them inside a new `<style>` element in the `<head>`.
+Some CSS is impossible to inline properly. `:hover` and `::after` comes to
+mind. Roadie tries its best to keep these around by injecting them inside a new
+`<style>` element in the `<head>` (or at the beginning of the partial if
+transforming a partial document).
-The problem here is that Roadie cannot possible adjust the specificity for you, so they will not apply the same way as they did before the styles were inlined.
+The problem here is that Roadie cannot possible adjust the specificity for you,
+so they will not apply the same way as they did before the styles were inlined.
-Another caveat is that a lot of email clients does not support this (which is the entire point of inlining in the first place), so don't put anything important in here. Always handle the case of these selectors not being part of the email.
+Another caveat is that a lot of email clients does not support this (which is
+the entire point of inlining in the first place), so don't put anything
+important in here. Always handle the case of these selectors not being part of
+the email.
#### Specificity problems ####
Inlined styles will have much higher specificity than styles in a `<style>`. Here's an example:
@@ -372,14 +402,30 @@
divider = (link['href'] =~ /?/ ? '&' : '?')
link['href'] = link['href'] + divider + 'source=newsletter'
end
end
-document.before_transformation = proc { |dom, document| logger.debug "Inlining document with title #{dom.at_css('head > title').try(:text)}" }
+document.before_transformation = ->(dom, document) {
+ logger.debug "Inlining document with title #{dom.at_css('head > title').try(:text)}"
+}
document.after_transformation = TrackNewsletterLinks.new
```
+### XHTML vs HTML ###
+
+You can configure the underlying HTML/XML engine to output XHTML or HTML (which
+is the default). One usecase for this is that `{` tokens usually gets escaped
+to `{`, which would be a problem if you then pass the resulting HTML on to
+some other templating engine that uses those tokens (like Handlebars or Mustache).
+
+```ruby
+document.mode = :xhtml
+```
+
+This will also affect the emitted `<!DOCTYPE>` if transforming a full document.
+Partial documents does not have a `<!DOCTYPE>`.
+
Build Status
------------
Tested with [Travis CI](http://travis-ci.org) using:
@@ -416,10 +462,44 @@
### What happened to my `@keyframes`?
The CSS Parser used in Roadie does not handle keyframes. I don't think any email clients do either, but if you want to keep on trying you can add them manually to a `<style>` element (or a separate referenced stylesheet) and [tell Roadie not to touch them](#referenced-stylesheets).
+### How do I get rid of the `<body>` elements that are added?
+
+It sounds like you want to transform a partial document. Maybe you are building
+partials or template fragments to later place in other documents. Use
+`Document#transform_partial` instead of `Document#transform` in order to treat
+the HTML as a partial document.
+
+### Can I skip URL rewriting on a specific element?
+
+If you add the `data-roadie-ignore` attribute on an element, URL rewriting will
+not be performed on that element. This could be really useful for you if you
+intend to send the email through some other rendering pipeline that replaces
+some placeholders/variables.
+
+```html
+<a href="/about-us">About us</a>
+<a href="|UNSUBSCRIBE_URL|" data-roadie-ignore>Unsubscribe</a>
+```
+
+Note that this will not skip CSS inlining on the element; it will still get the
+correct styles applied.
+
+### What should I do about "Invalid URL" errors?
+
+If the URL is invalid on purpose, see _Can I skip URL rewriting on a specific
+element?_ above. Otherwise, you can try to parse it yourself using Ruby's `URI`
+class and see if you can figure it out.
+
+```ruby
+require "uri"
+URI.parse("https://example.com/best image.jpg") # raises
+URI.parse("https://example.com/best%20image.jpg") # Works!
+```
+
Documentation
-------------
* [Online documentation for gem](https://www.omniref.com/ruby/gems/roadie)
* [Online documentation for master](https://www.omniref.com/github/Mange/roadie)
@@ -460,10 +540,10 @@
License
-------
(The MIT License)
-Copyright (c) 2009-2017 Magnus Bergmark, Jim Neath / Purify, and contributors.
+Copyright (c) 2009-2018 Magnus Bergmark, Jim Neath / Purify, and contributors.
* [Magnus Bergmark](https://github.com/Mange) <magnus.bergmark@gmail.com>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: