0
@@ -1,31 +1,27 @@
0
 module Waves
0
 
0
-  # Views in Waves are ultimately responsible for generating the response body. Views mirror controllers - both have full access to the request and response, and both may modify the response and even short-circuit the request processing and return a result by calling redirect or calling Response#finish.
0
+  # Views in Waves are responsible for processing templates to produce the response body. Views mirror controllers - both have full access to the request and response, and both may modify the response and even short-circuit the request processing and return a result by calling redirect or calling Response#finish.
0
   #
0
   # Views, like controllers, are classes with methods that are invoked by a mapping block (see Waves::Mapping). View instance methods take an assigns hash that are typically converted into instance variables accesible from within a template.
0
   #
0
   # Like controllers, a default implementation is provided by the +waves+ command when you first create your application. This default can be overridden to change the behaviors for all views, or you can explicitly define a View class to provide specific behavior for one view.
0
   #
0
-  # The default implementation simply determines which template to render and renders it, returning the result as a string. This machinery is provided by the View mixin, so it is easy to create your own View implementations.
0
+  # The default implementation simply determines which template to render and renders it, returning the result as a string. This machinery is provided by the View mixin, so it is easy to create your own View implementations.  You typically will not need to modify or define View classes.
0
   #
0
   # = Templates
0
   #
0
-  # Although you won't typically need to modify or define View classes, you will often create and modify templates. Templates can be evaluated using any registered Renderer. Two are presently packaged with Waves: Markaby and Erubis. Templates have access to the assigns hash passed to the view method as instance variables. These can be explicitly defined by the mapping file or whomever is invoking the view.
0
+  # Template files can be evaluated using any registered Renderer. Two are presently packaged with Waves: Markaby and Erubis. Templates have access to the assigns hash passed to the view method as instance variables. These can be explicitly defined by the mapping file or whomever is invoking the view.
0
   #
0
-  # *Example*
0
-  #
0
-  #   # Find the story named 'home' and pass it as @story into the "story/show" template
0
-  #   use( :story ) | controller { find( 'home' ) } | view { |x| show( :story => x ) }
0
   #
0
   # = Helpers
0
   #
0
-  # Helper methods can be defined for any view template by simply defining them within the default Helper module in <tt>helpers/default.rb</tt> of the generated application. Helpers specific to a particular View class can be explicitly defined by creating a helper module that corresponds to the View class. For examples, for the +User+ View class, you would define a helper module in <tt>user.rb</tt> named +User+.
0
+  # Helper methods can be defined for any view template by simply defining them within the default Helper module in <tt>helpers/default.rb</tt> of the generated application. Helpers specific to a particular View class can be explicitly defined by creating a helper module that corresponds to the View class. For examples, for the +User+ View class, you would define a helper module in <tt>helpers/user.rb</tt> named +User+.
0
   #
0
   # The default helper class initially includes a wide-variety of helpers, including helpers for layouts, Textile formatting, rendering forms, and nested views, as well as helpers for accessing the request and response objects. More helpers will be added in future releases, but in many cases, there is no need to include all of them in your application.
0
   #
0
   # = Layouts
0
   #
0
-  # Layouts are defined using the +Layout+ view class, and layout templates are placed in the +layout+ directory of the +templates+ directory. Layouts are explicitly set within a template using the +layout+ method.
0
+  # Layouts are explicitly set within a template using the +layout+ method.  Layout templates live in the +layout+ directory of the +templates+ directory. Layouts are defined using the +Layout+ view class.
0
   #
0
   # *Example*
0
   #
0
@@ -55,16 +51,17 @@ module Waves
0
 
0
   module Views
0
 
0
-    # A class method that returns the known Renderers, which is any module that is defined within Waves::Renderers and includes the Renderers::Mixin.
0
-    # You can define new Renderers simply be reopening Waves::Renderers and defining a module that mixes in Renderers::Mixin.
0
+    # Returns the known Renderers, effectively any module that includes Renderers::Mixin.
0
     def self.renderers ; @renderers ||= [] ; end
0
     
0
+    # Return the first renderer which thinks it can handle the supplied path.
0
     def self.renderer_for(path)
0
       @renderers.find do |renderer|
0
         File.exists?( renderer.filename( path ) )
0
       end
0
     end
0
     
0
+    # Render the template at the given path, using the assigns hash to supply instance variables.
0
     def self.render( path, assigns = {} )
0
       template = Views.renderer_for(path) || Views.renderer_for( :generic / File.basename(path) )
0
       raise NoTemplateError.new( path ) if template.nil?
0
@@ -74,27 +71,30 @@ module Waves
0
     class NoTemplateError < Exception # :nodoc:
0
     end
0
 
0
-    # The View mixin simply sets up the machinery for invoking a template, along with methods for accessing
0
-    # the request assigns and the standard interface for invoking a view method.
0
+    # Waves::Views::Mixin outfits a class with the methods needed to act as a View.  Unrecognized methods
0
+    # are treated as calls to +render+, with the method name supplied as the path to the template.
0
     module Mixin
0
 
0
       attr_reader :request
0
 
0
       include Waves::ResponseMixin
0
 
0
-      def self.included( c )
0
-        def c.process( request, *args, &block )
0
+      # On inclusion in a class, this module defines a method:
0
+      #
0
+      #   process(request, *args, &block)
0
+      #
0
+      # This method creates a new instance of the class and uses instance_exec to run
0
+      # the &block with the *args.
0
+      def self.included( mod )
0
+        def mod.process( request, *args, &block )
0
           self.new( request ).instance_exec( *args, &block )
0
         end
0
       end
0
 
0
-      def initialize( request ) ; @request = request ; @layout = :default ; end
0
-
0
-      # Return the first renderer for which a template file can be found.
0
-      # Uses Renderers::Mixin.filename to construct the filename for each renderer.
0
-      def renderer(path) ; Views.renderer_for(path) ; end
0
+      def initialize( request ) ; @request = request ; end
0
 
0
-      # Render the template found in the directory named after this view (snake cased, of course)
0
+      # Render the template found in the directory named after this view (snake cased, of course).
0
+      #
0
       # E.g. App::Views::Gnome.new.render( "stink" ) would look for templates/gnome/stink.<ext>
0
       def render( path, assigns = {} )
0
         qpath = "#{self.class.basename.snake_case}/#{path}"
0
@@ -107,7 +107,7 @@ module Waves
0
 
0
     end
0
 
0
-    # I'm sorry ... :)
0
+    # The basic View from which most application views will inherit.
0
     class Base ; include Mixin ; end
0
 
0
   end

0
@@ -15,20 +15,13 @@ Dir.chdir(File.dirname(__FILE__)) do
0
     it "defines an error for missing templates" do
0
       defined?(Waves::Views::NoTemplateError).should.not.be.nil
0
     end
0
-  
0
-  end
0
-
0
-  describe "A class which has included Waves::Views::Mixin" do
0
-  
0
-    before do
0
-      @view = TestView.new(mock(:request))
0
-    end
0
-  
0
+    
0
     it "uses the first renderer for which it can find a template file with the associated extension" do
0
-      @view.renderer("foo").should == Waves::Renderers::Erubis
0
-      @view.renderer("moo").should == Waves::Renderers::Erubis
0
-      @view.renderer("bleat").should == nil
0
+      Waves::Views.renderer_for("foo").should == Waves::Renderers::Erubis
0
+      Waves::Views.renderer_for("moo").should == Waves::Renderers::Erubis
0
+      Waves::Views.renderer_for("bleat").should == nil
0
     end
0
   
0
   end
0
+
0
 end
0
\ No newline at end of file