ref: refs/heads/jr-basemodel commit 1cb47ff74e910a0509c235c6d296db42504912eb Author: Josef Reidinger Date: Fri Dec 11 18:15:22 2009 +0100 add documentation to BaseModel (partial only) --- webservice/lib/base_model/base.rb | 73 ++++++++++++++++++++++++++ webservice/lib/base_model/mass_assignment.rb | 36 +++++++++++++ 2 files changed, 109 insertions(+), 0 deletions(-) diff --git a/webservice/lib/base_model/base.rb b/webservice/lib/base_model/base.rb index eb72bcb..aec330f 100644 --- a/webservice/lib/base_model/base.rb +++ b/webservice/lib/base_model/base.rb @@ -1,40 +1,113 @@ module BaseModel + # == Base + # Shared ancestor for models that want to act similar as ActiveResource or ActiveRecord model. + # + # Inspired by ActiveModel from rails3.0 + # Supported features + # * Validation + # * Callbacks + # * Mass assignment + # * Serialization + # + # === Validation + # It is used validation from ActiveRecord. For details see ActiveRecord::Validations + # + # Not all validation is usable in all models. Basic supported ones is: + # * validates_presence_of + # * validates_format_of + # * validates_inclusion_of + # * validates_exclusion_of + # * validates_range_of + # * validates_lenght_of + # * validates_numberically_of + # * validates_each (general validation) + # * validates_numberically_of + # see ActiveRecord::Validations::ClassMethods documentation for arguments + # + # === Callbacks + # It is used to add hook to actions from ActiveRecord. For details see ActiveRecord::Callbacks + # Supported callbacks (all have before and after variant also): + # * around_create + # * around_destroy + # * around_save + # * around_update + # * around_validation + # * around_validation_on_create + # * around_validation_on_update + # * general around_filter + # see ActiveRecord::Callbacks documentation for arguments + # + # === Mass assignment + # see BaseModel::MassAssignment + # + # === Serialization + # Framework to support serialization. By default is support xml and json serialization (method to_xml and to_json) + # and deserialization (from_xml and from_json). + # + # TODO add example + class Base + # requirement for class which should be used in ActiveModel + # see http://www.engineyard.com/blog/2009/my-five-favorite-things-about-rails-3/ (paragraph 4) def to_model self end + # initialize attributes by hash in attr def initialize(attr={}) load(attr) end + # saves result + # if fails sets error + # see ActiveRecord::Base#save or ActiveResource::Base#save + # Do not overwritte it, overwrite instead create or update def save create_or_update end + # same as save but throws exception if error occur + # see save def save! create_or_update #TODO raise exception end + # identification if create new source or update already existing one + # by default return false ( always update ) def new_record? false #always update by default end + # Creates or updates source depending on result of new_record? + # Use method save unless you really know what you are doing. def create_or_update (new_record? ? create : update) != false end + # Creates new source. + # By default do nothing. + # Overwrite only if you overwrite also new_record? otherwise it is never call + # If problem occur returns false and must properly set Error structure see ActiveRecord::Error def create true end + # Updates source. + # By default do nothing. + # Overwrite it if model is not read-only + # If problem occur returns false and must properly set Error structure see ActiveRecord::Error def update true end + # destroys source. + # By default do nothing. + # Overwrite it if model is not read-only + # If problem occur returns false and must properly set Error structure see ActiveRecord::Error def destroy + true end #remove overwritten method_missing from activeRecord diff --git a/webservice/lib/base_model/mass_assignment.rb b/webservice/lib/base_model/mass_assignment.rb index b90ce0d..b342650 100644 --- a/webservice/lib/base_model/mass_assignment.rb +++ b/webservice/lib/base_model/mass_assignment.rb @@ -1,5 +1,28 @@ module BaseModel + # == Mass Assignment module + # Adds ability to load instance variables from hash + # It allow whitelisting and blacklisting variables which should not be + # overwritten. It respect common behavior in ActiveResource and ActiveRecord. + # For mass loading see ActiveResource::Base#load + # For whitelisting details see ActiveRecord::Base.attr_accessible + # For blacklisting details see ActiveRecord::Base.attr_protected + # + # Example: + # class C + # include BaseModel::MassAssignment + # + # attr_accessor :attr1, attr2, :internal + # + # attr_protected :internal + # + # def instantiate(attr={}) + # load attr + # end + # end module MassAssignment + # loads hash to instance variables, where keys is names of variables and + # hash value is variables values + # it has same behavior as ActiveResource::Base#load def load(attributes) attributes.each do |k,v| whitelist = self.class.accessible_attributes @@ -15,20 +38,33 @@ module BaseModel end module ClassMethods + + # Defines attributes which should be loaded by mass assignment. + # By default is used all attributes + # For disable using loading non-whitelisted attributes use + # without parameters + # param args is variable number of symbols which identify variables def attr_accessible ( *args ) @attr_accessible ||= [] @attr_accessible.concat args end + # Gets list of allowed attributes. If result is nil, then is allowed is + # all attributes which is not protected. def accessible_attributes @attr_accessible end + # Defines attributes which cannot be loaded by mass assignment. + # By default all attributes is not protected. + # Note only used if whitelist is not specified by attr_accessible + # param args is variable number of symbols which identify variables def attr_protected ( *args ) @attr_protected ||= [] @attr_protected.concat args end + # Gets list of protected attributes. If result is nil, then no attributes is protected. def protected_attributes @attr_protected end -- To unsubscribe, e-mail: yast-commit+unsubscribe@opensuse.org For additional commands, e-mail: yast-commit+help@opensuse.org