activemodel 3.0.0.beta

data/lib/active_model/callbacks.rb

@@ -0,0 +1,133 @@
+require 'active_support/callbacks'
+
+module ActiveModel
+  # == Active Model Callbacks
+  # 
+  # Provides an interface for any class to have Active Record like callbacks.
+  # 
+  # Like the Active Record methods, the call back chain is aborted as soon as
+  # one of the methods in the chain returns false.
+  #
+  # First, extend ActiveModel::Callbacks from the class you are creating:
+  # 
+  #   class MyModel
+  #     extend ActiveModel::Callbacks
+  #   end
+  # 
+  # Then define a list of methods that you want call backs attached to:
+  # 
+  #   define_model_callbacks :create, :update
+  # 
+  # This will provide all three standard callbacks (before, around and after) around
+  # both the :create and :update methods. To implement, you need to wrap the methods 
+  # you want call backs on in a block so that the call backs get a chance to fire:
+  # 
+  #   def create
+  #     _run_create_callbacks do
+  #       # Your create action methods here
+  #     end
+  #   end
+  # 
+  # The _run_<method_name>_callbacks methods are dynamically created when you extend
+  # the <tt>ActiveModel::Callbacks</tt> module.
+  # 
+  # Then in your class, you can use the +before_create+, +after_create+ and +around_create+
+  # methods, just as you would in an Active Record module.
+  # 
+  #   before_create :action_before_create
+  # 
+  #   def action_before_create
+  #     # Your code here
+  #   end
+  # 
+  # You can choose not to have all three callbacks by passing an hash to the 
+  # define_model_callbacks method.
+  # 
+  #   define_model_callbacks :create, :only => :after, :before
+  # 
+  # Would only create the after_create and before_create callback methods in your
+  # class.
+  module Callbacks
+    def self.extended(base)
+      base.class_eval do
+        include ActiveSupport::Callbacks
+      end
+    end
+
+    # define_model_callbacks accepts all options define_callbacks does, in case you
+    # want to overwrite a default. Besides that, it also accepts an :only option, 
+    # where you can choose if you want all types (before, around or after) or just some.
+    #
+    #   define_model_callbacks :initializer, :only => :after
+    # 
+    # Note, the <tt>:only => <type></tt> hash will apply to all callbacks defined on
+    # that method call.  To get around this you can call the define_model_callbacks
+    # method as many times as you need.
+    # 
+    #   define_model_callbacks :create, :only => :after
+    #   define_model_callbacks :update, :only => :before
+    #   define_model_callbacks :destroy, :only => :around
+    # 
+    # Would create +after_create+, +before_update+ and +around_destroy+ methods only.
+    # 
+    # You can pass in a class to before_<type>, after_<type> and around_<type>, in which
+    # case the call back will call that class's <action>_<type> method passing the object
+    # that the callback is being called on.
+    # 
+    #   class MyModel
+    #     extend ActiveModel::Callbacks
+    #     define_model_callbacks :create
+    # 
+    #     before_create AnotherClass
+    #   end
+    # 
+    #   class AnotherClass
+    #     def self.before_create( obj )
+    #       # obj is the MyModel instance that the callback is being called on
+    #     end
+    #   end
+    #     
+    def define_model_callbacks(*callbacks)
+      options = callbacks.extract_options!
+      options = { :terminator => "result == false", :scope => [:kind, :name] }.merge(options)
+
+      types = Array(options.delete(:only))
+      types = [:before, :around, :after] if types.empty?
+
+      callbacks.each do |callback|
+        define_callbacks(callback, options)
+
+        types.each do |type|
+          send(:"_define_#{type}_model_callback", self, callback)
+        end
+      end
+    end
+
+    def _define_before_model_callback(klass, callback) #:nodoc:
+      klass.class_eval <<-CALLBACK, __FILE__, __LINE__
+        def self.before_#{callback}(*args, &block)
+          set_callback(:#{callback}, :before, *args, &block)
+        end
+      CALLBACK
+    end
+
+    def _define_around_model_callback(klass, callback) #:nodoc:
+      klass.class_eval <<-CALLBACK, __FILE__, __LINE__
+        def self.around_#{callback}(*args, &block)
+          set_callback(:#{callback}, :around, *args, &block)
+        end
+      CALLBACK
+    end
+
+    def _define_after_model_callback(klass, callback) #:nodoc:
+      klass.class_eval <<-CALLBACK, __FILE__, __LINE__
+        def self.after_#{callback}(*args, &block)
+          options = args.extract_options!
+          options[:prepend] = true
+          options[:if] = Array(options[:if]) << "!halted && value != false"
+          set_callback(:#{callback}, :after, *(args << options), &block)
+        end
+      CALLBACK
+    end
+  end
+end

data/lib/active_model/conversion.rb

@@ -0,0 +1,19 @@
+module ActiveModel
+  # If your object is already designed to implement all of the Active Model featurs
+  # include this module in your Class.
+  # 
+  #   class MyClass
+  #     include ActiveModel::Conversion
+  #   end
+  # 
+  # Returns self to the <tt>:to_model</tt> method.
+  # 
+  # If your model does not act like an Active Model object, then you should define
+  # <tt>:to_model</tt> yourself returning a proxy object that wraps your object
+  # with Active Model compliant methods.
+  module Conversion
+    def to_model
+      self
+    end
+  end
+end

data/lib/active_model/deprecated_error_methods.rb

@@ -0,0 +1,33 @@
+module ActiveModel
+  module DeprecatedErrorMethods
+    def on(attribute)
+      message = "Errors#on have been deprecated, use Errors#[] instead.\n"
+      message << "Also note that the behaviour of Errors#[] has changed. Errors#[] now always returns an Array. An empty Array is "
+      message << "returned when there are no errors on the specified attribute."
+      ActiveSupport::Deprecation.warn(message)
+
+      errors = self[attribute]
+      errors.size < 2 ? errors.first : errors
+    end
+
+    def on_base
+      ActiveSupport::Deprecation.warn "Errors#on_base have been deprecated, use Errors#[:base] instead"
+      ActiveSupport::Deprecation.silence { on(:base) }
+    end
+
+    def add_to_base(msg)
+      ActiveSupport::Deprecation.warn "Errors#add_to_base(msg) has been deprecated, use Errors#[:base] << msg instead"
+      self[:base] << msg
+    end
+
+    def invalid?(attribute)
+      ActiveSupport::Deprecation.warn "Errors#invalid?(attribute) has been deprecated, use Errors#[attribute].any? instead"
+      self[attribute].any?
+    end
+
+    def each_full
+      ActiveSupport::Deprecation.warn "Errors#each_full has been deprecated, use Errors#to_a.each instead"
+      to_a.each { |error| yield error }
+    end
+  end
+end

data/lib/active_model/dirty.rb

@@ -0,0 +1,164 @@
+module ActiveModel
+  # <tt>ActiveModel::Dirty</tt> provides a way to track changes in your
+  # object in the same way as ActiveRecord does.
+  # 
+  # The requirements to implement ActiveModel::Dirty are:
+  #
+  # * <tt>include ActiveModel::Dirty</tt> in your object
+  # * Call <tt>define_attribute_methods</tt> passing each method you want to track
+  # * Call <tt>attr_name_will_change!</tt> before each change to the tracked attribute
+  # 
+  # If you wish to also track previous changes on save or update, you need to add
+  # 
+  #   @previously_changed = changes
+  # 
+  # inside of your save or update method.
+  # 
+  # A minimal implementation could be:
+  # 
+  #   class Person
+  #   
+  #     include ActiveModel::Dirty
+  #   
+  #     define_attribute_methods [:name]
+  #   
+  #     def name
+  #       @name
+  #     end
+  #   
+  #     def name=(val)
+  #       name_will_change!
+  #       @name = val
+  #     end
+  #   
+  #     def save
+  #       @previously_changed = changes
+  #     end
+  #   
+  #   end
+  # 
+  # == Examples:
+  #
+  # A newly instantiated object is unchanged:
+  #   person = Person.find_by_name('Uncle Bob')
+  #   person.changed?       # => false
+  #
+  # Change the name:
+  #   person.name = 'Bob'
+  #   person.changed?       # => true
+  #   person.name_changed?  # => true
+  #   person.name_was       # => 'Uncle Bob'
+  #   person.name_change    # => ['Uncle Bob', 'Bob']
+  #   person.name = 'Bill'
+  #   person.name_change    # => ['Uncle Bob', 'Bill']
+  #
+  # Save the changes:
+  #   person.save
+  #   person.changed?       # => false
+  #   person.name_changed?  # => false
+  #
+  # Assigning the same value leaves the attribute unchanged:
+  #   person.name = 'Bill'
+  #   person.name_changed?  # => false
+  #   person.name_change    # => nil
+  #
+  # Which attributes have changed?
+  #   person.name = 'Bob'
+  #   person.changed        # => ['name']
+  #   person.changes        # => { 'name' => ['Bill', 'Bob'] }
+  #
+  # Resetting an attribute returns it to its original state:
+  #   person.reset_name!    # => 'Bill'
+  #   person.changed?       # => false
+  #   person.name_changed?  # => false
+  #   person.name           # => 'Bill'
+  #
+  # Before modifying an attribute in-place:
+  #   person.name_will_change!
+  #   person.name << 'y'
+  #   person.name_change    # => ['Bill', 'Billy']
+  module Dirty
+    extend ActiveSupport::Concern
+    include ActiveModel::AttributeMethods
+
+    included do
+      attribute_method_suffix '_changed?', '_change', '_will_change!', '_was'
+      attribute_method_affix :prefix => 'reset_', :suffix => '!'
+    end
+
+    # Do any attributes have unsaved changes?
+    #   person.changed? # => false
+    #   person.name = 'bob'
+    #   person.changed? # => true
+    def changed?
+      !changed_attributes.empty?
+    end
+
+    # List of attributes with unsaved changes.
+    #   person.changed # => []
+    #   person.name = 'bob'
+    #   person.changed # => ['name']
+    def changed
+      changed_attributes.keys
+    end
+
+    # Map of changed attrs => [original value, new value].
+    #   person.changes # => {}
+    #   person.name = 'bob'
+    #   person.changes # => { 'name' => ['bill', 'bob'] }
+    def changes
+      changed.inject({}) { |h, attr| h[attr] = attribute_change(attr); h }
+    end
+
+    # Map of attributes that were changed when the model was saved.
+    #   person.name # => 'bob'
+    #   person.name = 'robert'
+    #   person.save
+    #   person.previous_changes # => {'name' => ['bob, 'robert']}
+    def previous_changes
+      previously_changed_attributes
+    end
+
+    private
+      # Map of change <tt>attr => original value</tt>.
+      def changed_attributes
+        @changed_attributes ||= {}
+      end
+
+      # Map of fields that were changed when the model was saved
+      def previously_changed_attributes
+        @previously_changed || {}
+      end
+
+      # Handle <tt>*_changed?</tt> for +method_missing+.
+      def attribute_changed?(attr)
+        changed_attributes.include?(attr)
+      end
+
+      # Handle <tt>*_change</tt> for +method_missing+.
+      def attribute_change(attr)
+        [changed_attributes[attr], __send__(attr)] if attribute_changed?(attr)
+      end
+
+      # Handle <tt>*_was</tt> for +method_missing+.
+      def attribute_was(attr)
+        attribute_changed?(attr) ? changed_attributes[attr] : __send__(attr)
+      end
+
+      # Handle <tt>*_will_change!</tt> for +method_missing+.
+      def attribute_will_change!(attr)
+        begin
+          value = __send__(attr)
+          value = value.duplicable? ? value.clone : value
+        rescue TypeError, NoMethodError
+        end
+
+        changed_attributes[attr] = value
+      end
+
+      # Handle <tt>reset_*!</tt> for +method_missing+.
+      def reset_attribute!(attr)
+        __send__("#{attr}=", changed_attributes[attr]) if attribute_changed?(attr)
+      end
+  end
+end

data/lib/active_model/errors.rb

@@ -0,0 +1,277 @@
+require 'active_support/core_ext/string/inflections'
+require 'active_support/ordered_hash'
+
+module ActiveModel
+  # Provides a modified +OrderedHash+ that you can include in your object
+  # for handling error messages and interacting with Action Pack helpers.
+  # 
+  # A minimal implementation could be:
+  # 
+  #   class Person
+  #   
+  #     # Required dependency for ActiveModel::Errors
+  #     extend ActiveModel::Naming
+  # 
+  #     def initialize
+  #       @errors = ActiveModel::Errors.new(self)
+  #     end
+  #   
+  #     attr_accessor :name
+  #     attr_reader   :errors
+  #   
+  #     def validate!
+  #       errors.add(:name, "can not be nil") if name == nil
+  #     end
+  #   
+  #     # The following methods are needed to be minimally implemented
+  #
+  #     def read_attribute_for_validation(attr)
+  #       send(attr)
+  #     end
+  #   
+  #     def ErrorsPerson.human_attribute_name(attr, options = {})
+  #       attr
+  #     end
+  #   
+  #     def ErrorsPerson.lookup_ancestors
+  #       [self]
+  #     end
+  #   
+  #   end
+  # 
+  # The last three methods are required in your object for Errors to be
+  # able to generate error messages correctly and also handle multiple
+  # languages.  Of course, if you extend your object with ActiveModel::Translations
+  # you will not need to implement the last two.  Likewise, using
+  # ActiveModel::Validations will handle the validation related methods
+  # for you.
+  # 
+  # The above allows you to do:
+  # 
+  #   p = Person.new
+  #   p.validate!             # => ["can not be nil"]
+  #   p.errors.full_messages  # => ["name can not be nil"]
+  #   # etc..
+  class Errors < ActiveSupport::OrderedHash
+    include DeprecatedErrorMethods
+
+    # Pass in the instance of the object that is using the errors object.
+    # 
+    #   class Person
+    #     def initialize
+    #       @errors = ActiveModel::Errors.new(self)
+    #     end
+    #   end
+    def initialize(base)
+      @base = base
+      super()
+    end
+
+    alias_method :get, :[]
+    alias_method :set, :[]=
+
+    # When passed a symbol or a name of a method, returns an array of errors for the method.
+    # 
+    #   p.errors[:name]   #=> ["can not be nil"]
+    #   p.errors['name']  #=> ["can not be nil"]
+    def [](attribute)
+      if errors = get(attribute.to_sym)
+        errors
+      else
+        set(attribute.to_sym, [])
+      end
+    end
+
+    # Adds to the supplied attribute the supplied error message.
+    # 
+    #   p.errors[:name] = "must be set"
+    #   p.errors[:name] #=> ['must be set']
+    def []=(attribute, error)
+      self[attribute.to_sym] << error
+    end
+
+    # Iterates through each error key, value pair in the error messages hash.
+    # Yields the attribute and the error for that attribute.  If the attribute
+    # has more than one error message, yields once for each error message.
+    # 
+    #   p.errors.add(:name, "can't be blank")
+    #   p.errors.each do |attribute, errors_array|
+    #     # Will yield :name and "can't be blank"
+    #   end
+    # 
+    #   p.errors.add(:name, "must be specified")
+    #   p.errors.each do |attribute, errors_array|
+    #     # Will yield :name and "can't be blank"
+    #     # then yield :name and "must be specified"
+    #   end
+    def each
+      each_key do |attribute|
+        self[attribute].each { |error| yield attribute, error }
+      end
+    end
+
+    # Returns the number of error messages.
+    # 
+    #   p.errors.add(:name, "can't be blank")
+    #   p.errors.size #=> 1
+    #   p.errors.add(:name, "must be specified")
+    #   p.errors.size #=> 2
+    def size
+      values.flatten.size
+    end
+
+    # Returns an array of error messages, with the attribute name included
+    # 
+    #   p.errors.add(:name, "can't be blank")
+    #   p.errors.add(:name, "must be specified")
+    #   p.errors.to_a   #=>   ["name can't be blank", "name must be specified"]
+    def to_a
+      full_messages
+    end
+
+    # Returns the number of error messages.
+    #   p.errors.add(:name, "can't be blank")
+    #   p.errors.count #=> 1
+    #   p.errors.add(:name, "must be specified")
+    #   p.errors.count #=> 2
+    def count
+      to_a.size
+    end
+
+    # Returns an xml formatted representation of the Errors hash.
+    # 
+    #   p.errors.add(:name, "can't be blank")
+    #   p.errors.add(:name, "must be specified")
+    #   p.errors.to_xml   #=> Produces:
+    # 
+    #   #  <?xml version=\"1.0\" encoding=\"UTF-8\"?>
+    #   #  <errors>
+    #   #    <error>name can't be blank</error>
+    #   #    <error>name must be specified</error>
+    #   #  </errors>
+    def to_xml(options={})
+      require 'builder' unless defined? ::Builder
+      options[:root]    ||= "errors"
+      options[:indent]  ||= 2
+      options[:builder] ||= ::Builder::XmlMarkup.new(:indent => options[:indent])
+
+      options[:builder].instruct! unless options.delete(:skip_instruct)
+      options[:builder].errors do |e|
+        to_a.each { |error| e.error(error) }
+      end
+    end
+
+    # Adds an error message (+messsage+) to the +attribute+, which will be returned on a call to <tt>on(attribute)</tt>
+    # for the same attribute and ensure that this error object returns false when asked if <tt>empty?</tt>. More than one
+    # error can be added to the same +attribute+ in which case an array will be returned on a call to <tt>on(attribute)</tt>.
+    # If no +messsage+ is supplied, :invalid is assumed.
+    # 
+    # If +message+ is a Symbol, it will be translated, using the appropriate scope (see translate_error).
+    # If +message+ is a Proc, it will be called, allowing for things like Time.now to be used within an error
+    def add(attribute, message = nil, options = {})
+      message ||= :invalid
+      message = generate_message(attribute, message, options) if message.is_a?(Symbol)
+      message = message.call if message.is_a?(Proc)
+      self[attribute] << message
+    end
+
+    # Will add an error message to each of the attributes in +attributes+ that is empty.
+    def add_on_empty(attributes, custom_message = nil)
+      [attributes].flatten.each do |attribute|
+        value = @base.send(:read_attribute_for_validation, attribute)
+        is_empty = value.respond_to?(:empty?) ? value.empty? : false
+        add(attribute, :empty, :default => custom_message) unless !value.nil? && !is_empty
+      end
+    end
+
+    # Will add an error message to each of the attributes in +attributes+ that is blank (using Object#blank?).
+    def add_on_blank(attributes, custom_message = nil)
+      [attributes].flatten.each do |attribute|
+        value = @base.send(:read_attribute_for_validation, attribute)
+        add(attribute, :blank, :default => custom_message) if value.blank?
+      end
+    end
+
+    # Returns all the full error messages in an array.
+    #
+    #   class Company
+    #     validates_presence_of :name, :address, :email
+    #     validates_length_of :name, :in => 5..30
+    #   end
+    #
+    #   company = Company.create(:address => '123 First St.')
+    #   company.errors.full_messages # =>
+    #     ["Name is too short (minimum is 5 characters)", "Name can't be blank", "Address can't be blank"]
+    def full_messages
+      full_messages = []
+
+      each do |attribute, messages|
+        messages = Array(messages)
+        next if messages.empty?
+
+        if attribute == :base
+          messages.each {|m| full_messages << m }
+        else
+          attr_name = attribute.to_s.gsub('.', '_').humanize
+          attr_name = @base.class.human_attribute_name(attribute, :default => attr_name)
+          options = { :default => "{{attribute}} {{message}}", :attribute => attr_name }
+
+          messages.each do |m|
+            full_messages << I18n.t(:"errors.format", options.merge(:message => m))
+          end
+        end
+      end
+
+      full_messages
+    end
+
+    # Translates an error message in its default scope (<tt>activemodel.errors.messages</tt>).
+    # Error messages are first looked up in <tt>models.MODEL.attributes.ATTRIBUTE.MESSAGE</tt>, if it's not there,
+    # it's looked up in <tt>models.MODEL.MESSAGE</tt> and if that is not there it returns the translation of the
+    # default message (e.g. <tt>activemodel.errors.messages.MESSAGE</tt>). The translated model name,
+    # translated attribute name and the value are available for interpolation.
+    #
+    # When using inheritence in your models, it will check all the inherited models too, but only if the model itself
+    # hasn't been found. Say you have <tt>class Admin < User; end</tt> and you wanted the translation for the <tt>:blank</tt>
+    # error +message+ for the <tt>title</tt> +attribute+, it looks for these translations:
+    #
+    # <ol>
+    # <li><tt>activemodel.errors.models.admin.attributes.title.blank</tt></li>
+    # <li><tt>activemodel.errors.models.admin.blank</tt></li>
+    # <li><tt>activemodel.errors.models.user.attributes.title.blank</tt></li>
+    # <li><tt>activemodel.errors.models.user.blank</tt></li>
+    # <li>any default you provided through the +options+ hash (in the activemodel.errors scope)</li>
+    # <li><tt>activemodel.errors.messages.blank</tt></li>
+    # <li><tt>errors.attributes.title.blank</tt></li>
+    # <li><tt>errors.messages.blank</tt></li>
+    # </ol>
+    def generate_message(attribute, message = :invalid, options = {})
+      message, options[:default] = options[:default], message if options[:default].is_a?(Symbol)
+
+      defaults = @base.class.lookup_ancestors.map do |klass|
+        [ :"#{@base.class.i18n_scope}.errors.models.#{klass.model_name.underscore}.attributes.#{attribute}.#{message}",
+          :"#{@base.class.i18n_scope}.errors.models.#{klass.model_name.underscore}.#{message}" ]
+      end
+
+      defaults << options.delete(:default)
+      defaults << :"#{@base.class.i18n_scope}.errors.messages.#{message}"
+      defaults << :"errors.attributes.#{attribute}.#{message}"
+      defaults << :"errors.messages.#{message}"
+
+      defaults.compact!
+      defaults.flatten!
+
+      key = defaults.shift
+      value = @base.send(:read_attribute_for_validation, attribute)
+
+      options = {
+        :default => defaults,
+        :model => @base.class.model_name.human,
+        :attribute => @base.class.human_attribute_name(attribute),
+        :value => value
+      }.merge(options)
+
+      I18n.translate(key, options)
+    end
+  end
+end