view_models 1.5.2

data/lib/helpers/collection.rb

@@ -0,0 +1,124 @@
+module ViewModels
+  module Helpers
+    module Rails
+      
+      # Construct a view_model for a collection.
+      #
+      def collection_view_model_for array_or_pagination, context = self
+        Collection.new array_or_pagination, context
+      end
+      
+      # The Collection view_model helper has the purpose of presenting presentable collections.
+      # * Render as list
+      # * Render as table
+      # * Render as collection
+      # * Render a pagination
+      #
+      class Collection
+        
+        #
+        #
+        methods_to_delegate = [Enumerable.instance_methods.map(&:to_sym),
+                               :length, :size, :empty?, :each, :exit,
+                               { :to => :@collection }].flatten
+        self.delegate *methods_to_delegate
+        def select *args, &block # active_support fail?
+          @collection.select *args, &block
+        end
+        
+        def initialize collection, context
+          @collection, @context = collection, context
+        end
+        
+        # Renders a list (in the broadest sense of the word).
+        #
+        # Options:
+        #   collection => collection to iterate over
+        #   context => context to render in
+        #   template_name => template to render for each model element
+        #   separator => separator between each element
+        # By default, uses:
+        #   * The collection of the collection view_model to iterate over.
+        #   * The original context given to the collection view_model to render in.
+        #   * Uses :list_item as the default element template.
+        #   * Uses a nil separator in html.
+        #
+        def list options = {}
+          default_options = { :collection => @collection, :template_name => :list_item, :separator => nil }
+          
+          render_partial :list, default_options.merge(options)
+        end
+        
+        # Renders a collection.
+        #
+        # Note: The only difference between a list and a collection is the enclosing
+        #       list type. While list uses ol, the collection uses ul.
+        #
+        # Options:
+        #   collection => collection to iterate over
+        #   context => context to render in
+        #   template_name => template to render for each model element
+        #   separator => separator between each element
+        # By default, uses:
+        #   * The collection of the collection view_model to iterate over.
+        #   * Uses :collection_item as the default element template.
+        #   * Uses a nil separator.
+        #
+        def collection options = {}
+          default_options = { :collection => @collection, :template_name => :collection_item, :separator => nil }
+          
+          render_partial :collection, default_options.merge(options)
+        end
+        
+        # Renders a table.
+        #
+        # Note: Each item represents a table row.
+        #
+        # Options:
+        #   collection => collection to iterate over
+        #   context => context to render in
+        #   template_name => template to render for each model element
+        #   separator => separator between each element
+        # By default, uses:
+        #   * The collection of the collection view_model to iterate over.
+        #   * Uses :table_row as the default element template.
+        #   * Uses a nil separator.
+        #
+        def table options = {}
+          default_options = { :collection => @collection, :template_name => :table_row, :separator => nil }
+          
+          render_partial :table, default_options.merge(options)
+        end
+        
+        # Renders a pagination.
+        #
+        # Options:
+        #   collection => collection to iterate over
+        #   context => context to render in
+        #   separator => separator between pages
+        # By default, uses:
+        #   * The collection of the collection view_model to iterate over.
+        #   * Uses | as separator.
+        #
+        def pagination options = {}
+          default_options = { :collection => @collection, :separator => '|' }
+          
+          render_partial :pagination, default_options.merge(options)
+        end
+        
+        private
+          
+          # Helper method that renders a partial in the context of the context instance.
+          #
+          # Example:
+          #   If the collection view_model helper has been instantiated in the context
+          #   of a controller, render will be called in the controller.
+          #
+          def render_partial name, locals
+            @context.instance_eval { render :partial => "view_models/collection/#{name}", :locals => locals }
+          end
+      end
+      
+    end
+  end
+end

data/lib/helpers/rails.rb

@@ -0,0 +1,59 @@
+module ViewModels
+  module Helpers
+    module Rails
+      
+      mattr_accessor :specific_view_model_mapping
+      self.specific_view_model_mapping = {}
+      
+      # Create a new view_model instance for the given model instance
+      # with the given arguments.
+      #
+      # Note: Will emit an ArgumentError if the view model class doesn't support 2 arguments.
+      #
+      def view_model_for model, context = self
+        view_model_class_for(model).new model, context
+      end
+      
+      # Get the view_model class for the given model instance.
+      #
+      # Note: ViewModels are usually of class ViewModels::<ModelClassName>.
+      #       (As returned by default_view_model_class_for)
+      #       Override specific_mapping if you'd like to install your own.
+      #
+      # OR:   Override default_view_model_class_for(model) if
+      #       you'd like to change the default.
+      #
+      def view_model_class_for model
+        specific_view_model_class_for(model) || default_view_model_class_for(model)
+      end
+      
+      # Returns the default view_model class for the given model instance.
+      #
+      # Default class name is:
+      # ViewModels::<ModelClassName>
+      #
+      # Override this method if you'd like to change the _default_
+      # model-to-view_model class mapping.
+      #
+      # Note: Will emit a NameError if a corresponding ViewModels constant cannot be loaded.
+      #
+      mattr_accessor :default_prefix
+      self.default_prefix = 'ViewModels::'
+      def default_view_model_class_for model
+        (default_prefix + model.class.name).constantize
+      end
+      
+      # Returns a specific view_model class for the given model instance.
+      #
+      # Override this method, if you want to return a specific
+      # view model class for the given model.
+      #
+      # Note: Will emit a NameError if a corresponding ViewModels constant cannot be loaded.
+      #
+      def specific_view_model_class_for model
+        specific_view_model_mapping[model.class]
+      end
+      
+    end
+  end
+end

data/lib/helpers/view.rb

@@ -0,0 +1,22 @@
+module ViewModels
+  module Helpers
+    # Module for conveniently including common view_helpers into a view_model
+    #
+    module View
+      
+      # Include hook.
+      #
+      def self.included view_model
+        view_model.send :include, *all_view_helpers
+      end
+      
+      def self.all_view_helpers
+        [
+          ActionView::Helpers,
+          ERB::Util
+        ]
+      end
+  
+    end
+  end
+end

data/lib/view_models/base.rb

@@ -0,0 +1,268 @@
+# Base Module for ViewModels.
+#
+module ViewModels
+  
+  # Gets raised when render_as, render_the, or render_template cannot
+  # find the named template, not even in the hierarchy.
+  #
+  class MissingTemplateError < StandardError; end
+  
+  # Base class from which all view_models inherit.
+  #
+  class Base
+    
+    # Model and Controller are accessible from outside.
+    #
+    # TODO but they actually shouldn't be. Try to migrate into protected area.
+    #
+    attr_reader :model, :controller
+    
+    # Make helper and helper_method available
+    #
+    include ActionController::Helpers
+    
+    # Create a view_model. To create a view_model, you need to have a model (to present) and a context.
+    # The context is usually a view or a controller, but doesn't need to be.
+    # 
+    def initialize model, context
+      @model = model
+      @controller = ControllerExtractor.new(context).extract
+    end
+    
+    class << self
+      
+      # Installs a path store, a specific store for
+      # template inheritance, to remember specific
+      # [path, name, format] tuples, pointing to a template path,
+      # so the view models don't have to traverse the inheritance chain always.
+      #
+      attr_accessor :path_store
+      def inherited subclass
+        ViewModels::PathStore.install_in subclass
+        super
+      end
+      
+      # Installs the model_reader Method for filtered
+      # model method delegation.
+      #
+      include Extensions::ModelReader
+      
+      # Delegates method calls to the controller.
+      #
+      # Examples:
+      #   controller_method :current_user
+      #   controller_method :current_user, :current_profile  # multiple methods to be delegated
+      #
+      # In the view_model:
+      #   self.current_user
+      # will call
+      #   controller.current_user
+      #
+      def controller_method *methods
+        delegate *methods << { :to => :controller }
+      end
+      
+      # Wrapper for add_template_helper in ActionController::Helpers, also
+      # includes given helper in the view_model
+      #
+      # TODO extract into module
+      #
+      alias old_add_template_helper add_template_helper
+      def add_template_helper helper_module
+        include helper_module
+        old_add_template_helper helper_module
+      end
+      
+      # Sets the view format and tries to render the given options.
+      #
+      # Note: Also caches [path, name, format] => template path.
+      #
+      def render view, options
+        options.format! view
+        path_store.cached options do
+          options.file = template_path view, options
+          view.render_with options
+        end
+      end
+      
+      protected
+        
+        # Returns the next view model class in the render hierarchy.
+        #
+        # Note: Just returns the superclass.
+        #
+        # TODO Think about raising the MissingTemplateError here.
+        #
+        def next
+          superclass
+        end
+        
+        # Just raises a fitting template error.
+        #
+        def raise_template_error_with message
+          raise MissingTemplateError.new "No template #{message} found."
+        end
+        
+        # Check if the view lookup inheritance chain has ended.
+        #
+        # Raises a MissingTemplateError if yes.
+        #
+        def inheritance_chain_ends?
+           self == ViewModels::Base
+        end
+        
+        # Returns a template path for the view with the given options.
+        #
+        # If no template is found, traverses up the inheritance chain.
+        #
+        # Raises a MissingTemplateError if none is found during
+        # inheritance chain traversal.
+        #
+        def template_path view, options
+          raise_template_error_with options.error_message if inheritance_chain_ends?
+          
+          template_path_from(view, options) || self.next.template_path(view, options)
+        end
+        
+        # Accesses the view to find a suitable template path.
+        #
+        def template_path_from view, options
+          template = view.find_template tentative_template_path(options)
+          
+          template && template.path
+        end
+        
+        # Return as render path either a stored path or a newly generated one.
+        #
+        # If nothing or nil is passed, the store is ignored.
+        #
+        def tentative_template_path options
+          path_store[options.path_key] || generate_template_path_from(options)
+        end
+        
+        # Returns the root of this view_models views with the template name appended.
+        # e.g. 'view_models/some/specific/path/to/template'
+        #
+        def generate_template_path_from options
+          File.join generate_path_from(options), options.name
+        end
+        
+        # If the path is explicitly defined, return it, otherwise
+        # generate a view model path from the class name.
+        #
+        def generate_path_from options
+          options.path || view_model_path
+        end
+        
+        # Returns the path from the view_model_view_paths to the actual templates.
+        # e.g. "view_models/models/book"
+        #
+        # If the class is named
+        #   ViewModels::Models::Book
+        # this method will yield
+        #   view_models/models/book
+        #
+        # Note: Remembers the result since it is dependent on the Class name only.
+        #
+        def view_model_path
+          @view_model_path || @view_model_path = self.name.underscore
+        end
+        
+    end # class << self
+    
+    # Delegate controller methods.
+    #
+    controller_method :logger, :form_authenticity_token, :protect_against_forgery?, :request_forgery_protection_token
+    
+    # Make all the dynamically generated routes (restful routes etc.)
+    # available in the view_model
+    #
+    ActionController::Routing::Routes.install_helpers self
+    
+    # Renders the given partial in the view_model's view root in the format given.
+    #
+    # Example:
+    #   app/views/view_models/this/view_model/_partial.haml
+    #   app/views/view_models/this/view_model/_partial.text.erb
+    #
+    # The following options are supported: 
+    # * :format - Calling view_model.render_as('partial') will render the haml
+    #   partial, calling view_model.render_as('partial', :format => :text) will render
+    #   the text erb.
+    # * All other options are passed on to the render call. I.e. if you want to specify locals you can call
+    #   view_model.render_as(:partial, :locals => { :name => :value })
+    # * If no format is given, it will render the default format, which is (currently) html.
+    #
+    def render_as name, options = {}
+      render RenderOptions::Partial.new(name, options)
+    end
+    # render_the is used for small parts.
+    #
+    # Example:
+    # # If the view_model is called window, the following
+    # # is more legible than window.render_as :menubar
+    # * window.render_the :menubar
+    #
+    alias render_the render_as
+    
+    # Renders the given template in the view_model's view root in the format given.
+    #
+    # Example:
+    #   app/views/view_models/this/view_model/template.haml
+    #   app/views/view_models/this/view_model/template name.text.erb
+    #
+    # The following options are supported: 
+    # * :format - Calling view_model.render_template('template') will render the haml
+    #   template, calling view_model.render_template('template', :format => :text) will render
+    #   the text erb template.
+    # * All other options are passed on to the render call. I.e. if you want to specify locals you can call
+    #   view_model.render_template(:template, :locals => { :name => :value })
+    # * If no format is given, it will render the default format, which is (currently) html.
+    #
+    def render_template name, options = {}
+      render RenderOptions::Template.new(name, options)
+    end
+    
+    protected
+      
+      # CaptureHelper needs this.
+      #
+      attr_accessor :output_buffer
+      
+      # Internal render method that uses the options to get a view instance
+      # and then referring to its class for rendering.
+      #
+      def render options
+        options.view_model = self
+        
+        determine_and_set_format options
+        
+        self.class.render view_instance, options
+      end
+      
+      # Returns a view instance for render_xxx.
+      #
+      # TODO Try getting a view instance from the controller.
+      #
+      def view_instance
+        # view = if controller.response.template
+        #   controller.response.template
+        # else
+          View.new controller, master_helper_module
+        # end
+        
+        # view.extend Extensions::View
+      end
+      
+      # Determines what format to use for rendering.
+      #
+      # Note: Uses the template format of the view model instance
+      #       if none is explicitly set in the options.
+      #       This propagates the format to further render_xxx calls.
+      #
+      def determine_and_set_format options
+        options.format = @template_format = options.format || @template_format
+      end
+      
+  end
+end

data/lib/view_models/controller_extractor.rb

@@ -0,0 +1,24 @@
+# Base Module for ViewModels.
+#
+module ViewModels
+  
+  # Extracts controllers for a living from unsuspecting views.
+  #
+  class ControllerExtractor
+    
+    attr_reader :context
+    
+    def initialize context
+      @context = context
+    end
+    
+    # Extracts a controller from the context.
+    #
+    def extract
+      context = self.context
+      context.respond_to?(:controller) ? context.controller : context
+    end
+    
+  end
+  
+end

data/lib/view_models/path_store.rb

@@ -0,0 +1,61 @@
+# Base Module for ViewModels.
+#
+module ViewModels
+  
+  # A simple path store. Designed to remove a bit of complexity from the base view model.
+  #
+  # Use it to install an instance in the metaclass.
+  #
+  class PathStore
+    
+    attr_reader :view_model_class
+    
+    def initialize view_model_class
+      @view_model_class = view_model_class
+      @name_path_mapping = {}
+    end
+    
+    # Install in the metaclass (as an example).
+    #
+    def self.install_in klass
+      klass.path_store = PathStore.new klass
+    end
+    
+    # Cache the result of the rendering.
+    #
+    def cached options, &block
+      prepare options.path_key
+      result = block.call
+      save options and result if result
+    end
+    
+    # Prepare the key for the next storing procedure.
+    #
+    # Note: If this is nil, the store will not save the path.
+    #
+    def prepare key
+      @key = key
+    end
+    
+    # Saves the options for the prepared key.
+    #
+    def save options
+      self[@key] = options.file
+    end
+    
+    # Does not save values for nil keys.
+    #
+    def []= key, path
+      return if key.nil?
+      @name_path_mapping[key] ||= path
+    end
+    
+    # Simple [] delegation.
+    #
+    def [] key
+      @name_path_mapping[key]
+    end
+    
+  end
+  
+end

data/lib/view_models/render_options.rb

@@ -0,0 +1,109 @@
+module ViewModels
+  
+  # Container object for render options.
+  #
+  module RenderOptions
+    
+    # Hold a number of options for rendering.
+    #
+    class Base
+      
+      attr_accessor :path, :name, :prefix, :file, :view_model, :format
+      
+      def initialize prefix, name, options
+        @prefix = prefix
+        @options = options
+        self.template_name = deoptionize name
+        @format = @options.delete :format
+      end
+      
+      # Generate a suitable error message for the error options.
+      #
+      def error_message
+        "'#{error_path}#{name}' with #{error_format}"
+      end
+      def error_path
+        path = self.path
+        path ? "#{path}/" : ""
+      end
+      def error_format
+        format = self.format
+        format ? "format #{format}" : "default format"
+      end
+      
+      # Used when rendering.
+      #
+      def to_render_options
+        @options[:locals] ||= {}
+        @options[:locals].reverse_merge! :view_model => view_model
+        @options.reverse_merge :file => file
+      end
+      
+      def format! view
+        view.template_format = @format if @format
+      end
+      
+      # Used for caching.
+      #
+      def path_key
+        [self.path, self.name, self.format]
+      end
+      
+      private
+        
+        # TODO rewrite
+        #
+        def template_name= template_name
+          template_name.to_s.include?('/') ? specific_path(template_name) : incomplete_path(template_name)
+        end
+        
+        #
+        #
+        def deoptionize template_name
+          if template_name.kind_of?(Hash)
+            @options.merge! template_name
+            @options.delete :partial
+          else
+            template_name
+          end
+        end
+        
+        #
+        #
+        def specific_path name
+          self.path             = File.dirname name
+          self.name_with_prefix = File.basename name
+        end
+        
+        #
+        #
+        def incomplete_path name
+          self.path             = nil
+          self.name_with_prefix = name
+        end
+        
+        def name_with_prefix= name
+          self.name = "#{self.prefix}#{name}"
+        end
+        
+      end
+      
+      # A specific container for partial rendering.
+      #
+      class Partial < Base
+        def initialize name, options = {}
+          super :'_', name, options
+        end
+      end
+
+      # A specific container for template rendering.
+      #
+      class Template < Base
+        def initialize name, options = {}
+          super nil, name, options
+        end
+      end
+    
+  end
+  
+end

data/lib/view_models/view.rb

@@ -0,0 +1,26 @@
+module ViewModels
+  # View model specific view.
+  #
+  class View < ActionView::Base
+    
+    # Include the helpers from the view model.
+    #
+    def initialize controller, master_helper_module
+      metaclass.send :include, master_helper_module
+      super controller.class.view_paths, {}, controller
+    end
+    
+    #
+    #
+    def render_with options
+      render options.to_render_options
+    end
+
+    # Finds the template in the view paths at the given path, with its format.
+    #
+    def find_template path
+      view_paths.find_template path, template_format rescue nil
+    end
+    
+  end
+end

data/lib/view_models.rb

@@ -0,0 +1,3 @@
+require 'active_support'
+
+module ViewModels; end