acts_as_sanitiled

= Acts as Sanitiled

This plugin, based on Chris Wanstrath's venerable acts_as_textiled, extends the automatic textiling functionality to sanitization as well using as its basis Ryan Grove's powerful yet simple Sanitize gem.

Important Development Status Update There used to be a paragraph here about why I liked this approach, but I've come to disagree with it over time. First, generally because the Rails 3 / rails_xss approach of tainted strings is ultimately better than the bandaid that this provided. But specifically because the cleverness of the solution outweighs its usefulness. It's a lot of hacking around internals simply to avoid calling a helper in a view, which while easy to forget, does not usually appear in all that many places or change all that often. Meanwhile, the internals of the model carry significantly more complexity, and suffer irredeemable breakages when you introduce something like I18n with Globalize2. Aside from that, any gains that were made are erased the minute you need to emit something other than HTML. With that in mind, I am still maintaining acts_as_sanitiled to the extent I need it, but I am no longer sanctioning the approach, and I would recommend deprecating your usage of the plugin.

== Requirements

The officially sanctioned requirements are:

• Sanitize >1.1.0 (prior versions had a whitespace issue)
• RedCloth >4.1.0
• ActiveRecord (tested on 2.3.10)

However there are a lot of little aberrations in output when you start mixing and matching versions of the various moving parts. Most recently I am working with REE 1.8.7, Sanitize 2.0.0, RedCloth 4.2.5, and Nokogiri 1.4.4, and I make sure specs pass with that mix. With other versions things should still work but the output might be slightly different (see known issues)

== Installation

gem install acts_as_sanitiled

== Known Issues

Line breaks sometime disappear from output which breaks the :plain output. This issue was not present under 1.8.6, Sanitize 1.1.0 and Nokogiri 1.4.0, but when I switched to 1.8.7 it appears. I never tracked down the cause, so keep an eye out for this one.

XHTML vs HTML output. This changed when I upgraded to Sanitize 2.0.0 and Nokogiri 1.4.4. This must have become the default somewhere, which is fine with me since HTML 5 is the future. Specs upgraded accordingly.

== Changes from acts_as_textiled

acts_as_sanitiled mostly maintains the API, but one noticeable difference is that it needs to expose the Sanitize config. Therefore acts_as_textiled use of a hash to provide per-column RedCloth configuration had to be replaced with Sanitize config. RedCloth options can still be passed as an array that applies to all fields listed.

The other big change is that acts_as_sanitiled uses Sanitize which outputs utf8 rather than HTML entities. For my own purposes this is preferable anyway, but it might give someone a few headaches getting encoding issues. My advice: take your lumps now and figure out your encoding pipelines.

== Usage

class Story < ActiveRecord::Base acts_as_sanitiled :body_text, :description end

story = Story.find(3) => #<Story:0x245fed8 ... >

story.description => "

This is cool.

"

story.description(:source) => "This is cool."

story.description(:plain) => "This is cool."

story.description = "I know!" => "I know!"

story.save => true

story.description => "

I know!

"

story.textiled = false => false

story.description => "I know!"

story.textiled = true => true

story.description => "

I know!

"

== Different Modes

Sanitize supports a detailed configuration hash describing what HTML is allowed (among other things). This can be passed at the end of the declaration. See the Sanitize docs for more information.

class Story < ActiveRecord::Base acts_as_sanitiled :body_text, :elements => ['em','strong','div'], :attributes => {'div' => ['class','id']} end

RedCloth supports different modes, such as :lite_mode. To use a mode on a specific attribute simply pass one or more options in an array after the field names. Like so:

class Story < ActiveRecord::Base acts_as_sanitiled :body_text, :description, [ :lite_mode ] end

Of course you can combine them as well:

class Story < ActiveRecord::Base acts_as_sanitiled :body_text, :description, [ :lite_mode ], :elements => ['a'], :add_attributes => {'a' => {'rel' => 'nofollow'}} end

Suppose you want to sanitize but not textilize:

class Story < ActiveRecord::Base acts_as_sanitized :body_text, :elements => ['br', 'p'] end

Or vice-versa:

class Story < ActiveRecord::Base acts_as_textilized :body_text, [ :lite_mode ] end

== Default options

Most likely you want to use the same options throughout your application, but perhaps not the same options I like. You can set the default options for both Sanitize and RedCloth like so.

ActsAsSanitiled.default_redcloth_options = [:no_span_caps] ActsAsSanitiled.default_sanitize_options = {:elements => ['em','strong','p','br']}

This should be done in +environment.rb+ or an initializer so it will run before your ActiveRecord classes are defined.

== form_for

Are you using form_for? If you are, you don't have to change any code at all.

<% form_for :story, @story do |f| %> Description:
<%= f.text_field :description %> <% end %>

You'll see the Textile plaintext in the text field. It Just Works.

== form tags

If you're being a bit unconvential, no worries. You can still get at your raw Textile like so:

Description:
<%= text_field_tag :description, @story.description(:source) %>

And there's always object.textiled = false, as demo'd above.

== Pre-fetching

acts_as_sanitiled locally caches rendered HTML once the attribute in question has been requested. Obviously this doesn't bode well for marshalling or caching.

If you need to force your object to build and cache HTML for all textiled attributes, call the +textilize+ method on your object.

If you're real crazy you can even do something like this:

class Story < ActiveRecord::Base acts_as_sanitiled :body_text, :description

def after_find
  textilize
end

end

All your Textile will now be ready to go in spiffy HTML format. But you probably won't need to do this.

Enjoy.

• By Chris Wanstrath [ chris[at]ozmm[dot]org ]
• Butchered and Sanitized by Gabe da Silveira [ gabe[at]websaviour[dot]com ]