h1. Roadie

Roadie tries to make sending HTML emails a little less painful in Rails 3 by inlining stylesheets and rewrite relative URLs for you.

If you want to have this in Rails 2, please see "MailStyle":https://www.github.com/purify/mail_style.

h2. How does it work?

Email clients have bad support for stylesheets, and some of them blocks stylesheets from downloading. The easiest way to handle this is to work with all styles inline, but that is error prone and hard to work with as you cannot use classes and/or reuse styling.

This gem helps making this easier by automatically inlining stylesheet rules into the document before sending it. You just give it a list of stylesheets and it will go though all of the selectors assigning the styles to the maching elements. Careful attention has been put into rules being applied in the correct order, so it should behave just like in the browser[1].

Roadie also rewrites all relative URLs in the email to a 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.

fn1. Of course, rules like @:hover@ will not work by definition. Only static styles can be added.

h2. Features

* Writes CSS styles inline
** Respects @!important@ styles
** 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!)
* Makes image urls absolute
** Hostname and port configurable on a per-environment basis
* Makes link <code>href</code>s absolute
* Automatically adds proper html skeleton when missing (you don't have to create a layout for emails)[2]

fn2. This might be removed in a future version, though. You really ought to create a good layout and not let Roadie guess how you want to have it structured

h3. What about Sass / Less?

Sass is supported "by accident" as long as the stylesheets are generated and stored in the stylesheets directory. This is the default behavior from Sass. You are recommended to add a deploy task that generates the stylesheets to make sure that they are present at all times.

h2. Install

Roadie is officially supported in both Ruby 1.8.7 and 1.9.2.

Add the gem to Rails' Gemfile
<pre><code>gem 'roadie'</code></pre>

h2. Usage

Simply specify the <code>:css</code> option to mailer:

<pre><code>class Notifier < ActionMailer::Base
  default :css => :email, :from => 'support@mycompany.com'
  def registration_mail
    mail(:subject => 'Welcome Aboard', :to => 'someone@example.com')
  end

  def newsletter
    mail(:subject => 'Newsletter', :to => 'someone@example.com', :css => [:email, :newsletter])
  end
end</code></pre>
(you could also use the @defaults@ method in ActionMailer)

This will look for a css file called @email.css@ in your @public/stylesheets@ folder. The @css@ method can take either a string, a symbol or an array of both. You should pass the CSS filename without the ".css" extension.

h3. Image URL Correcting

If you have @default_url_options[:host]@ set in your mailer, then Roadie will do it's best to make the urls of images and in stylesheets absolute.

In @application.rb@:
<pre><code>class Application
  config.action_mailer.default_url_options = {:host => 'example.com'}
end</code></pre>

If you want to to be different depending on your environment, just set it in your environment's configuration instead.

h3. Ignoring stylesheets

By default, @style@ elements in the email document's @head@ are processed along with the stylesheets and removed from the @head@.

You can set a special <code>data-immutable="true"</code> attribute on @style@ tags you do not want to be processed and removed from the document's @head@. This is the place to put things like @:hover@ selectors that you want to have for email clients allowing them.

Style elements with <code>media="print"</code> are always ignored.

h2. Documentation

* "Online documentation for master":http://rubydoc.info/github/Mange/roadie/master/frames

h2. Bugs / TODO

* Improve overall performance
* Clean up stylesheet assignment code

h2. History and contributors

This gem was originally developed for Rails 2 use on "Purify":http://purifyapp.com under the name "MailStyle":https://www.github.com/purify/mail_style. However, the author stopped maintaining it and a fork took place to make it Rails 3 compatible.

The following people have contributed to the orignal gem:

* "Jim Neath":http://jimneath.org (Original author)
* "Lars Klevans":http://tastybyte.blogspot.com/
* "Jonas Grimfelt":http://github.com/grimen
* "Ben Johnson":http://www.binarylogic.com
* "Istvan Hoka":http://istvanhoka.com/
* "Voraz":http://blog.voraz.com.br

h2. License

(The MIT License)

Copyright &copy; 2009-2011

* "Jim Neath":http://jimneath.org
* Magnus Bergmark <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:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.