view_models 2.0.1 → 3.0.0

data/lib/{shared/lib/view_models → view_models}/base.rb

@@ -1,59 +1,115 @@
 # Base Module for ViewModels.
+# @author Florian Hanke
+# @author Kaspar Schiess
+# @author Niko Dittmann
+# @author Beat Richartz
+# @version 3.0.0
+# @since 1.0.0
 #
-module 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
+  MissingTemplateError = Class.new(StandardError)
   
   # Base class from which all view_models inherit.
+  # @example Create Your first View Model
+  #   class ViewModels::MyViewModel < ViewModels::Base
+  #     # your code
+  #   end
   #
   class Base
     
+    # Make the rails methods helper and helper_method available in view models
+    #
+    include AbstractController::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, a controller, or an app, but doesn't need to be.
     # 
-    # TODO Include this.
+    # The @context = @controller is really only needed because some Rails helpers access @controller directly.
+    # It's really bad.
+    # @param [ActiveRecord] model The model which the view model is based upon
+    # @param [ActionView, ActionController, Rails::Application] app_or_controller_or_view The context of the view model
+    # @example Initialize a view model without the mapping helper
+    #   ViewModel::YourModel.new(@model, @context)
     # 
     def initialize model, app_or_controller_or_view
-      @model   = model
-      @context = ContextExtractor.new(app_or_controller_or_view).extract
+      @model                 = model
+      @context = @controller = ContextExtractor.new(app_or_controller_or_view).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.
+      # The path store accessor, storing the view paths for the view model
       #
       attr_accessor :path_store
+      
+      # 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 always traverse the inheritance chain.
+      # @param [ViewModel] subclass The subclass of the view model
+      #
       def inherited subclass
         ViewModels::PathStore.install_in subclass
         super
       end
       
       # Delegates method calls to the context.
-      #
-      # Examples:
-      #   context_method :current_user
-      #   context_method :current_user, :current_profile  # multiple methods to be delegated
-      #
       # In the view_model:
       #   self.current_user
       # will call
       #   context.current_user
       #
+      # @param [Symbol] methods A list of symbols representing methods to be delegated
+      # @example delegate one method to the context
+      #   context_method :current_user
+      # @example delegate multiple methods to the context
+      #   context_method :current_user, :current_profile
+      #
       def context_method *methods
         delegate *methods << { :to => :context }
       end
       
+      # Alias the context_method to the rails-centric controller_method.
+      #
+      alias controller_method context_method
+      
       # Installs the model_reader Method for filtered
       # model method delegation.
       #
       include Extensions::ModelReader
       
+      unless instance_methods.include?('old_add_template_helper')
+        alias old_add_template_helper add_template_helper
+        
+        # Wrapper for add_template_helper in ActionController::Helpers, also
+        # includes given helper in the view_model
+        #
+        # @todo extract into module
+        # @param [Module] helper_module the helper to be added
+        #
+        def add_template_helper helper_module
+          include helper_module
+          old_add_template_helper helper_module
+        end
+      end
+      
+      # Sets the view format and tries to render the given options.
+      # @param [ActionView] renderer The view renderer
+      # @param [Hash] options The options to pass to the view
+      # @option options [Hash] :locals The locals to pass to the view
+      # @note Also caches [path, name, format] => template path.
+      #
+      def render renderer, options
+        options.format! renderer
+        path_store.cached options do
+          options.file = template_path renderer, options
+          renderer.render_with options
+        end
+      end
+      
       protected
         
         # Hierarchical rendering.
@@ -61,27 +117,31 @@ module ViewModels
         
         # Returns the next view model class in the render hierarchy.
         #
-        # Note: Just returns the superclass.
+        # @note Just returns the superclass.
         #
-        # TODO Think about raising the MissingTemplateError here.
+        # @todo Think about raising the MissingTemplateError here.
+        # @return The superclass of the view model, which ends with ViewModel::Base
         #
         def next_in_render_hierarchy
           superclass
         end
-        # Just raises a fitting template error.
+        
+        # Raises the fitting template error with the given message
+        # @param [String,Symbol] message The message with which the template error should be raised
+        # @raise [MissingTemplateError] A template error indicating that the template is missing
         #
         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.
+        # @return wether the current class is ViewModel::Base and therefore at the end of the inheritance chain
         #
         def inheritance_chain_ends?
            self == ViewModels::Base
         end
         
-        
         # Template finding
         #
         
@@ -91,27 +151,36 @@ module ViewModels
         #
         # Raises a MissingTemplateError if none is found during
         # inheritance chain traversal.
+        # @param [ActionView] renderer The view renderer
+        # @param [Hash] options The options to pass to the template path
         #
-        def template_path renderer, options
+        def template_path renderer, options          
           raise_template_error_with options.error_message if inheritance_chain_ends?
           
           template_path_from(renderer, options) || self.next_in_render_hierarchy.template_path(renderer, options)
         end
-        
-        # ...
-        
-        # Return as render path either a stored path or a newly generated one.
+           
+        # Accesses the view to find a suitable template path.
+        # @param [ActionView] renderer The view renderer
+        # @param [Hash] options The options to pass to the view
         #
-        # If nothing or nil is passed, the store is ignored.
-        #
-        # TODO Think about using the built-in Padrino template store.
+        def template_path_from renderer, options
+          template = renderer.find_template tentative_template_path(options)
+          
+          template && template.virtual_path.to_s
+        end
+        
+        # @return render path either a stored path or a newly generated one.
+        # @note If nothing or nil is passed, the store is ignored.
+        # @param [Hash] options The view render options
         #
         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'
+        # @return the root of this view_models views with the template name appended.
+        # @example Returning a specific path
+        #   'some/specific/path/to/template'
         #
         def generate_template_path_from options
           File.join generate_path_from(options), options.name
@@ -130,19 +199,47 @@ module ViewModels
         # If the class is named
         #   ViewModels::Models::Book
         # this method will yield
-        #   view_models/models/book
+        #   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
+          @view_model_path ||= self.name.gsub(/^ViewModels::|(\w+)(::)?/) { $1.underscore.pluralize + ($2 ? '/' : '').to_s if $1 }
         end
         
     end
-    
+        
     # Delegate context methods.
     #
-    context_method :logger
+    context_method :logger, :form_authenticity_token, :protect_against_forgery?, :request_forgery_protection_token, :config, :cookies, :flash, :default_url_options
+    
+    # id and param are simply delegated to the model.
+    #
+    # This makes it possible to use the view_model
+    # for e.g. url generation:
+    # * edit_user_path(view_model)
+    #
+    delegate :id, :to_param, :to => :model
+    
+    # Delegate dom id to the action controller record identifier.
+    #
+    def dom_id *args
+      if args.present?
+        context.dom_id *args
+      else
+        ActionController::RecordIdentifier.dom_id model
+      end
+    end
+    
+    # Make all the dynamically generated routes (restful routes etc.)
+    # available in the view_model
+    #
+    Rails.application.routes.install_helpers self if Rails.application
+
+    # include these helpers by default
+    #
+    helper Helpers::View
+    helper Helpers::Mapping
     
     # Renders the given partial in the view_model's view root in the format given.
     #
@@ -199,6 +296,22 @@ module ViewModels
       #
       attr_reader :model, :context
       
+      # CaptureHelper needs this.
+      #
+      attr_accessor :output_buffer
+      
+      # alias the context as controller
+      #
+      alias controller context
+      
+      # Returns a view instance for render_xxx.
+      #
+      # @todo Try getting a view instance from the controller.
+      #
+      def renderer
+        View.new context, self._helpers
+      end
+      
       # Internal render method that uses the options to get a view instance
       # and then referring to its class for rendering.
       #
@@ -212,9 +325,7 @@ module ViewModels
       
       # 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.
+      # @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

data/lib/{shared/lib/view_models → view_models}/context_extractor.rb

@@ -4,17 +4,21 @@ module ViewModels
   
   # Extracts controllers for a living from unsuspecting views.
   #
-  # Note: This is actually only needed in Rails. In Padrino, the context is always the app.
-  #
   class ContextExtractor
     
+    # The context
+    #
     attr_reader :context
     
+    # Initialize the Context extractor
+    # @param [ActionController, ActionMailer, ActionView] context Some render context
+    #
     def initialize context
       @context = context
     end
     
     # Extracts a controller from the context.
+    # @return [ActionController] an instance of action controller
     #
     def extract
       context = self.context

data/lib/{shared/lib/view_models → view_models}/extensions/model_reader.rb

@@ -2,15 +2,23 @@
 #
 #
 module ViewModels
+  
+  # Extensions of the View Model Class
+  #
   module Extensions
+    
+    # Model Reader extension. Allows to define model readers on view models, accessing attributes and methods
+    # on models
+    #
     module ModelReader
       
       # Define a reader for a model attribute. Acts as a filtered delegation to the model. 
       #
       # You may specify a :filter_through option that is either a symbol or an array of symbols. The return value
-      # from the model will be filtered through the functions (arity 1) and then passed back to the receiver. 
+      # from the model will be filtered through the functions (arity 1) and then passed back to the receiver.
+      # @param [Symbol, Hash] attributes_and_options The attributes and options for the model reader
       #
-      # Example: 
+      # @example install different model readers
       #
       #   model_reader :foobar                                        # same as delegate :foobar, :to => :model
       #   model_reader :foobar, :filter_through => :h                 # html escape foobar 
@@ -32,6 +40,7 @@ module ViewModels
         end
         
         # Extract filter_through options from the options hash if there are any.
+        # @param [Hash] options the options to split
         #
         def split options
           @filters = if options.last.kind_of?(Hash)
@@ -42,6 +51,9 @@ module ViewModels
           @attributes = options
         end
         
+        # Render the options to an array
+        # @return [Array] The attributes and the filters in this order
+        #
         def to_a
           [attributes, filters]
         end
@@ -53,13 +65,19 @@ module ViewModels
       #
       class FilteredDelegationInstaller
         
+        # The attributes target, attributes, filters
+        #
         attr_reader :target, :attributes, :filters
         
+        # Initialize a new filtered delegation
+        # @param [ViewModel] target the target to install the filtered delegation in
+        # @param [ModelReader::Options] options The options for the filtered delegation
+        #
         def initialize target, options
           @target, @attributes, @filters = target, *options
         end
         
-        # Install install
+        # Install a reader for each attribute
         #
         def install
           attributes.each { |attribute| install_reader(attribute) }
@@ -67,10 +85,8 @@ module ViewModels
         
         # Install a reader for the given name with the given filters.
         #
-        # Example:
-        # # Installs a reader for model.attribute
-        # #
-        # * install_reader :attribute
+        # @example Installs a reader for model.attribute
+        #   install_reader :attribute
         #
         def install_reader attribute
           target.class_eval reader_definition_for(attribute)
@@ -79,7 +95,7 @@ module ViewModels
         # Defines a reader for the given model attribute and filtering
         # through the given filters.
         # 
-        # Note: The filters are applied from last to first element.
+        # @note The filters are applied from last to first element.
         #
         def reader_definition_for attribute
           "def #{attribute}; #{filtered_left_parentheses}model.#{attribute}#{right_parentheses}; end"
@@ -88,7 +104,7 @@ module ViewModels
         # Combines left parentheses and filters.
         #
         def filtered_left_parentheses
-          filters.zip(left_parentheses).to_s
+          filters.zip(left_parentheses).join
         end
         
         # Generates the needed amount of parentheses to match the left parentheses.
@@ -99,10 +115,8 @@ module ViewModels
         
         # Generates an array of left parentheses with
         # length <amount of filters>
-        # Example:
-        # # 4 Filters
-        # # 
-        # left_parentheses # => ['(', '(', '(', '(']
+        # @example for 4 Filters
+        #   left_parentheses # => ['(', '(', '(', '(']
         #
         def left_parentheses
           ['('] * filters.size

data/lib/{rails2/lib → view_models}/extensions/view.rb

@@ -5,15 +5,20 @@
 #
 module ViewModels
   module Extensions
+    
+    # Extensions for the View instance
+    #
     module View
       
-      #
+      # Renders the template with the given options
+      # @param [RenderOptions::Base] options The options to render with
       #
       def render_with options
         render options.to_render_options
       end
 
       # Finds the template in the view paths at the given path, with its format.
+      # @param [String] path the template path
       #
       def find_template path
         view_paths.find_template path, template_format rescue nil