activemodel 3.0.pre → 3.0.0.rc

data/lib/active_model/callbacks.rb

@@ -0,0 +1,134 @@
+require 'active_support/core_ext/array/wrap'
+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 callback 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 callbacks attached to:
+  # 
+  #   define_model_callbacks :create, :update
+  # 
+  # This will provide all three standard callbacks (before, around and after) for
+  # both the :create and :update methods. To implement, you need to wrap the methods 
+  # you want callbacks on in a block so that the callbacks 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 a 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 the same 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 callback 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.wrap(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__ + 1
+        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__ + 1
+        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__ + 1
+        def self.after_#{callback}(*args, &block)
+          options = args.extract_options!
+          options[:prepend] = true
+          options[:if] = Array.wrap(options[:if]) << "!halted && value != false"
+          set_callback(:#{callback}, :after, *(args << options), &block)
+        end
+      CALLBACK
+    end
+  end
+end

data/lib/active_model/conversion.rb

@@ -1,8 +1,48 @@
 module ActiveModel
-  # Include ActiveModel::Conversion if your object "acts like an ActiveModel model".
+  # == Active Model Conversions
+  #
+  # Handles default conversions: to_model, to_key and to_param.
+  #
+  # == Example
+  #
+  # Let's take for example this non persisted object.
+  #
+  #   class ContactMessage
+  #     include ActiveModel::Conversion
+  #
+  #     # ContactMessage are never persisted in the DB
+  #     def persisted?
+  #       false
+  #     end
+  #   end
+  #
+  #   cm = ContactMessage.new
+  #   cm.to_model == self #=> true
+  #   cm.to_key           #=> nil
+  #   cm.to_param         #=> nil
+  #
   module Conversion
+    # If your object is already designed to implement all of the Active Model 
+    # you can use the default to_model implementation, which simply returns 
+    # self.
+    # 
+    # 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.
     def to_model
       self
     end
+
+    # Returns an Enumerable of all (primary) key attributes or nil if 
+    # persisted? is false
+    def to_key
+      persisted? ? [id] : nil
+    end
+
+    # Returns a string representing the object's key suitable for use in URLs,
+    # or nil if persisted? is false
+    def to_param
+      to_key ? to_key.join('-') : nil
+    end
   end
 end

data/lib/active_model/deprecated_error_methods.rb

@@ -16,7 +16,7 @@ module ActiveModel
     end
 
     def add_to_base(msg)
-      ActiveSupport::Deprecation.warn "Errors#add_to_base(msg) has been deprecated, use Errors#[:base] << msg instead"
+      ActiveSupport::Deprecation.warn "Errors#add_to_base(msg) has been deprecated, use Errors#add(:base, msg) instead"
       self[:base] << msg
     end
 

data/lib/active_model/dirty.rb

@@ -1,5 +1,53 @@
+require 'active_model/attribute_methods'
+require 'active_support/concern'
+require 'active_support/hash_with_indifferent_access'
+require 'active_support/core_ext/object/duplicable'
+
 module ActiveModel
-  # Track unsaved attribute changes.
+  # == Active Model Dirty
+  #
+  # Provides a way to track changes in your object in the same way as 
+  # Active Record does.
+  # 
+  # The requirements to implement ActiveModel::Dirty are to:
+  #
+  # * <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')
@@ -69,7 +117,7 @@ module ActiveModel
     #   person.name = 'bob'
     #   person.changes # => { 'name' => ['bill', 'bob'] }
     def changes
-      changed.inject({}) { |h, attr| h[attr] = attribute_change(attr); h }
+      changed.inject(HashWithIndifferentAccess.new){ |h, attr| h[attr] = attribute_change(attr); h }
     end
 
     # Map of attributes that were changed when the model was saved.
@@ -78,19 +126,15 @@ module ActiveModel
     #   person.save
     #   person.previous_changes # => {'name' => ['bob, 'robert']}
     def previous_changes
-      previously_changed_attributes
+      @previously_changed
     end
 
-    private
-      # Map of change <tt>attr => original value</tt>.
-      def changed_attributes
-        @changed_attributes ||= {}
-      end
+    # 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
+    private
 
       # Handle <tt>*_changed?</tt> for +method_missing+.
       def attribute_changed?(attr)

data/lib/active_model/errors.rb

@@ -1,10 +1,77 @@
+# -*- coding: utf-8 -*-
+
+require 'active_support/core_ext/array/wrap'
+require 'active_support/core_ext/array/conversions'
 require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/hash/reverse_merge'
 require 'active_support/ordered_hash'
 
 module ActiveModel
+  # == Active Model Errors
+  #
+  # 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
 
+    CALLBACKS_OPTIONS = [:if, :unless, :on, :allow_nil, :allow_blank]
+
+    # 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()
@@ -13,6 +80,11 @@ module ActiveModel
     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
@@ -21,65 +93,134 @@ module ActiveModel
       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 true if there are any errors, false if not.
+    def empty?
+      all? { |k, v| v && v.empty? }
+    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
+      to_a.to_xml options.reverse_merge(:root => "errors", :skip_types => true)
+    end
+
+    # Returns an array as JSON representation for this object.
+    def as_json(options=nil)
+      to_a
     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).
+    # Adds +message+ to the error messages on +attribute+, which will be returned on a call to
+    # <tt>on(attribute)</tt> for the same attribute. 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 +message+ is supplied, <tt>:invalid</tt> 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 <tt>Time.now</tt> 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)
+
+      if message.is_a?(Symbol)
+        message = generate_message(attribute, message, options.except(*CALLBACKS_OPTIONS))
+      elsif message.is_a?(Proc)
+        message = message.call
+      end
+
       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)
+    def add_on_empty(attributes, options = {})
+      if options && !options.is_a?(Hash)
+        options = { :message => options }
+        ActiveSupport::Deprecation.warn \
+          "ActiveModel::Errors#add_on_empty(attributes, custom_message) has been deprecated.\n" +
+          "Instead of passing a custom_message pass an options Hash { :message => custom_message }."
+      end
+
       [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
+        add(attribute, :empty, options) if 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)
+    def add_on_blank(attributes, options = {})
+      if options && !options.is_a?(Hash)
+        options = { :message => options }
+        ActiveSupport::Deprecation.warn \
+          "ActiveModel::Errors#add_on_blank(attributes, custom_message) has been deprecated.\n" +
+          "Instead of passing a custom_message pass an options Hash { :message => custom_message }."
+      end
+
       [attributes].flatten.each do |attribute|
         value = @base.send(:read_attribute_for_validation, attribute)
-        add(attribute, :blank, :default => custom_message) if value.blank?
+        add(attribute, :blank, options) if value.blank?
       end
     end
 
@@ -93,7 +234,7 @@ module ActiveModel
     #   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(options = {})
+    def full_messages
       full_messages = []
 
       each do |attribute, messages|
@@ -103,10 +244,12 @@ module ActiveModel
         if attribute == :base
           messages.each {|m| full_messages << m }
         else
-          attr_name = attribute.to_s.humanize
-          prefix = attr_name + I18n.t('activemodel.errors.format.separator', :default => ' ')
+          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 <<  "#{prefix}#{m}"
+            full_messages << I18n.t(:"errors.format", options.merge(:message => m))
           end
         end
       end
@@ -114,46 +257,62 @@ module ActiveModel
       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,
+    # 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 also, 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:
+    # When using inheritance 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><tt>activemodel.errors.messages.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)
+    def generate_message(attribute, type = :invalid, options = {})
+      type = options.delete(:message) if options[:message].is_a?(Symbol)
 
-      klass_ancestors = [@base.class]
-      klass_ancestors += @base.class.ancestors.reject {|x| x.is_a?(Module)}
+      if options[:default]
+        ActiveSupport::Deprecation.warn \
+          "ActiveModel::Errors#generate_message(attributes, custom_message) has been deprecated.\n" +
+          "Use ActiveModel::Errors#generate_message(attributes, :message => 'your message') instead."
+        options[:message] = options.delete(:default)
+      end
 
-      defaults = klass_ancestors.map do |klass|
-        [ :"models.#{klass.name.underscore}.attributes.#{attribute}.#{message}",
-          :"models.#{klass.name.underscore}.#{message}" ]
+      defaults = @base.class.lookup_ancestors.map do |klass|
+        [ :"#{@base.class.i18n_scope}.errors.models.#{klass.model_name.underscore}.attributes.#{attribute}.#{type}",
+          :"#{@base.class.i18n_scope}.errors.models.#{klass.model_name.underscore}.#{type}" ]
       end
 
-      defaults << options.delete(:default)
-      defaults = defaults.compact.flatten << :"messages.#{message}"
+      defaults << options.delete(:message)
+      defaults << :"#{@base.class.i18n_scope}.errors.messages.#{type}"
+      defaults << :"errors.attributes.#{attribute}.#{type}"
+      defaults << :"errors.messages.#{type}"
+
+      defaults.compact!
+      defaults.flatten!
 
       key = defaults.shift
-      value = @base.send(:read_attribute_for_validation, attribute)
+      value = (attribute != :base ? @base.send(:read_attribute_for_validation, attribute) : nil)
 
-      options = { :default => defaults,
-        :model => @base.class.name.humanize,
-        :attribute => attribute.to_s.humanize,
-        :value => value,
-        :scope => [:activemodel, :errors]
+      options = {
+        :default => defaults,
+        :model => @base.class.model_name.human,
+        :attribute => @base.class.human_attribute_name(attribute),
+        :value => value
       }.merge(options)
 
       I18n.translate(key, options)