my_cache["missing"] # => nil
```
**Warning:** The default `Hash` store will never be cleared, so make sure you don't allow the number of unique asset paths to grow too large in a single run. This is especially important if you run Roadie in a daemon that accepts arbritary documents, and/or if you use hash digests in your filenames. Making a new instance of `CachedProvider` will use a new `Hash` instance.
You can implement your own custom cache store by implementing the `[]` and `[]=` methods.
```ruby
class MyRoadieMemcacheStore
def initialize(memcache)
@memcache = memcache
end
def [](path)
css = memcache.read("assets/#{path}/css")
if css
name = memcache.read("assets/#{path}/name") || "cached #{path}"
Roadie::Stylesheet.new(name, css)
end
end
def []=(path, stylesheet)
memcache.write("assets/#{path}/css", stylesheet.to_s)
memcache.write("assets/#{path}/name", stylesheet.name)
stylesheet # You need to return the set Stylesheet
end
end
document.external_asset_providers = Roadie::CachedProvider.new(
document.external_asset_providers,
MyRoadieMemcacheStore.new(MemcacheClient.instance)
)
```
If you are using Rspec, you can test your implementation by using the shared examples for the "roadie cache store" role:
```ruby
require "roadie/rspec"
describe MyRoadieMemcacheStore do
let(:memcache_client) { MemcacheClient.instance }
subject { MyRoadieMemcacheStore.new(memcache_client) }
it_behaves_like "roadie cache store" do
before { memcache_client.clear }
end
end
```
#### `PathRewriterProvider` ####
With this provider, you can rewrite the paths that are searched in order to more easily support another provider. Examples could include rewriting absolute URLs into something that can be found on the filesystem, or to access internal hosts instead of external ones.
```ruby
filesystem = Roadie::FilesystemProvider.new("assets")
document.asset_providers << Roadie::PathRewriterProvider.new(filesystem) do |path|
path.sub('stylesheets', 'css').downcase
end
document.external_asset_providers = Roadie::PathRewriterProvider.new(filesystem) do |url|
if url =~ /myapp\.com/
URI.parse(url).path.sub(%r{^/assets}, '')
else
url
end
end
```
You can also wrap a list, for example to implement `external_asset_providers` by composing the normal `asset_providers`:
```ruby
document.external_asset_providers =
Roadie::PathRewriterProvider.new(document.asset_providers) do |url|
URI.parse(url).path
end
```
### Writing your own provider ###
Writing your own provider is also easy. You 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
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
def find_stylesheet!(name)
find_stylesheet(name) or raise Roadie::CssNotFound.new(name, "does not match a user stylesheet", self)
end
# Instead of implementing #find_stylesheet!, you could also:
# include Roadie::AssetProvider
# That will give you a default implementation without any error message. If
# you have multiple error cases, it's recommended that you implement
# #find_stylesheet! without #find_stylesheet and raise with an explanatory
# error message.
end
# 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'),
]
```
You can test for compliance by using the built-in RSpec examples:
```ruby
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 { stub_dependencies }
end
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
`
Hello world
```
When hovering over this ``, the color will not change as the `color: green` rule takes precedence. You can get it to work by adding `!important` to the `:hover` rule.
It would be foolish to try to automatically inject `!important` on every rule automatically, so this is a manual process.
#### Turning it off ####
If you'd rather skip this and have the styles not possible to inline disappear, you can turn off this feature by setting the `keep_uninlinable_css` option to false.
```ruby
document.keep_uninlinable_css = false
```
### Callbacks ###
Callbacks allow you to do custom work on documents before they are transformed. The Nokogiri document tree is passed to the callable along with the `Roadie::Document` instance:
```ruby
class TrackNewsletterLinks
def call(dom, document)
dom.css("a").each { |link| fix_link(link) }
end
def fix_link(link)
divider = (link['href'] =~ /?/ ? '&' : '?')
link['href'] = link['href'] + divider + 'source=newsletter'
end
end
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 `` if transforming a full document.
Partial documents does not have a ``.
Build Status
------------
Tested with [Travis CI](http://travis-ci.org) using:
* MRI 2.1
* MRI 2.2
* MRI 2.3
* MRI 2.4
* JRuby (latest)
* Rubinius (failures on Rubinius will not fail the build due to a long history of instability in `rbx`)
[(Build status)](http://travis-ci.org/#!/Mange/roadie)
Let me know if you want any other VM supported officially.
### Versioning ###
This project follows [Semantic Versioning](http://semver.org/) and has been since version 1.0.0.
FAQ
---
### Why is my markup changed in subtle ways?
Roadie uses Nokogiri to parse and regenerate the HTML of your email, which means that some unintentional changes might show up.
One example would be that Nokogiri might remove your ` `s in some cases.
Another example is Nokogiri's lack of HTML5 support, so certain new element might have spaces removed. I recommend you don't use HTML5 in emails anyway because of bad email client support (that includes web mail!).
### I'm getting segmentation faults (or other C-like problems)! What should I do? ###
Roadie uses Nokogiri to parse the HTML of your email, so any C-like problems like segfaults are likely in that end. The best way to fix this is to first upgrade libxml2 on your system and then reinstall Nokogiri.
Instructions on how to do this on most platforms, see [Nokogiri's official install guide](http://nokogiri.org/tutorials/installing_nokogiri.html).
### 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 `