roadie 2.4.3 → 3.0.0.pre1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8dbb2ff6110e3730b2c4b818bbfa1724ad8912ea
+  data.tar.gz: fe0bf94a18e731475ee8bcf1e16d4d6cd6692071
+SHA512:
+  metadata.gz: 97d48f412f42884ab58afa39325178256bee9f81a5822e8415e746cd3181931048d982a607d12ec5cf11efd5ad11c439cf88f8165f05c7df781f02002641082c
+  data.tar.gz: bdb1604da3762385097b4e156fe38300580d4f3d899dda4d4ed66e5a8fd846405be0eb99df85e54c07cceda0f5a37f0af277773ecd3adf61050f0445ae6d947d

data/.gitignore

@@ -10,3 +10,6 @@ pkg
 Gemfile.lock
 doc
 tmp
+
+spec/railsapps/*/log
+spec/railsapps/*/tmp

data/.travis.yml

@@ -1,22 +1,17 @@
-bundler_args: --without guard
-before_install:
-  - gem install bundler --pre
-
+language: ruby
 rvm:
-  - 1.8.7
   - 1.9.3
   - 2.0.0
   - jruby
+  - rbx
+
+bundler_args: --without guard
+script: "rake"
 
-gemfile:
-  - gemfiles/rails_3.0.gemfile
-  - gemfiles/rails_3.1.gemfile
-  - gemfiles/rails_3.2.gemfile
-  - gemfiles/rails_4.0.gemfile
+env:
+  # Setup Coveralls
+  secure: "D1Uvi+a7W89k91zXVVwuuvv8O8qbDdyJ4g9i+3bGaSYySHxD8YuuG1QiQ4G/S2KLp/r3VPRpa8Wb1mSwb81tEBzXpzoZC7zSvgntPxRPhMg4zpodZ0O0AkK8/t1yZSkIe0V5sejFOQ1a5LJa3OorKBBjrqM5kPDOygTXtO3bQ6E="
 
 matrix:
-  exclude:
-    - rvm: 1.8.7
-      gemfile: gemfiles/rails_4.0.gemfile
   allow_failures:
-    - rvm: jruby
+    - rvm: rbx

data/.yardopts

@@ -1 +1 @@
---no-private
+--no-private --files Changelog.md

data/Changelog.md

@@ -1,15 +1,27 @@
 ### dev
 
-[full changelog](https://github.com/Mange/roadie/compare/v2.4.3...master)
-
-* Nothing yet
-
-### 2.4.3
-
-[full changelog](https://github.com/Mange/roadie/compare/v2.4.2...v2.4.3)
-
-* Bug fixes:
-  * Blacklist `:enabled`, `:disabled` and `:checked` pseudo functions - [Tyler Hunt (tylerhunt)](https://github.com/tylerhunt).
+[full changelog](https://github.com/Mange/roadie/compare/v2.4.2...master)
+
+Complete rewrite of most of the code and a new direction for the gem.
+
+* Breaking changes:
+  * Removed Rails support into a separate Gem (`roadie-rails`).
+  * Removed Sprockets dependency and AssetPipelineProvider.
+  * Changed the entire public API.
+  * Changed the API of custom providers.
+  * Dropped support for Ruby 1.8.7.
+  * Change `data-immutable` to `data-roadie-ignore`.
+* New features:
+  * Rewriting the URLs of `img[src]`.
+  * A way to inject stylesheets without having to adjust template.
+  * A before callback to compliment the after callback.
+* Enhancements:
+  * Better support for stylesheets using CSS fallbacks.
+    This means that styles like this is now inlined: `width: 5em; width: 3rem;`, while Roadie would previously remove the first of the two.
+    This sadly means that the HTML file will be much larger than before if you're using a non-optimized stylesheet (for example including your application stylesheet to the email). This was a bad idea even before this change, and this might get you to change.
+  * Using HTML5 doctype instead of XHTML
+  * Full support for JRuby
+  * Experimental support for Rubinius
 
 ### 2.4.2
 

data/Gemfile

@@ -1,6 +1,9 @@
 source 'https://rubygems.org'
 gemspec
 
+# Added here so it does not show up on the Gemspec; I only want it for CI builds
+gem 'coveralls', group: :test, require: nil
+
 group :guard do
   gem 'guard'
   gem 'guard-rspec'

data/Guardfile

@@ -1,7 +1,17 @@
-guard 'rspec' do
+rspec_options = {
+  cmd: 'rspec -f nested',
+  keep_failed: true,
+  all_after_pass: true,
+  all_on_start: true,
+  run_all: {cmd: 'rspec -f progress'}
+}
+
+guard 'rspec', rspec_options do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
 
+  watch(%r{lib/roadie/rspec/.*\.rb}) { "spec" }
+
   watch(%r{spec/support/.*\.rb}) { "spec" }
   watch('spec/spec_helper.rb')   { "spec" }
 end

data/README.md

@@ -1,11 +1,18 @@
 Roadie
 ======
 
-> Making HTML emails comfortable for the Rails rockstars
+[![Build history and status](https://secure.travis-ci.org/Mange/roadie.png)](http://travis-ci.org/#!/Mange/roadie)
+[![Code Climate](https://codeclimate.com/github/Mange/roadie.png)](https://codeclimate.com/github/Mange/roadie)
+[![Coverage Status](https://coveralls.io/repos/Mange/roadie/badge.png?branch=master)](https://coveralls.io/r/Mange/roadie?branch=master)
+[![Gem Version](https://badge.fury.io/rb/roadie.png)](http://badge.fury.io/rb/roadie)
+[![Dependency Status](https://gemnasium.com/Mange/roadie.png)](https://gemnasium.com/Mange/roadie)
+
+**Note: This README details the prerelease 3.0 version of Roadie. You might be using 2.0, which is much older and only for Rails.**
+
+> Making HTML emails comfortable for the Ruby 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 by inlining stylesheets and rewriting relative URLs for you inside your emails.
 
-If you want to have this in Rails 2, please see [MailStyle](https://www.github.com/purify/mail_style).
 
 How does it work?
 -----------------
@@ -18,226 +25,228 @@ Roadie also rewrites all relative URLs in the email to a absolute counterpart, m
 
 ¹: Of course, rules like `:hover` will not work by definition. Only static styles can be added.
 
-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 [almost all combinations of](http://travis-ci.org/#!/Mange/roadie):
-
-* Ruby:
-  * 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 ###
-
-This project follows [Semantic Versioning](http://semver.org/) and has been since version 1.0.0.
-
 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
   * Hostname and port configurable on a per-environment basis
-* Makes link `href`s absolute
+* 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)²
+* Allows you to inject stylesheets in a number of ways, at runtime
 
-²: 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
+²: 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.
 
-Install
--------
+Install & Usage
+---------------
 
-Add the gem to Rails' Gemfile
+[Add this gem to your Gemfile as recommended by Rubygems](http://rubygems.org/gems/roadie) and run `bundle install`.
 
 ```ruby
-gem 'roadie'
+gem 'roadie', '~> x.y.0'
 ```
 
-Configuring
------------
-
-Roadie listens to the following options (set in `Application.rb` or in your environment's configuration files:
+You may then create a new instance of a Roadie document:
 
-* `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.
+```ruby
+document = Roadie::Document.new "<html><body></body></html>"
+document.add_css "body { color: green; }"
+document.transform
+    # => "<html><body style=\"color:green;\"></body></html>"
+```
 
-Usage
------
+Your document instance can be configured several options:
 
-Just add a `<link rel="stylesheet" />` or `<style type="text/css"></style>` element inside your email layout and it will be inlined automatically.
+* `url_options` - Dictates how absolute URLs should be built.
+* `asset_providers` - A single (or list of) asset providers that are invoked when external CSS is referenced. See below.
+* `before_transformation` - A callback run before inlining starts.
+* `after_transformation` - A callback run after inlining is completed.
 
-**Note:** Do not use `stylesheet_link_tag` in your mail views. Just use a regular tag pointing to the logical asset name instead; e.g. `emails.css` instead of `emails-<SHA>.css`. This should hopefully be fixed in a later version. You are recommended to use the `:css` option to the mailer (detailed below) instead if you want to avoid problems with this.
+### Making URLs absolute ###
 
-You can also specify the `:css` option to mailer to have it inlined automatically without you having to make a layout:
+In order to make URLs absolute you need to first configure the URL options of the document.
 
 ```ruby
-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
+html = "... <a href="/about-us">Read more!</a> ..."
+document = Roadie::Document.new html
+document.url_options = {host: "myapp.com", protocol: "https"}
+document.transform
+  # => "... <a href="https://myapp.com/about-us">Read more!</a> ..."
 ```
 
-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.
+The following URLs will be rewritten for you:
+* `a[href]` (HTML)
+* `img[src]` (HTML)
+* `url()` (CSS)
 
-### Image URL rewriting ###
+### Referenced stylesheets ###
 
-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.
+By default, `style` and `link` elements in the email document's `head` are processed along with the stylesheets and removed from the `head`.
 
-In `application.rb`:
+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.
 
-```ruby
-class Application
-  config.action_mailer.default_url_options = {:host => 'example.com'}
-end
+Style and link elements with `media="print"` are also ignored.
+
+```html
+<head>
+  <link rel="stylesheet" type="text/css" href="/assets/emails/rock.css">         <!-- Will be inlined -->
+  <link rel="stylesheet" type="text/css" href="http://www.metal.org/metal.css">  <!-- Will NOT be inlined; absolute URL -->
+  <link rel="stylesheet" type="text/css" href="/assets/jazz.css" media="print">  <!-- Will NOT be inlined; print style -->
+  <link rel="stylesheet" type="text/css" href="/ambient.css" data-roadie-ignore> <!-- Will NOT be inlined; ignored -->
+  <style></style>                    <!-- Will be inlined -->
+  <style data-roadie-ignore></style> <!-- Will NOT be inlined; ignored -->
+</head>
 ```
 
-If you want to to be different depending on your environment, just set it in your environment's configuration instead.
+Roadie will use the given asset providers to look for the actual CSS that is referenced. If you don't change the default, it will use the `Roadie::FilesystemProvider` which looks for stylesheets on the filesystem, relative to the current working directory.
 
-### Ignoring stylesheets ###
+Example:
 
-By default, `style` and `link` elements in the email document's `head` are processed along with the stylesheets and removed from the `head`.
+```ruby
+# /home/user/foo/stylesheets/primary.css
+body { color: blue; }
+
+# /home/user/foo/script.rb
+html = <<-HTML
+<html>
+  <head>
+  <link rel="stylesheet" type="text/css" href="/stylesheets/primary.css">
+  </head>
+  <body>
+  </body>
+</html>
+HTML
+
+Dir.pwd # => "/home/user/foo"
+document = Roadie::Document.new html
+document.transform # =>
+                   # <!DOCTYPE html>
+                   # <html>
+                   #   <head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"></head>
+                   #   <body style="color:green;"></body>
+                   # </html>
+```
 
-You can set a special `data-immutable="true"` attribute on `style` and `link` 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.
+If a referenced stylesheet cannot be found, the `#transform` method will raise an `Roadie::CssNotFound` error. If you instead want to ignore missing stylesheets, you can use the `NullProvider`.
 
-Style and link elements with `media="print"` are always ignored.
+### Configuring providers ###
 
-### Inlining link tags ###
+You can write your own providers if you need very specific behavior for your app, or you can use the built-in providers.
 
-Any `link` element that is part of your email will be linked in. You can exclude them by setting `data-immutable` as you would on normal `style` elements. Linked stylesheets for print media is also ignored as you would expect.
+Included providers:
+* `FilesystemProvider` - Looks for files on the filesystem, relative to the given directory unless otherwise specified.
+* `ProviderList` – Wraps a list of other providers and searches them in order. The `asset_providers` setting is an instance of this. It behaves a lot like an array, so you can push, pop, shift and unshift to it.
+* `NullProvider` - Does not actually provide anything, it always finds empty stylesheets. Use this in tests or if you want to ignore stylesheets that cannot be found by your other providers.
 
-If the `link` tag uses an absolute URL to the stylesheet, it will not be inlined. Use a relative path instead:
+If you want to search several locations on the filesystem, just declare that:
 
-```html
-<head>
-  <link rel="stylesheet" type="text/css" href="/assets/emails/rock.css">             <!-- Will be inlined -->
-  <link rel="stylesheet" type="text/css" href="http://www.metal.org/metal.css">      <!-- Will NOT be inlined -->
-  <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>
+```ruby
+document.asset_providers = [
+  Roadie::FilesystemProvider.new(App.root.join("resources", "stylesheets")),
+  Roadie::FilesystemProvider.new(App.root.join("system", "uploads", "stylesheets")),
+]
 ```
 
-Writing your own provider
--------------------------
+If you want to ignore stylesheets that cannot be found instead of crashing, push the `NullProvider` to the end:
 
-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.
+```ruby
+document.asset_providers << Roadie::NullProvider.new
+```
 
-Example Subclassing the `AssetPipelineProvider`:
+### Writing your own provider ###
+
+Writing your own provider is also easy. You just need to provide:
+ * `#find_stylesheet(name)`, returning either a `Roadie::Stylesheet` or nil.
+ * `#find_stylesheet!(name)`, returning either a `Roadie::Stylesheet` or raising `Roadie::CssNotFound`.
 
 ```ruby
-# application.rb
-config.roadie.provider = UserAssetsProvider.new
-
-# lib/user_assets_provider.rb
-class UserAssetsProvider < Roadie::AssetPipelineProvider
-  def find(name)
-    user = User.find_by_name(name)
-    if user
-      user.custom_css
-    else
-      super
+class UserAssetsProvider
+  def initialize(user_collection)
+    @user_collection = user_collection
+  end
+
+  def find_stylesheet(name)
+    if name =~ %r{^/users/(\d+)\.css$}
+      user = @user_collection.find_user($1)
+      Roadie::Stylesheet.new("user #{user.id} stylesheet", user.stylesheet)
     end
   end
-end
-```
 
-Writing your own inliner
--------------------------
+  def find_stylesheet!(name)
+    find_stylesheet(name) or raise Roadie::CssNotFound.new(name)
+  end
 
-A custom inliner transforms an outgoing HTML email using application specific rules. The custom inliner is invoked after the default inliner.
+  # Instead of implementing #find_stylesheet!, you could also:
+  # include Roadie::AssetProvider
+end
 
-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.
+# Try to look for a user stylesheet first, then fall back to normal filesystem lookup.
+document.asset_providers = [
+  UserAssetsProvider.new(app),
+  Roadie::FilesystemProvider.new('./stylesheets'),
+]
+```
 
-Example for using lambda as custom inliner:
+You can test for compliance by using the built-in RSpec examples:
 
 ```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']}"
+require 'spec_helper'
+require 'roadie/rspec'
+
+describe MyOwnProvider do
+  # Will use the default `subject` (MyOwnProvider.new)
+  it_behaves_like "roadie asset provider", valid_name: "found.css", invalid_name: "does_not_exist.css"
+
+  # Extra setup just for these tests:
+  it_behaves_like "roadie asset provider", valid_name: "found.css", invalid_name: "does_not_exist.css" do
+    subject { MyOwnProvider.new(...) }
+    before { Whatever.stub ... }
   end
 end
 ```
 
-Example for using object as custom inliner:
+### Callbacks ###
 
-```ruby
-# application.rb
-config.roadie.after_inlining = PromotionInliner.new
+Callbacks allow you to do custom work on documents before they are inlined. The Nokogiri document tree is passed to the callable:
 
-# lib/product_link_inliner.rb
-class PromotionInliner
+```ruby
+class TrackNewsletterLinks
   def call(document)
-    document.css("a.product").each do |link|
-      fix_link link
-    end
+    document.css("a").each { |link| fix_link(link) }
   end
 
   def fix_link(link)
-    if link['class'] =~ /\bsale\b/
-      link['href'] = link['href'] + '?source=newsletter'
-    end
+    divider = (link['href'] =~ /?/ ? '&' : '?')
+    link['href'] = link['href'] + divider + 'source=newsletter'
   end
 end
+
+document.before_transformation = { |document| logger.debug "Inlining document with title #{document.at_css('head > title').try(:text)}" }
+document.after_transformation = TrackNewsletterLinks.new
 ```
 
-### Custom inliner scopes
+Build Status
+------------
 
-- **All HTML emails**
+Tested with [Travis CI](http://travis-ci.org) using:
 
-```ruby
-# application.rb. Custom inliner for all emails.
-config.roadie.after_inlining = PromotionInliner.new
-```
-- **All HTML emails sent by a mailer**
+* MRI 1.9.3
+* MRI 2.0.0
+* JRuby (latest)
+* Rubinius >= 2.1 (experimental)
 
-```ruby
-class MarketingMailer < ActionMailer::Base
-  # Custom inliner for all mailer methods.
-  default after_inlining: PromotionInliner.new
-end
-```
+[(Build status)](http://travis-ci.org/#!/Mange/roadie)
 
-- **All HTML emails sent by a specific mailer method**
+Let me know if you want any other VM supported officially.
 
-```ruby
-class UserMailer < ActionMailer::Base
-  def registration
-    # Custom inliner for registration emails
-    mail(after_inlining: MarketingMailer.new)
-  end
-end
-```
+Rubinius support is experimental since it it currently hindered by a Rubinius bug that will probably be fixed shortly.
 
-Bugs / TODO
------------
+### Versioning ###
 
-* Improve overall performance
-* Clean up stylesheet assignment code
-* Assets referenced with digest URLs should be findable
-  * Roadie should be able to have multiple asset providers in a specific order
+This project follows [Semantic Versioning](http://semver.org/) and has been since version 1.0.0.
 
 FAQ
 ---
@@ -262,18 +271,23 @@ Put any styles using them in a separate stylesheet and make sure it is ignored.
 Documentation
 -------------
 
-* [Online documentation for 2.3.0](http://rubydoc.info/gems/roadie/2.3.0/frames)
+* [Online documentation for gem](http://rubydoc.info/gems/roadie/frames)
 * [Online documentation for master](http://rubydoc.info/github/Mange/roadie/master/frames)
 * [Changelog](https://github.com/Mange/roadie/blob/master/Changelog.md)
 
 Running specs
 -------------
 
-Run specs for your current ruby against the latest compatible version of rails with `rake spec`. You can run against all supported combinations of ruby and rails by issuing `rake spec:all`.
+```bash
+bundle install
+rake
+```
 
 History and contributors
 ------------------------
 
+This gem was previously tied to Rails. It is now framework-agnostic and supports any type of HTML documents. If you want to use it with Rails, check out [roadie-rails](https://github.com/Mange/roadie-rails).
+
 Major contributors to Roadie:
 
 * [Arttu Tervo (arttu)](https://github.com/arttu) - Original Asset pipeline support
@@ -281,17 +295,6 @@ Major contributors to Roadie:
 
 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.
-
-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)
-
 License
 -------
 
@@ -299,8 +302,7 @@ License
 
 Copyright (c) 2009-2013
 
-* [Jim Neath](http://jimneath.org)
-* Magnus Bergmark <magnus.bergmark@gmail.com>
+* [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: