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
