README.md in affairs_of_state-0.1.1 vs README.md in affairs_of_state-0.1.2

- old
+ new

@@ -1,73 +1,103 @@ # Affairs of State +[![Build Status](https://travis-ci.org/kmcphillips/affairs_of_state.png?branch=master)](https://travis-ci.org/kmcphillips/affairs_of_state) + You have an Active Record model. It nees to have multiple states, but not complex rules. This gem gives you validation, easy check and change methods, and a single configuration line. ## Installation Add this line to your application's Gemfile: - gem 'affairs_of_state' +```ruby +gem 'affairs_of_state' +``` And then execute: - $ bundle +```ruby +$ bundle +``` Or install it yourself as: - $ gem install affairs_of_state +```ruby +$ gem install affairs_of_state +``` ## Usage -The gem assumes you have a string column named "status" on your model: +The gem assumes you have a string column named `status` on your model: - add_column :model_name, :status, :default => "active" +```ruby +add_column :model_name, :status, :default => "active" +``` Then you just list your states in the model: - affairs_of_state :active, :inactive +```ruby +affairs_of_state :active, :inactive +``` -If you'd like to use another column, lets say "state", pass it in as a configuration option: +If you'd like to use another column, lets say `state`, pass it in as a configuration option: - affairs_of_state :active, :inactive, :column => :state +```ruby +affairs_of_state :active, :inactive, :column => :state +``` You can also turn off validation: - affairs_of_state :active, :inactive, :allow_blank => true +```ruby +affairs_of_state :active, :inactive, :allow_blank => true +``` Or give it a long list of statuses: - affairs_of_state :ordered, :cancelled, :shipped, :lost, :in_transit +```ruby +affairs_of_state :ordered, :cancelled, :shipped, :lost, :in_transit +``` You can also pass a proc or a method name symbol to the :if option to bypass validation: - affairs_of_state :active, :inactive, :if => lambda{|object| only_validate_if_this_is_true(object) } - # or - affairs_of_state :active, :inactive, :if => :only_validate_if_this_method_returns_true +```ruby +affairs_of_state :active, :inactive, :if => lambda{|object| only_validate_if_this_is_true(object) } +# or +affairs_of_state :active, :inactive, :if => :only_validate_if_this_method_returns_true +``` ## Methods The gem provides methods for checking and setting your status. The question mark method returns a boolean, and the bang method changes to that status. Lets assume you have "active" and "cancelled" as defined status: - widget = Widget.first +```ruby +widget = Widget.first +widget.cancelled! if widget.active? +``` - widget.cancelled! if widget.active? - You can also access all your statuses on the model like so: - Widget::STATUES # -> ["active", "cancelled"] +```ruby +Widget::STATUSES # -> ["active", "cancelled"] +``` It also provides scopes automagically: - Widget.active +```ruby +Widget.active +Widget.cancelled +``` - Widget.cancelled +For select inputs in forms there is a convenience method that returns all states in the format expected by `options_for_select` +```ruby +<%= f.select :status, options_for_select(Widget.statuses_for_select) %> +``` -## "But I want callbacks and validations and other things." +## "But I want callbacks and validations etc." + Then this gem isn't for you. Consider: https://github.com/rubyist/aasm https://github.com/pluginaweek/state_machine @@ -75,12 +105,15 @@ ## Tests Just run rspec: - rspec +``` +rspec +``` ## The usual Author: Kevin McPhillips - github@kevinmcphillips.ca +License: [MIT](http://opensource.org/licenses/MIT)