README.md in roadie-2.0.0 vs README.md in roadie-2.1.0.pre1

- old
+ new

@@ -34,19 +34,15 @@ ### Versioning ### This project follows [Semtantic Versioning](http://semver.org/) and has been since version 1.0.0. -Two branches are currently in place: -* 2.x - Rails 3.1 -* 1.x - Rails 3.0 - -The 1.x branch will continue to be supported until it is deemed unnecessary by the author, but properly made pull requests will be accepted indefinitely. - Features -------- +* Supports Rails' Asset Pipeline and simple filesystem access out of the box +* You can add support for CSS from any place inside your apps * 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 @@ -56,26 +52,37 @@ ²: 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 ### What about Sass / Less? ### -Sass is supported "by accident" as long as the stylesheets are generated and stored in the asset directories. You are recommended to add a deploy task that generates the stylesheets to make sure that they are present at all times on the machine generating the emails. +Sass is supported as long as the stylesheets are generated and stored in the asset directories. You are recommended to add a deploy task that generates the stylesheets to make sure that they are present at all times on the machine generating the emails. Install ------- Add the gem to Rails' Gemfile ```ruby gem 'roadie' ``` +Configuring +----------- + +Roadie listens to the following options (set in `Application.rb` or in your environment's configuration files: + +* `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. + Usage ----- -Simply specify the `:css` option to mailer: +Just add a `<link rel="stylesheet" />` or `<style type="text/css"></style>` element inside your email layout and it will be inlined automatically. +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' def registration_mail @@ -125,10 +132,33 @@ <link rel="stylesheet" type="text/css" href="/assets/jazz.css" media="print"> <!-- Will NOT be inlined --> <link rel="stylesheet" type="text/css" href="/ambient.css" data-immutable> <!-- Will NOT be inlined --> </head> ``` +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. + +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 + end +end +``` + Bugs / TODO ----------- * Improve overall performance * Clean up stylesheet assignment code @@ -152,10 +182,10 @@ History and contributors ------------------------ Major contributors to Roadie: -* [Arttu Tervo (arttu)](https://github.com/arttu) - Asset pipeline support +* [Arttu Tervo (arttu)](https://github.com/arttu) - Original Asset pipeline 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.