=MultiFieldDate

== License
See LICENSE file

== Description
For use with tables that require that incomplete dates be allowed (e.g., just the year and month
or just the month and day).
Requires that the table have four fields: year, month, day, and full date.
When the year, month, and day fields are present, the full date field is updated.
 
== Usage 
=== QuickStart
There are two ways to use this plugin:
  1. acts_as_multi_field_date
  2. multi_field_date

acts_as_multi_field_date only allows one date_field per model. e.g.,

class Birth < ActiveRecord::Base
  acts_as_multi_field_date :date_field => 'birth_date'
  #Assumes year, month, and day fields are 'year', 'month', and 'day' by default.
  #Can be changed: 
  # acts_as_multi_field_date :date_field => 'birth_date', :day_field => 'bday'
end

multi_field_date, on the other hand, allows multiple dates in a model, e.g.,

class Person < ActiveRecord::Base
  multi_field_date :birth, :date_field => 'birth_date', :year_field => 'birth_year',
    :month_field => 'birth_month', :day_field => 'birth_day'
  multi_field_date :death, :date_field => 'death_date', :year_field => 'death_year',
    :month_field => 'death_month', :day_field => 'death_day'
end

Also see: ActiveRecord::Acts::MultiFieldDate::ClassMethods#multi_field_date
     and: ActiveRecord::Acts::ActsAsMultiFieldDate::ClassMethods#acts_multi_field_date
=== Installation
<tt>script/plugin install http://rails-multifielddate-plugin.googlecode.com/svn/plugins/multi_field_date</tt>

== ActsAsMultiFieldDate
=== Configuration

Example migration:
  create_table "births", :force => true do |t|
    t.date     "birth_date"
    t.integer  "year"
    t.integer  "month"
    t.integer  "day"
  end
  
In your model, specify the date field as acts_as_multi_field_date:
      class Birth 
         acts_as_multi_field_date :birth, :date_field => 'birth_date'
      end
    
=== Example
       birth = Birth.create(:birth_year => 1979) 
       birth.save
       birth       # => #<Birth id: 2, year: 1979, month: nil, day: nil, birth_date: nil>
       birth.year  # => 1979
       birth.birth_date  # => nil 
       birth.month = 10 
       birth.save
       birth       # => #<Birth id: 2, year: 1979, month: 10, day: nil, birth_date: nil>
       birth.date_text # => "1979-10-??"
       birth.day = 20 
       #note the birth_date is still nil:
       birth       # => #<Birth id: 2, year: 1979, month: 10, day: 20, birth_date: nil>
       birth.save
       #birth_date is updated after save:
       birth       # => #<Birth id: 2, year: 1979, month: 10, day: 20, birth_date: "1979-10-20">
       birth.year = 1970
       birth.save
       birth.birth_date # => "1970-10-20"


== MultiFieldDate
=== Configuration

Example migration:
  create_table "people", :force => true do |t|
    t.string   "name"
    t.date     "birth_date"
    t.integer  "birth_year"
    t.integer  "birth_month"
    t.integer  "birth_day"
    t.date     "deceased_date"
    t.integer  "deceased_year"
    t.integer  "deceased_month"
    t.integer  "deceased_day"
  end
  
In your model, specify one or more sets of date fields as multi_field_date:
      class Person
         multi_field_date :birth, :date_field => 'birth_date', :year_field => 'birth_year', 
           :month_field => 'birth_month', :day_field => 'birth_day'
         multi_field_date :death, :date_field => 'deceased_date', :year_field => 'deceased_year', 
           :month_field => 'deceased_month', :day_field => 'deceased_day'
      end
    
=== Example
       person = Person.create(:name => 'Joe Blow', :birth_year => 1979) 
       person.birth       # => #<MultiFieldDate:0x25760d8 @year=1979, @date=nil, @day=nil, @month=nil>
       person.save
       person.birth.year  # => 1979
       person.birth.date  # => nil 
       person.birth_month = 10 
       person.save
       person.birth       # => #<MultiFieldDate:0x25760d8 @year=1979, @date=nil, @day=nil, @month=10>
       person.birth_day = 20 
       person.save
       person.birth       # => #<MultiFieldDate:0x25760d8 @year=1979, @date=nil, @day=nil, @month=10>
       person.save        
       person.birth       # => #<MultiFieldDate:0x25760d8 @year=1979, @date=Sat, 20 Oct 1979, @day=20, @month=10>
       person.birth.date  # => Sat, 20 Oct 1979
updates model's birth_date attribute:
       person.birth_month = nil
       person.save
       person.birth.date  # => nil
for what it's worth, you can also access month, day, year through MultiFieldDate object:
       person.birth_month = 10
       person.save
       person.birth.month # => 10
       
    
Author:: Bryan Donovan 
Date::   January, 2008