From dba196cb7f8d34b93f6872e4a43737bb52019065 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sun, 17 Jan 2010 03:26:20 +0530 Subject: Merge docrails --- activemodel/lib/active_model/callbacks.rb | 104 +++++++++++++++------ activemodel/lib/active_model/conversion.rb | 13 ++- activemodel/lib/active_model/dirty.rb | 40 +++++++- activemodel/lib/active_model/validations/length.rb | 8 +- 4 files changed, 128 insertions(+), 37 deletions(-) (limited to 'activemodel/lib') diff --git a/activemodel/lib/active_model/callbacks.rb b/activemodel/lib/active_model/callbacks.rb index f66a1ddcaa..a7e0cf90c1 100644 --- a/activemodel/lib/active_model/callbacks.rb +++ b/activemodel/lib/active_model/callbacks.rb @@ -1,6 +1,52 @@ 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__callbacks methods are dynamically created when you extend + # the ActiveModel::Callbacks 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 @@ -8,43 +54,39 @@ module ActiveModel end end - # Define callbacks similar to ActiveRecord ones. It means: - # - # * The callback chain is aborted whenever the block given to - # _run_callbacks returns false. - # - # * If a class is given to the fallback, it will search for - # before_create, around_create and after_create methods. - # - # == Usage - # - # First you need to define which callbacks your model will have: + # 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 :only => 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_, after_ and around_, in which + # case the call back will call that class's _ method passing the object + # that the callback is being called on. + # # class MyModel + # extend ActiveModel::Callbacks # define_model_callbacks :create + # + # before_create AnotherClass # end - # - # This will define three class methods: before_create, around_create, - # and after_create. They accept a symbol, a string, an object or a block. - # - # After you create a callback, you need to tell when they are executed. - # For example, you could do: - # - # def create - # _run_create_callbacks do - # super + # + # class AnotherClass + # def self.before_create( obj ) + # # obj is the MyModel instance that the callback is being called on # end # end - # - # == Options - # - # 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 - # + # def define_model_callbacks(*callbacks) options = callbacks.extract_options! options = { :terminator => "result == false", :scope => [:kind, :name] }.merge(options) diff --git a/activemodel/lib/active_model/conversion.rb b/activemodel/lib/active_model/conversion.rb index d5c65920f6..c14a07c7dc 100644 --- a/activemodel/lib/active_model/conversion.rb +++ b/activemodel/lib/active_model/conversion.rb @@ -1,5 +1,16 @@ module ActiveModel - # Include ActiveModel::Conversion if your object "acts like an ActiveModel model". + # 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 :to_model method. + # + # If your model does not act like an Active Model object, then you should define + # :to_model yourself returning a proxy object that wraps your object + # with Active Model compliant methods. module Conversion def to_model self diff --git a/activemodel/lib/active_model/dirty.rb b/activemodel/lib/active_model/dirty.rb index 735c61df74..5f02929a9d 100644 --- a/activemodel/lib/active_model/dirty.rb +++ b/activemodel/lib/active_model/dirty.rb @@ -1,5 +1,43 @@ module ActiveModel - # Track unsaved attribute changes. + # ActiveModel::Dirty provides a way to track changes in your + # object in the same way as ActiveRecord does. + # + # The requirements to implement ActiveModel::Dirty are: + # + # * include ActiveModel::Dirty in your object + # * Call define_attribute_methods passing each method you want to track + # * Call attr_name_will_change! 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') diff --git a/activemodel/lib/active_model/validations/length.rb b/activemodel/lib/active_model/validations/length.rb index 871f589af9..9ceb75487f 100644 --- a/activemodel/lib/active_model/validations/length.rb +++ b/activemodel/lib/active_model/validations/length.rb @@ -57,13 +57,13 @@ module ActiveModel # # class Person < ActiveRecord::Base # validates_length_of :first_name, :maximum=>30 - # validates_length_of :last_name, :maximum=>30, :message=>"less than {{count}} if you don't mind" + # validates_length_of :last_name, :maximum=>30, :message=>"less than 30 if you don't mind" # validates_length_of :fax, :in => 7..32, :allow_nil => true # validates_length_of :phone, :in => 7..32, :allow_blank => true # validates_length_of :user_name, :within => 6..20, :too_long => "pick a shorter name", :too_short => "pick a longer name" - # validates_length_of :fav_bra_size, :minimum => 1, :too_short => "please enter at least {{count}} character" - # validates_length_of :smurf_leader, :is => 4, :message => "papa is spelled with {{count}} characters... don't play me." - # validates_length_of :essay, :minimum => 100, :too_short => "Your essay must be at least {{count}} words."), :tokenizer => lambda {|str| str.scan(/\w+/) } + # validates_length_of :zip_code, :minimum => 5, :too_short => "please enter at least 5 characters" + # validates_length_of :smurf_leader, :is => 4, :message => "papa is spelled with 4 characters... don't play me." + # validates_length_of :essay, :minimum => 100, :too_short => "Your essay must be at least 100 words."), :tokenizer => lambda {|str| str.scan(/\w+/) } # end # # Configuration options: -- cgit v1.2.3