= Symbolize attribute values

This plugin introduces an easy way to use symbols for values of attributes. Symbolized attributes return a ruby symbol (or nil) as their value
and can be set using :symbols or "strings".

== Install

=== Gem

    gem install symbolize


=== Mongoid

    gem "symbolize", :require => "symbolize/mongoid"


=== ActiveRecord

    gem "symbolize", :require => "symbolize/active_record"



== About

Simply add "symbolize :attr_name" to your model class, and the specified
attribute will return symbol values and can be set using smbols (setting
string values will still work, which is important when using forms).

On SQL-based DBs, an attribute to symbolize should be a string (varchar) column in the database.



== Usage

Add "symbolize :attr_name" to your model class. You may also want to add
validates_inclusion_of to restrict the possible values (just like an enum).

    # ActiveRecord
    class User < ActiveRecord::Base

    # Mongoid
    class User
      include Mongoid::Document
      include Mongoid::Symbolize

      symbolize :gender, :in => [:female, :male], :scopes => true
      symbolize :so, :in => {
        :linux   => "Linux",
        :mac     => "Mac OS X"
      }, :scopes => true

      # Allow blank
      symbolize :gui,  :in => [:gnome, :kde, :xfce], :allow_blank => true

      # Don`t i18n
      symbolize :browser, :in => [:firefox, :opera], :i18n => false, :methods => true

      # Scopes
      symbolize :angry, :in => [true, false], :scopes => true

      # Don`t validate
      symbolize :lang, :in => [:ruby, :c, :erlang], :validate => false

      # Default
      symbolize :kind, :in => [:admin, :manager, :user], :default => :admin
  end


=== in/within

The values allowed on the enum field, you can provide a hash with
{:value => "Human text"} or an array of keys to be i18n eval (or not).
Booleans are also supported. See below.

allow_(blank|nil): What you expect.


=== validate

Set to false to avoid the validation of the input.
Useful for a dropdown with an "other" option textfield.


=== method

If you provide the method option, some fancy boolean methods will be added:
In our User example, browser has this option, so you can do:

    @user.firefox?
    @user.opera?


=== Booleans

Its possible to use boolean fields also.
  symbolize :switch, :in => [true, false]

  ...
    switch:
      "true": On
      "false": Off
      "nil": Unknown


=== i18n

If you don`t provide a hash with values, it will try i18n:

    activerecord:
      attributes:
        user:
          enums:
            gui:
              gnome: Gnome Desktop Enviroment
              kde: K Desktop Enviroment
              xfce: XFCE4
            gender:
              female: Girl
              male: Boy

You can skip i18n lookup with :i18n => false
  symbolize :gender, :in => [:female, :male], :i18n => false


=== scopes (BETA)

If you provide the scopes option, some fancy named scopes will be added:
In our User example, gender has this option, so you can do:

    User.female => User.find(:all, :conditions => { :gender => :female })

You can chain named scopes as well:

    User.female.mac => User.find(:all, :conditions => { :gender => :female, :so => :mac })

For boolean colums you can use

    User.angry     => User.find(:all, :conditions => { :angry => true })
    User.not_angry => User.find(:all, :conditions => { :angry => false })

    ( or with_[attribute] and without_[attribute] )


=== default (BETA)

As the name suggest, the symbol you choose as default will be set in new objects automatically.

     User.new.kind # Will print :admin


== Examples

  u = User.find_by_name('Anna')   # => #<User Anna>
  u.gender                        # => :female

  u = User.find_by_gender(:male)  # => #<User Bob>
  u.gender                        # => :male

  u = User.find(:all, :conditions => { :gender => :female })
  u = User.female

  u = User.new(:name => 'ET', :gender => :unknown)
  u.save                          # => validation fails

== Rails Form Example

    class Coffee
      symbolize :genetic, :in => [:arabica, :robusta, :blend]
    end

    form_for(@coffee) do |f|
      = f.label :genetic
      = f.select :genetic, Coffee.get_genetic_values

== Model Helpers


You may call `Class.get_attr_values` anywhere to get a nice array.
Works nice with dropdowns. Examples:


Somewhere on a view:

    = select_tag :kind, Coffee.get_genetic_values


== View Helpers

  <% form_for @user do |f| %>
    <%= f.radio_sym "gender" %>
    <!-- Alphabetic order -->
    <%= f.select_sym "so" %>
    <!-- Fixed order -->
    <%= f.select_sym "office" %>
  <% end %>

  output:

  <form action="users/1" method="post">
    <div style="margin:0;padding:0">...</div>
    <label>Female <input id="user_gender_female" name="user[gender]" type="radio" value="female"></label>
    <label>Male <input checked="checked" id="user_gender_male" name="user[gender]" type="radio" value="male" ></label>
    <!-- Alphabetic order -->
    <select id="user_so" name="post[so]">
      <option value="linux" selected="selected">Linux</option>
      <option value="mac">Mac OS X</option>
      <option value="windows">Windows XP</option>
    </select>
    <!-- Fixed order -->
    <select id="user_office" name="post[office]">
      <option value="kde" selected="selected">Koffice</option>
      <option value="ms">Microsoft Office</option>
      <option value="open">Open Office</option>
    </select>
  </form>



=== Plugin:

Try at your own risk.

  rails plugin install git://github.com/nofxx/symbolize.git


== Rails 3.1 (beta)

Specs pass with rails 3, but a scope :public == fail.


== Specs

Run the adapter independently:

    $ rspec spec/symbolize/mongoid_spec.rb
    $ rspec spec/symbolize/active_record_spec.rb


== Notes

This fork:
http://github.com/nofxx/symbolize


Forked from:
http://github.com/nuxlli/activerecord_symbolize


Initial work:
I've been using this for quite some time and made it a rails plugin now. More
background iinformation can be found at
http://zargony.com/2007/09/07/symbolize-attribute-values-in-activerecord


Copyright (c) 2007-2008 Andreas Neuhaus, released under the MIT license