prepro 0.0.3 → 0.0.4

data/doc/gem_workflow.textile

@@ -0,0 +1,8 @@
+h1. How to cut a new version
+
+# after all changes are made
+# update the version in lib/version.rb, following semantic versioning
+# cd into prepro root dir
+# gem build prepro.gemspec
+# gem push prepro-x.x.x.gem
+# commit all changes to git

data/lib/prepro/authorization_error.rb

@@ -0,0 +1,6 @@
+# Defines an error to raise when permissions are transgressed.
+module Prepro
+  
+  class AuthorizationError < StandardError; end
+  
+end

data/lib/prepro/presenter.rb

@@ -10,10 +10,14 @@ module Prepro
     # @param[User, AnonymousUser] actor the actor who will view the model
     # @param[ActionView::Base] view_context An instance of a view class. The default view class is
     #     ActionView::Base
-    # @param[Hash, optional] options
+    # @param[Hash, optional] options:
+    #     * :enforce_permissions - default true
     # @return[DecoratedModel, Array<DecoratedModel>] a model or collection thereof, decorated for
     #     presentation
     def self.new(id_model_hash_collection, actor, view_context, options = {})
+      options = {
+        :enforce_permissions => true
+      }.merge(options)
       case id_model_hash_collection
       when Array, ActiveRecord::Relation
         present_collection(id_model_hash_collection, actor, view_context, options)
@@ -21,7 +25,7 @@ module Prepro
         present_single(id_model_hash_collection, actor, view_context, options)
       end
     end
-  
+
     # Alias the basic access methods, so that they can be called for classes further down the
     # inheritance chain, after another class overrode the method
     # Aliasing class methods can only be done in the singleton method
@@ -38,12 +42,16 @@ module Prepro
     # @param[Hash, optional] options
     # @return[Array<DecoratedModel>] An array of models, each decorated for presentation
     def self.present_collection(model_instances, actor, view_context, options = {})
-      presenter_attrs = OpenStruct.new(:actor => actor, :view_context => view_context, :options => options)
-      enforce_permissions(model_class.listable_by?(actor))
+      presenter_attrs = OpenStruct.new(
+        :actor => actor, :view_context => view_context, :options => options
+      )
+      if options[:enforce_permissions]
+        enforce_permissions(model_class.listable_by?(actor))
+      end
       model_instances.each { |e| make_presentable!(e, presenter_attrs) }
       model_instances
     end
-  
+
     # Prepares a model instance for presentation
     # @param[Integer, String(number), Model] id_hash_model id of model, attributes for model, or model
     #     to present
@@ -55,11 +63,13 @@ module Prepro
     def self.present_single(id_hash_model, actor, view_context, options = {})
       presenter_attrs = OpenStruct.new(:actor => actor, :view_context => view_context, :options => options)
       model_instance = load_model_instance(id_hash_model)
-      enforce_permissions(model_instance.viewable_by?(actor))
+      if options[:enforce_permissions]
+        enforce_permissions(model_instance.viewable_by?(actor))
+      end
       make_presentable!(model_instance, presenter_attrs)
       model_instance
     end
-  
+
     # Returns a model_instance, based on given id_hash_model
     def self.load_model_instance(id_hash_model)
       case id_hash_model
@@ -76,22 +86,24 @@ module Prepro
     def self.model_class
       raise "Implement me in concrete presenter"
     end
-  
-    # Override this in your concrete presenters with your own permission handling code.
+
+    # Raises an AuthorizationError if actor doesn't have permission
+    # @param[Boolean] has_permission indicates whether actor has permission
+    # @return[Nil] nil, or raises AuthorizationError
     def self.enforce_permissions(has_permission)
-      raise "Implement me in concrete presenter"
+      raise Prepro::AuthorizationError  unless has_permission
     end
-  
+
     module DecoratorMixin
-    
+
       def presenter_attrs=(the_presenter_attrs)
         @presenter_attrs = the_presenter_attrs
       end
-    
+
       def presenter_attrs
         @presenter_attrs
       end
-    
+
       # Formats a_datetime
       # @param[DateTime, Nil] a_datetime the datetime to format
       # @param[Symbol] output_format the format to be applied: :distance_in_words,
@@ -167,8 +179,8 @@ module Prepro
       def indicate_blank
         presenter_attrs.view_context.content_tag :span, "None Given", :class => 'label'
       end
-    
+
     end
-  
+
   end
 end

data/lib/prepro/processor.rb

@@ -3,24 +3,33 @@
 # Use it for the create, update, and destroy actions in a rails app.
 module Prepro
   class Processor
-  
+
     # Creates a new model_instance based on model_attrs.
     # @param[Hash] model_attrs The attributes for the new model_instance. Includes DB columns,
     #     associated objects, nested attributes, etc.
     # @param[User, AnonymousUser, Nil] actor The actor who creates the model_instance
+    # @param[Hash, optional] options:
+    #   * :enforce_permissions - default true
     # @return[Array<ModelInstance, Boolean>] A tuple with the newly created model_instance and a
     #     success flag.
     def self.create(model_attrs, actor, options = {})
-      processor_attrs = OpenStruct.new(:attributes => model_attrs, :actor => actor, :options => options)
+      options = {
+        :enforce_permissions => true
+      }.merge(options)
+      processor_attrs = OpenStruct.new(
+        :attributes => model_attrs, :actor => actor, :options => options
+      )
       model_instance = model_class.new
-      enforce_permissions(model_instance.creatable_by?(actor))
+      if options[:enforce_permissions]
+        enforce_permissions(model_instance.creatable_by?(actor))
+      end
       before_assign_attributes_on_create(model_instance, processor_attrs)
       model_instance.assign_attributes(model_attrs, :as => options[:as])
       before_save_on_create(model_instance, processor_attrs)
       success = model_instance.save
       [model_instance, success]
     end
-  
+
     # Updates an existing model_instance based on model_attrs.
     # @param[Hash] model_attrs The attributes for the updated model_instance. Includes DB columns,
     #     the model's id, associated objects, nested attributes, etc.
@@ -29,21 +38,25 @@ module Prepro
     def self.update(model_attrs, actor, options = {})
       processor_attrs = OpenStruct.new(:attributes => model_attrs, :actor => actor, :options => options)
       model_instance = model_class.find(model_attrs[:id])
-      enforce_permissions(model_instance.updatable_by?(actor))
+      if options[:enforce_permissions]
+        enforce_permissions(model_instance.updatable_by?(actor))
+      end
       before_assign_attributes_on_update(model_instance, processor_attrs)
       model_instance.assign_attributes(model_attrs, :as => options[:as])
       before_save_on_update(model_instance, processor_attrs)
       success = model_instance.save
       [model_instance, success]
     end
-  
+
     # Destroys an existing model_instance based on model_id
     # @param[Integer, String<Number>] model_id The id of the model_instance to be destroyed
     # @param[User, AnonymousUser, Nil] actor The actor who updates the model_instance
     # @return[Array<ModelInstance, Boolean>] A tuple with the destroyed model_instance and a success flag.
     def self.destroy(model_id, actor, options = {})
       model_instance = model_class.find(model_id)
-      enforce_permissions(model_instance.destroyable_by?(actor))
+      if options[:enforce_permissions]
+        enforce_permissions(model_instance.destroyable_by?(actor))
+      end
       model_instance.destroy
       [model_instance, true]
     end
@@ -74,15 +87,17 @@ module Prepro
     def self.model_class
       raise "Implement me in concrete processor"
     end
-  
-    # Override this in your concrete processors with your own permission handling code.
+
+    # Raises an AuthorizationError if actor doesn't have permission
+    # @param[Boolean] has_permission indicates whether actor has permission
+    # @return[Nil] nil, or raises AuthorizationError
     def self.enforce_permissions(has_permission)
-      raise "Implement me in concrete processor"
+      raise Prepro::AuthorizationError  unless has_permission
     end
-  
+
     def self.make_processable(model_instance, processor_attrs)
       # nothing to do here, override in specific processors
     end
-  
+
   end
 end

data/lib/prepro/version.rb

@@ -1,3 +1,3 @@
 module Prepro
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/readme.textile

@@ -2,3 +2,42 @@ Prepro gives your Rails app presenters and processors to slim down both controll
 
 This is still a work in progress. I use it for production, however the API might change and it
 requires a lot more documentation.
+
+Requires Rails 3.1 or greater.
+
+
+h1. How Prepro fits into the Rails picture
+
+* Rails models, ActiveRecord based.
+* Prepro Presenters: wrapped around a Rails model to take care of data output. You would typically
+  use a presenter in the following controller actions: index, show, new, edit
+* Prepro Processors: wrapped around a Rails model to take care of data input.
+
+
+h2. What to put into Rails Models
+
+Try to encapsulate all but the simplest references to ActiveRecord in the model. Don't let AR spill
+out into your entire app. This will make testing a lot simpler.
+
+* Complex AR methods like composed AREL methods or scopes
+* Data manipulation
+* validation
+* delegation
+* conversion
+* getter and setter overrides for DB column based attributes
+
+h2. What to put into Presenters
+
+Anything that is related to data output and display.
+
+* Display related methods
+* output in alternative formats like PDF, CSV, ATOM
+* methods used for form population (e.g., Select options)
+
+h2. What to put into Processors
+
+Anything related to data input.
+
+* methods to create/update records from complex data, e.g., params hash. This is comparable to DCI
+  contexts.
+* form data processing

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: prepro
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 23
   prerelease: 
   segments: 
   - 0
   - 0
-  - 3
-  version: 0.0.3
+  - 4
+  version: 0.0.4
 platform: ruby
 authors: 
 - Jo Hund
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-25 00:00:00 -08:00
+date: 2012-02-02 00:00:00 -08:00
 default_executable: 
 dependencies: []
 
@@ -28,11 +28,14 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- doc/gem_workflow.textile
 - lib/prepro.rb
+- lib/prepro/authorization_error.rb
 - lib/prepro/presenter.rb
 - lib/prepro/processor.rb
 - lib/prepro/version.rb
 - prepro-0.0.2.gem
+- prepro-0.0.3.gem
 - prepro.gemspec
 - readme.textile
 has_rdoc: true