README.md in roadie-2.3.4 vs README.md in roadie-2.4.0

- old
+ new

@@ -1,11 +1,11 @@ Roadie ====== > Making HTML emails comfortable for the Rails rockstars -Roadie tries to make sending HTML emails a little less painful in Rails 3 by inlining stylesheets and rewrite relative URLs for you. +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). How does it work? ----------------- @@ -21,20 +21,21 @@ Build Status ------------ [![Build history and status](https://secure.travis-ci.org/Mange/roadie.png)](http://travis-ci.org/#!/Mange/roadie) -Tested with [Travis CI](http://travis-ci.org) using the [all combinations of](http://travis-ci.org/#!/Mange/roadie): +Tested with [Travis CI](http://travis-ci.org) using [almost all combinations of](http://travis-ci.org/#!/Mange/roadie): * Ruby: - * 1.8.7 - * 1.9.2 - * 1.9.3 + * MRI 1.8.7 + * MRI 1.9.3 + * MRI 2.0.0 * Rails * 3.0 * 3.1 * 3.2 + * 4.0 Let me know if you want any other combination supported officially. ### Versioning ### @@ -72,10 +73,11 @@ * `config.roadie.enabled` - Set this to `false` to disable Roadie from working on your emails. Useful if you want to disable Roadie in some environments. * `config.action_mailer.default_url_options` - Used for making URLs absolute. * `config.assets.enabled` - If the asset pipeline is turned off, Roadie will default to searching for assets in `public/stylesheets`. * `config.roadie.provider` - Set the provider manually, ignoring all other options. Use for advanced cases, or when you have non-default paths or other options. +* `config.roadie.after_inlining` - Set a custom inliner for the HTML document. The custom inliner in invoked after the default inliner. Usage ----- Just add a `<link rel="stylesheet" />` or `<style type="text/css"></style>` element inside your email layout and it will be inlined automatically. @@ -84,23 +86,23 @@ You can also specify the `:css` option to mailer to have it inlined automatically without you having to make a layout: ```ruby class Notifier < ActionMailer::Base - default :css => :email, :from => 'support@mycompany.com' + 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]) + mail(:subject => 'Newsletter', :to => 'someone@example.com', :css => ['email', 'newsletter']) end end ``` -This will look for a css file called `email.css` in your assets. The `css` method can take either a string, a symbol or an array of both. The ".css" extension will be added automatically. +This will look for a css file called `email.css` in your assets. The `css` method can take either a string or an array of strings. The ".css" extension will be added automatically. ### Image URL rewriting ### 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. @@ -138,30 +140,99 @@ ``` Writing your own provider ------------------------- -A provider handles searching CSS files for you. Cou can easily create your own provider for your specific app by subclassing `Roadie::AssetProvider`. See the API documentation for information about how to build them. +A provider handles searching CSS files for you. You can easily create your own provider for your specific app by subclassing `Roadie::AssetProvider`. See the API documentation for information about how to build them. Example Subclassing the `AssetPipelineProvider`: ```ruby # application.rb config.roadie.provider = UserAssetsProvider.new # lib/user_assets_provider.rb class UserAssetsProvider < Roadie::AssetPipelineProvider def find(name) - super - rescue CSSFileNotFound user = User.find_by_name(name) - raise unless user - user.custom_css + if user + user.custom_css + else + super + end end end ``` +Writing your own inliner +------------------------- + +A custom inliner transforms an outgoing HTML email using application specific rules. The custom inliner is invoked after the default inliner. + +A custom inliner can be created using a `lambda` that accepts one parameter or an object that responds to the `call` method with one parameter. + +Example for using lambda as custom inliner: + +```ruby +# application.rb +config.roadie.after_inlining = lambda do |document| + document.css("a#new_user").each do |link| + link['href'] = "http://www.foo.com#{link['href']}" + end +end +``` + +Example for using object as custom inliner: + +```ruby +# application.rb +config.roadie.after_inlining = PromotionInliner.new + +# lib/product_link_inliner.rb +class PromotionInliner + def call(document) + document.css("a.product").each do |link| + fix_link link + end + end + + def fix_link(link) + if link['class'] =~ /\bsale\b/ + link['href'] = link['href'] + '?source=newsletter' + end + end +end +``` + +### Custom inliner scopes + +- **All HTML emails** + +```ruby +# application.rb. Custom inliner for all emails. +config.roadie.after_inlining = PromotionInliner.new +``` +- **All HTML emails sent by a mailer** + +```ruby +class MarketingMailer < ActionMailer::Base + # Custom inliner for all mailer methods. + default after_inlining: PromotionInliner.new +end +``` + +- **All HTML emails sent by a specific mailer method** + +```ruby +class UserMailer < ActionMailer::Base + def registration + # Custom inliner for registration emails + mail(after_inlining: MarketingMailer.new) + end +end +``` + Bugs / TODO ----------- * Improve overall performance * Clean up stylesheet assignment code @@ -204,14 +275,15 @@ ------------------------ Major contributors to Roadie: * [Arttu Tervo (arttu)](https://github.com/arttu) - Original Asset pipeline support +* [Ryunosuke SATO (tricknotes)](https://github.com/tricknotes) - Initial Rails 4 support You can [see all contributors](https://github.com/Mange/roadie/contributors) on GitHub. -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. +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/) @@ -223,10 +295,10 @@ License ------- (The MIT License) -Copyright (c) 2009-2011 +Copyright (c) 2009-2013 * [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: