prepro 0.0.0 → 0.0.2

data/lib/prepro/presenter.rb

@@ -0,0 +1,174 @@
+# Abstract class with common features for Presenters. Use this for any objects that will be rendered
+# in some shape or form. Use it for read only access, in other words, for index, show, new and edit
+# actions in a rails app.
+module Prepro
+  class Presenter
+
+    # Prepares collection of model instances or a single model instance for presentation
+    # @param[Integer, String(number), Hash, Model, Array<Model>] id_model_hash_collection id of model,
+    #     attributes for new model, existing model or collection of models to present.
+    # @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
+    # @return[DecoratedModel, Array<DecoratedModel>] a model or collection thereof, decorated for
+    #     presentation
+    def self.new(id_model_hash_collection, actor, view_context, options = {})
+      case id_model_hash_collection
+      when Array, ActiveRecord::Relation
+        present_collection(id_model_hash_collection, actor, view_context, options)
+      else
+        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
+    # See: http://athikunte.blogspot.com/2008/03/aliasmethod-for-class-methods.html
+    class << self
+      alias_method :new_original, :new
+    end
+
+    # Prepares collection of model instances for presentation
+    # @param[Array<Model>] model_instances A collection of model instances
+    # @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
+    # @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))
+      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
+    # @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
+    # @return[DecoratedModel] a model, decorated for presentation
+    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))
+      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
+      when Integer, /\A\d+/
+        model_class.find(id_hash_model)
+      when Hash
+        model_class.new(id_hash_model)
+      else
+        id_hash_model
+      end
+    end
+
+    # Override this in your concrete presenters with the class presented by self.
+    def self.model_class
+      raise "Implement me in concrete presenter"
+    end
+  
+    # Override this in your concrete presenters with your own permission handling code.
+    def self.enforce_permissions(has_permission)
+      raise "Implement me in concrete presenter"
+    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,
+      #                              or any datetime format specified in initializers
+      def formatted_datetime(a_datetime, output_format, options = {})
+        return 'N/A'  if a_datetime.blank?
+        case output_format
+        when :distance_in_words
+          if a_datetime < Time.now
+            # in the past
+            decorated_time_ago_in_words(a_datetime, options)
+          else
+            # in the future
+            decorated_time_from_now_in_words(a_datetime, options)
+          end
+        else
+          a_datetime.to_s(output_format)
+        end
+      end
+
+      # Renders time ago, showing absolute time on hover
+      # @param[DateTime] a_datetime the time to render
+      # @param[Hash, optional] options:
+      #   * :suffix => printed after the time, default: ' ago'
+      #   * :suppress_1 => if the number is a one, suppress it. Used for '... in the last month', which
+      #                    reads better than '... in the last 1 month'
+      #   * :text_only => skip html tags
+      def decorated_time_ago_in_words(a_datetime, options = {})
+        options = {
+          :suffix => ' ago',
+          :suppress_1 => false,
+          :text_only => false
+        }.merge(options)
+        ts = ((presenter_attrs.view_context.time_ago_in_words(a_datetime).gsub('about ', '') + options[:suffix])  rescue 'N/A')
+        ts = ts.gsub(/^1\s+/, '')  if options[:suppress_1]
+        if options[:text_only]
+          ts
+        else
+          presenter_attrs.view_context.content_tag(:span, ts, :title => a_datetime.to_s(:full_date_and_time))
+        end
+      end
+
+      # Renders time from now, showing absolute time on hover
+      # @param[DateTime] a_datetime the time to render
+      # @param[Hash, optional] options:
+      #   * :prefix => printed before the time, default: 'in '
+      #   * :suppress_1 => if the number is a one, suppress it. Used for '... in the last month', which
+      #                    reads better than '... in the last 1 month'
+      #   * :text_only => skip html tags
+      def decorated_time_from_now_in_words(a_datetime, options = {})
+        options = {
+          :prefix => 'in ',
+          :suppress_1 => false,
+          :text_only => false
+        }.merge(options)
+        ts = (
+          (
+            options[:prefix] + presenter_attrs.view_context.time_ago_in_words(a_datetime).gsub('about ', '')
+          )  rescue 'N/A'
+        )
+        ts = ts.gsub(/^1\s+/, '')  if options[:suppress_1]
+        if options[:text_only]
+          ts
+        else
+          presenter_attrs.view_context.content_tag(:span, ts, :title => a_datetime.to_s(:full_date_and_time))
+        end
+      end
+
+      def formatted_boolean(a_boolean)
+        a_boolean ? 'Yes' : 'No'
+      end
+
+      def indicate_blank
+        presenter_attrs.view_context.content_tag :span, "None Given", :class => 'label'
+      end
+    
+    end
+  
+  end
+end

data/lib/prepro/processor.rb

@@ -0,0 +1,90 @@
+# Abstract class with common features for Processors. Use this for any objects that will receive
+# attributes and will cause a persisted record to be changed or updated. In other words:
+# 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
+    # @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)
+      model_instance = model_class.new
+      enforce_permissions(model_instance.creatable_by?(actor))
+      before_assign_attributes_on_create(model_instance, processor_attrs)
+      # use this (instead of attributes=), once we're on Rails3.1: model_instance.assign_attributes(model_attrs, :as => options[:as])
+      model_instance.attributes = model_attrs
+      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.
+    # @param[User, AnonymousUser, Nil] actor The actor who updates the model_instance
+    # @return[Array<ModelInstance, Boolean>] A tuple with the updated model_instance and a success flag.
+    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))
+      before_assign_attributes_on_update(model_instance, processor_attrs)
+      # use this (instead of attributes=), once we're on Rails3.1: model_instance.assign_attributes(model_attrs, :as => options[:as])
+      model_instance.attributes = model_attrs
+      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))
+      model_instance.destroy
+      [model_instance, true]
+    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
+    # See: http://athikunte.blogspot.com/2008/03/aliasmethod-for-class-methods.html
+    class << self
+      alias_method :create_original, :create
+      alias_method :update_original, :update
+    end
+
+  private
+
+    def self.before_assign_attributes_on_create(model_instance, processor_attrs)
+    end
+
+    def self.before_save_on_create(model_instance, processor_attrs)
+    end
+
+    def self.before_assign_attributes_on_update(model_instance, processor_attrs)
+    end
+
+    def self.before_save_on_update(model_instance, processor_attrs)
+    end
+
+    def self.model_class
+      raise "Implement me in concrete processor"
+    end
+  
+    # Override this in your concrete processors with your own permission handling code.
+    def self.enforce_permissions(has_permission)
+      raise "Implement me in concrete processor"
+    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

@@ -0,0 +1,3 @@
+module Prepro
+  VERSION = "0.0.2"
+end

data/lib/prepro.rb

@@ -1,3 +1,5 @@
-# Shell for the Prepro gem
-class Prepro
-end
+require 'prepro/presenter'
+require 'prepro/processor'
+
+module Prepro
+end

data/readme.textile

@@ -0,0 +1,4 @@
+Prepro gives your Rails app presenters and processors to slim down both controllers and models.
+
+This is still a work in progress. I use it for production, however the API might change and it
+requires a lot more documentation.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: prepro
 version: !ruby/object:Gem::Version 
-  hash: 31
+  hash: 27
   prerelease: 
   segments: 
   - 0
   - 0
-  - 0
-  version: 0.0.0
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Jo Hund
@@ -15,11 +15,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-12-20 00:00:00 -08:00
+date: 2012-01-25 00:00:00 -08:00
 default_executable: 
 dependencies: []
 
-description: Presenters and Processors to make Rails apps more SOLID.
+description: Presenters and Processors for clean Rails apps.
 email: jhund@clearcove.ca
 executables: []
 
@@ -29,6 +29,10 @@ extra_rdoc_files: []
 
 files: 
 - lib/prepro.rb
+- lib/prepro/presenter.rb
+- lib/prepro/processor.rb
+- lib/prepro/version.rb
+- readme.textile
 has_rdoc: true
 homepage: http://rubygems.org/gems/prepro
 licenses: []
@@ -62,6 +66,6 @@ rubyforge_project:
 rubygems_version: 1.5.2
 signing_key: 
 specification_version: 3
-summary: Presenters and Processors to make Rails apps more SOLID.
+summary: Presenters and Processors for clean Rails apps.
 test_files: []