view_models 1.5.6 → 1.5.7

data/README.textile

@@ -1,22 +1,16 @@
-h1. ViewModels for Rails
+h1. ViewModels
 
-h2. Previous contributors
+A view model/representer solution for Rails.
 
-Code:
+h2. Features
 
-"Kaspar":http://github.com/kschiess @http://github.com/kschiess@, for the first, and foundation-laying version.
-
-"Niko":http://github.com/niko @http://github.com/niko@, for handling collections and better Helpers handling.
-
-"Andi":http://github.com/andi @http://github.com/andi@, for refactoring it into a cleaner structure.
-
-Inspiration:
-
-"Severin":http://github.com/severin @http://github.com/severin@, for bits and pieces here and there.
-
-"rainhead":http://github.com/rainhead @http://github.com/rainhead@, for the idea to subclass ActionView::Base.
-
-Important note: These guys rock! :)
+* Polymorph view model objects that correspond to model objects.
+* View model specific templates.
+* Hierarchical Template Rendering: Allows generalized templates for a class tree of view models.
+* Helper methods directly on the view models.
+* No view related code in the models.
+* A clean API for use in Rails.
+* 100% rcov coverage, nice metrics, gallons of blood and sweat by excellent contributors.
 
 h2. Installation
 
@@ -24,7 +18,7 @@ h3. Rails Plugin
 
 @script/plugin install git://github.com/floere/view_models.git@
 
-h3. Gem for use in Rails
+h3. Gem (for use in Rails)
 
 @gem install view_models@
 
@@ -34,221 +28,13 @@ and then adding the line
 
 in your environment.rb.
 
-h2. Description
-
-A possible view_model solution, i.e. no view logic in model code.
-
-h2. Feedback
-
-Ask/Write florian.hanke@gmail.com if you have questions/feedback, thanks! :)
-Fork if you have improvements. Send me a pull request, it is much appreciated.
-
-h2. Problem
-
-Display Methods are not well placed either in
-* models: Violation of the MVC principle.
-* helpers: No Polymorphism.
-
-h2. Solution
-
-A thin proxy layer over a model, with access to the controller, used by the view or controller.
-
-@The view@ -> to @the view model@ which in turn -> @the model@ and -> @the controller@
-
-h2. Examples & What you can do
-
-h3. A quick one
-
-In the view:
-<pre><code>user = view_model_for @user
-%h1= "You, #{user.full_name}, the user"
-%h2 This is how you look as a search result:
-= user.render_as :result
-%h2 This is how you look as a Vcard:
-= user.render_as :vcard</code></pre>
-In the view model:
-<pre><code>class ViewModels::User < ViewModels::Project
-  model_reader :first_name, :last_name
-  def full_name
-    "#{last_name}, #{first_name}"
-  end
-end</code></pre>
-In the model:
-<pre><code>class User < ActiveRecord::Base
-end</code></pre>
-Also, there are two partials in @app/views/view_models/user/@, @_result.html.haml@ and @_vcard.html.haml@ that define how the result of @user.render_as :result@ and @user.render_as :vcard@ look. The ViewModel can be accessed inside the view by using the local variable @view_model@.
-
-h3. Getting a view_model in a view or a controller.
-
-Call view_model_for: @view_model_instance = view_model_for model_instance@
-By convention, uses @ViewModels::Model::Class::Name@, thus prefixing @ViewModels::@ to the model class name.
-
-Note: You can override @specific_view_model_class_for@ to change the mapping of model to class, or make it dynamic.
-
-h3. Getting a collection view model in a view.
-
-The collection view_model renders each of the given items with its view_model.
-
-Call collection_view_model_for: @collection_view_model_instance = collection_view_model_for enumerable_containing_model_instances@
-
-Rendering a list: @collection_view_model_instance.list@
-
-Rendering a collection: @collection_view_model_instance.collection@
-
-Rendering a table: @collection_view_model_instance.table@
-
-Rendering a pagination: @collection_view_model_instance.pagination@
-Note: Only works if the passed parameter for @collection_view_model_for@ is a @PaginationEnumeration@.
-
-Important note:
-  As of yet it is needed to copy the templates/views/view_models/collection
-  directory to the corresponding location in app/views/view_models/collection.
-  This is only needed if you wish to use the collection view model.
-  The collections are automatically copied if you use the generator.
-
-Note: Rewrite the collection templates as needed, they are rather basic.
-
-h3. Writing filtered delegate methods on the view model.
-
-Will create two delegate methods first_name and last_name that delegate to the model: @model_reader :first_name, :last_name@
-
-Will create a description delegate method that filters the model value through h: @model_reader :description, :filter_through => :h@
-
-Will create a description delegate method that filters the model value through first textilize, then h: @model_reader :description, :filter_through => [:textilize, :h]@
-
-Will create both a first_name and last_name delegate method that filters the model value through first textilize, then h: @model_reader :first_name, :last_name, :filter_through => [:textilize, :h]@
-Note: Filter methods can be any method on the view_model with arity 1.
-
-h3. Rendering view model templates
-
-Use @render_as(template_name, options)@.
-
-Gets a @ViewModels::Model::Class@ instance: @view_model = view_model_for Model::Class.new@
-
-Gets a @ViewModels::<model_instance.class.name>@ instance: @view_model = view_model_for model_instance@
-
-Renders the 'example' partial in view_models/model/class: @view_model.render_as :example@
-Note: Renders a format depending on the request. ../index.text will render example.text.erb.
-
-Renders the 'example.text.erb' partial in view_models/model/class: @view_model.render_as :example, :format => :text@
-Note: If the partial cannot be found, it will traverse the view model hierarchy upwards to find a partial template.
-
-Locals can be passed through as usual: @view_model.render_as :example, :format => :text, :locals => { :name => value }@
-
-h3. Rails Helpers in ViewModels
-
-Use @helper@ as you would in the controller.
-@helper ActionView::Helpers::UrlHelper@
-@helper ApplicationHelper@
-Note: It is helpful to create a superclass to all view models in the project with generally used helpers.
-We use @ViewModels::Project@ a lot, for example. See example below.
-
-h3. Controller Delegate Methods
-
-Use @controller_method(*args)@.
-
-Delegates current_user and logger on the view_model to the controller: @controller_method :current_user, :logger@
-
-h2. The Generator
-
-Generates view model class, spec, and views. Use as follows:
-
-@script/generate view_models <view model class name>@
-@script/generate view_models User@
-
-@script/generate view_models <view model class name> <partials for render_as, separated by space>@
-@script/generate view_models User compact extensive list_item table_item@
-
-h2. One Big Fat Example
-
-The following classes all have specs of course ;) But are not shown since they don't help the example.
-
-@ViewModels@ superclass for this project.
-
-We include all of Rails' helpers for the view models in this project.
-Also, we include the @ApplicationHelper@.
-
-We delegate @logger@ and @current_user@ calls in the view models to the active controller.
-
-<pre>
-<code>
-class ViewModels::Project < ViewModels::Base
-  
-  # Our ApplicationHelper.
-  #
-  helper ApplicationHelper
-  
-  # We want to be able to call view_model_for in our view_models.
-  #
-  helper ViewModels::Helpers::Rails
-  
-  # Include all common view helpers.
-  #
-  helper ViewModels::Helpers::View
-  
-  # We want to be able to use id, dom_id, to_param on the view model.
-  #
-  # Note: Overrides the standard dom_id method from the RecordIdentificationHelper.
-  #
-  include ViewModels::Extensions::ActiveRecord
-  
-  controller_method :logger, :current_user
-  
-end
-
-# All items have a description that needs to be filtered by textilize.
-#
-class ViewModels::Item < ViewModels::Project
-  model_reader :description, :filter_through => :textilize
-  # Use price in the view as follows:
-  # = view_model.price - will display e.g. 16.57 CHF, since it is filtered first through localize_currency
-  model_reader :price, :filter_through => :localize_currency
-  
-  # Converts a database price tag to the users chosen value, with the users preferred currency appended.
-  # If the user is Swiss, localize_currency will convert 10 Euros to "16.57 CHF" 
-  #
-  def localize_currency(price_in_euros)
-    converted_price = current_user.convert_price(price_in_euros)
-    "#{converted_price} #{current_user.currency.to_s}"
-  end
-end
-
-# This class also has partial templates in the directory
-#   app/views/view_models/book
-# that are called
-#   _cart_item.html.haml
-#   _cart_item.text.erb
-#
-# Call view_model_for on a book in the view or controller to get this view_model.
-#
-class ViewModels::Book < ViewModels::Item
-  model_reader :author, :title, :pages
-  model_reader :excerpt, :filter_through => :textilize
-  
-  def header
-    content_tag(:h1, "#{author} – #{title}")
-  end
-  
-  def full_description
-    content_tag(:p, "#{excerpt} #{description}", :class => 'description full')
-  end
-end
+h2. Links Galore!
 
-# This class also has partial templates in the directory
-#   app/views/view_models/toy
-# that are called
-#   _cart_item.html.haml
-#   _cart_item.text.erb
-#
-# Call view_model_for on a toy in the view or controller to get this view_model.
-#
-class ViewModels::Toy < ViewModels::Item
-  model_reader :starting_age, :small_dangerous_parts
-  
-  def obligatory_parental_warning
-    "Warning, this toy can only be used by kids ages #{starting_age} and up. Your department of health. Thank you."
-  end
-  
-end
-</code>
-</pre>
+"Usage, Examples, In-depth Infos [Wiki]":http://wiki.github.com/floere/view_models/
+"Reference [RDoc]":http://rdoc.info/projects/floere/view_models
+"Gem [RubyGems.org]":http://rubygems.org/gems/view_models
+"Mailing List":http://groups.google.com/group/view_models/topics
+"Bug Tracker":http://github.com/floere/view_models/issues
+"Metrics":http://getcaliper.com/caliper/project?repo=git://github.com/floere/view_models.git
+"Source [Github]":http://github.com/floere/view_models
+"Homepage":http://floere.github.com/view_models/

data/TODO.textile

@@ -1,4 +1,5 @@
 h1. Next up
 
-* Explore possibilities to include Modules in hierarchical rendering.
-* Encapsule the rather bloated hierarchical rendering in a HierarchicalRendering object that mediates the whole rendering process.
+* Encapsule the rather bloated hierarchical rendering in a HierarchicalRendering object that mediates the whole rendering process.
+
+--* Explore possibilities to include Modules in hierarchical rendering.--

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :minor: 5
-:patch: 6
+:patch: 7
 :major: 1

data/lib/experimental/modules_in_render_hierarchy.rb

@@ -1,10 +1,10 @@
 module ModulesInRenderHierarchy
-  
+
   def self.included klass
     klass.extend ClassMethods
     klass.metaclass.alias_method_chain :include, :superclass_override
   end
-  
+
   module ClassMethods
     def include_with_superclass_override mod
       original_superclass = superclass
@@ -17,5 +17,5 @@ module ModulesInRenderHierarchy
       end
     end
   end
-  
+
 end

data/lib/view_models/render_options.rb

@@ -4,7 +4,7 @@ module ViewModels
   #
   module RenderOptions
     
-    # Hold a number of options for rendering.
+    # Base class for Partial and Template.
     #
     class Base
       
@@ -57,35 +57,43 @@ module ViewModels
           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
-        
-        #
+        # Specific path is a specifically named view path, with slashes.
         #
         def specific_path name
           self.path             = File.dirname name
           self.name_with_prefix = File.basename name
         end
         
-        #
+        # Incomplete path is a view path without slashes. The view models will
+        # try to find out where to take the template from.
         #
         def incomplete_path name
           self.path             = nil
           self.name_with_prefix = name
         end
         
+        # Add the prefix to the template name.
+        #
+        # Note: Will add an underscore if it's a partial.
+        #
         def name_with_prefix= name
           self.name = "#{self.prefix}#{name}"
         end
         
+        # Extracts the template name from the given parameter.
+        #
+        # If it's a hash, it will remove and use the :partial option.
+        # If not, it will use that.
+        #
+        def deoptionize template_name
+          if template_name.kind_of?(Hash)
+            @options.merge! template_name
+            @options.delete :partial
+          else
+            template_name
+          end
+        end
+        
       end
       
       # A specific container for partial rendering.

data/spec/integration/integration_spec.rb

@@ -60,7 +60,7 @@ describe 'Integration' do
   #     end
   #   end
   # end
-  
+
   describe 'ActiveRecord Extensions' do
     before(:each) do
       @view_model.extend ViewModels::Extensions::ActiveRecord

data/spec/integration/view_models/module_for_rendering.rb

@@ -1,7 +1,7 @@
 module ModuleForRendering
-  
+
   def module_method
     "Hello!"
   end
-  
+
 end

data/spec/lib/helpers/rails_spec.rb

@@ -32,8 +32,6 @@ describe ViewModels::Helpers::Rails do
         specific_view_model_mapping.should == {}
       end
       it "should raise an ArgumentError on an non-mapped model" do
-        # TODO really clear enough that one should provide a ViewModel with an initializer with 2 params?
-        #
         class SomeViewModelClass; end
         specific_view_model_mapping[String] = SomeViewModelClass
         lambda {
@@ -43,8 +41,6 @@ describe ViewModels::Helpers::Rails do
     end
     describe "no specific mapping" do
       it "should raise on an non-mapped model" do
-        # TODO really clear enough that the view model class is missing?
-        #
         lambda {
           view_model_for(42)
         }.should raise_error(NameError, "uninitialized constant ViewModels::Fixnum")

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 1
   - 5
-  - 6
-  version: 1.5.6
+  - 7
+  version: 1.5.7
 platform: ruby
 authors: 
 - Florian Hanke
@@ -17,7 +17,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-04 00:00:00 +01:00
+date: 2010-04-15 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency