README.md in sanitize-rails-0.8.1 vs README.md in sanitize-rails-0.9.1
- old
+ new
@@ -1,64 +1,94 @@
-Sanitize-Rails - sanitize .. on Rails. [](https://travis-ci.org/vjt/sanitize-rails)
-======================================
+# Sanitize-Rails - sanitize .. on Rails. [](https://travis-ci.org/vjt/sanitize-rails)
-Installation
-------------
+An easy bridge to integrate Ryan Grove's [HTML Whitelist Sanitizer][sanitize]
+in your Rails application.
-Gemfile:
+## Installation
- gem 'sanitize-rails', :require => 'sanitize/rails'
+`Gemfile`:
-Configuration
--------------
+ gem 'sanitize-rails', require: 'sanitize/rails'
-config/initializers/sanitizer.rb:
+## Configuration
+Pass the configuration to `Sanitize` calling `Sanitize::Rails.configure` in
+an initializer, say `config/initializers/sanitizer.rb`:
+
Sanitize::Rails.configure(
- :elements => [ ... ],
- :attribiutes => { ... },
+ elements: [ ... ],
+ attributes: { ... },
...
)
-There's an example in the `example/` directory.
+Check out the [example][] in the `example/` directory.
-Usage
------
+## Usage
-app/models/foo.rb:
+ActionView `sanitize` helper is transparently overriden to use the `Sanitize`
+gem.
- sanitizes :field
- sanitizes :some_other_field, :on => :create
- sanitizes :yet_another_field, :on => :save
+A `sanitize` helper is added to `ActiveRecord`, that installs on create/save
+callbacks that sanitize the given attributes before persisting them to the
+database. Example:
-ActionView `sanitize` helper is overriden to use
-the Sanitize gem - transparently.
+`app/models/foo.rb`:
-Testing
--------
+ class Foo < ActiveRecord::Base
+ sanitizes :description # on save by default
-Only Test::Unit for now - please write matchers
-and send a pull request :-)
+ sanitizes :body, on: :create
+ sanitizes :remarks, on: :save
+ end
-test/test\_helper:
+## Testing
+### RSpec
+
+`spec/spec_helper.rb`:
+
+ require 'sanitize/rails/matchers'
+
+in spec code:
+
+ describe Post do
+ # Simplest variant, single field and default values
+ it { should sanitize_field :title }
+
+ # Multiple fields
+ it { should sanitize_fields :title, :body }
+
+ # Specifing both text to sanitize and expected result
+ it { should sanitize_field(:title).replacing('©').with('©') }
+ end
+
+You should pass field names to matcher in the same way as you do with the
+`sanitize` call in the model, otherwise sanitize method won't be found in
+model.
+
+### Test::Unit
+
+`test/test_helper.rb:`
+
+ require 'sanitize/rails/test_helpers'
+
Sanitize::Rails::TestHelpers.setup(self,
- :invalid => 'some <a>string',
- :valid => 'some <a>string</a>'
+ invalid: 'some <a>string',
+ valid: 'some <a>string</a>'
)
your test:
- assert_sanitizes(Model, :field, :some_other_field)
+ assert_sanitizes Model, :field, :some_other_field
-Compatibility
--------------
+## Compatibility
-Tested with Rails 3.0 ~ 4.0 under Ruby 1.9 and 2.0.
+Tested with Rails 3.0 and :up: under Ruby 1.9.3 and :up:.
-License
--------
+## License
MIT
+## :smiley: Have fun!
-Have fun!
+[sanitize]: https://github.com/rgrove/sanitize
+[example]: https://github.com/vjt/sanitize-rails/blob/master/example/sanitizer.rb