blocks 1.2.5 → 2.1.0

data/CHANGELOG.rdoc

@@ -0,0 +1,49 @@
+2.1.0 (July 3, 2013)
+* Biggest change is that this gem was moved back to the blocks repo and renamed from building-blocks to blocks, it's original name.
+* changed rendering so that partials are no longer rendered by default
+* surrounding_tag_surrounds_before_and_after_blocks is now false, by default, meaning that if a block has a surrounding_tag, it will only render the block's contents inside that tag, and any before and after blocks will render outside that tag.
+* allows render options to be skipped or provider new helper methods, building blocks from the controller, got rid of aliases for "blocks", specify render order?
+
+2.0.0 (October 18, 2012)
+
+* Added ability to render a collection of objects and specify the surrounding elements and the html to apply to those surrounding elements
+  For example: blocks.render :test, :collection => @cuisine_types, :as => :cuisine_type, :surrounding_tag => "div", :surrounding_tag_html => {:class => Proc.new {cycle("even", "odd")}}
+* Added ability to specify "around" blocks, i.e. blocks of view code that render around another block of code, such as:
+  <% blocks.around :test_block do |content_block| %>
+    <h1>
+      <%= content_block.call %>
+    </h1>
+  <% end %> %>
+* Added a util method BuildingBlocks.render_template(self, partial, options={}, &block) that makes the templating feature easier to use
+  (as opposed to calling the long way: BuildingBlocks::Base.new(self, options={}).render_template(partial, &block))
+* Aliased "#blocks" method that is available to views as "#buildingblocks", "#bb", and "#building_blocks"
+* Aliased "#after" method to "#for", so that you can now call <%= blocks.for :block_name %> (should be slightly more familiar to users of content_for with yield)
+* Added a "#setup" method to initialize BuildingBlocks globally (for example: BuildingBlocks.setup do |config| config.template_folder = "shared" end)
+* Cleaned up the organization of the code base and now using autoload instead of require
+* Removed :use_partials_for_before_and_after_hooks option from 1.2.2
+
+1.2.3 (February 9, 2012)
+
+* Created two new utility methods: evaluated_procs and evaluated_proc that allow parameters for blocks to be Proc objects so long as these methods are called to evaluate them. (These methods have been carried over and renamed from the table-for gem where they were used to be able to dynamically specify table css classes, styles, and ids at runtime).
+
+1.2.2 (February 9, 2012)
+
+* Allow :use_partials and :use_partials_for_before_and_after_hooks to be passed in as initialization options to BuildingBlocks::Base to control whether BuildingBlocks attempts to render partials when "blocks.render" is called.
+
+1.2.1 (February 7, 2012)
+
+* Only try to render "before" and "after" blocks as partials if that BuildingBlocks::USE_PARTIALS_FOR_BEFORE_AND_AFTER_HOOKS is globally set to true (set to false now by default)
+
+1.2.0 (February 5, 2012)
+
+* Changed prototype for "use" method, such that the name of the block being rendered is now a required parameter.
+* Documented BuildingBlocks::Base more thoroughly
+* Changed the blocks.use method to blocks.render (blocks.use is still available for legacy purposes)
+* Removed the original render method and replaced with render_template that takes the partial and block to render as arguments.
+
+1.1.0 (February 4, 2012)
+
+* Ability to disable use of partials when rendering a block
+* Ability to disable use of partials for before and after hooks
+* Complete test coverage
+* :template_folder and :variable options are no longer being passed in as part of the options hash to defined blocks and partials

data/README.rdoc

@@ -1,141 +1 @@
-= Blocks
-
-Wiki[http://wiki.github.com/hunterae/blocks]
-
-Blocks is a replacement / complement to content_for with yield. It allows a user to specify a block capable of taking parameters that may be passed in when using that block. A user may also specify other blocks to be prepended or appended before or after a specific block is rendered. A template may also be specified to blocks that will provide the layout for a specific component and provide default implementations for its blocks. In this way, blocks is able to offer a very simple to use table generator ({table_for}[https://github.com/hunterae/blocks/wiki/table_for]) and list generator (list_for).
-
-== Installation
-
-In <b>Rails 3</b>, add this to your Gemfile.
-
-  gem "blocks"
-
-In <b>Rails 2</b>, add this to your environment.rb file. (At this time, it is untested in Rails 2)
-
-  config.gem "blocks"
-
-Alternatively, you can install it as a plugin.
-
-  rails plugin install git://github.com/hunterae/blocks.git
-
-
-== Getting Started
-
-What makes blocks particularly powerful is that it represent a combination of the ruby definition of blocks and partials. A block may be defined inline utilizing syntax similar to that of content_for:
-
-  <%= blocks.define :some_block_name, :some_parameter => 1, :some_parameter2 => 2 do |options| %>
-    <%= options[:some_parameter] %>
-    <%= options[:some_parameter2] %>
-    <%= options[:some_parameter3] %>
-  <% end %>
-
-or it may be written as a partial, existing in the controller view directory for whatever controller renders the view, or the globally configured blocks directory (views/blocks by default). The above block definition might then be written in the file views/blocks/_some_block_name.html.erb:
-
-  <%= some_parameter if defined?(some_parameter)%>
-  <%= some_parameter2 if defined?(some_parameter2) %>
-  <%= some_parameter3 if defined?(some_parameter3) %>
-
-Notice that in the context of a partial, we have direct access to the parameters as local variables. However, since we're not utilizing "blocks.define" to create our block, we can't specify the default parameters :some_parameter and :some_parameter2 as we do in the first example. This has the potential to cause a runtime exception in the context of partials and we will need to assure that optional parameters are defined using "defined?". 
-
-In the first example, we specified two parameters that are provided automatically to the block named "some_block_name". They are "some_parameter" and "some_parameter2". In addition, the definition of the block is assuming that the user will be passing in another parameter called "some_parameter3". However, all parameters are passed in in a hash (or local variables for partials), no error will occur if the user fails to specify "some_parameter3".
-
-Now, we may use the above block as follows:
-
-  <%= blocks.use :some_block_name %>
-  
-The system will first look for a block that's been defined inline by the name :some_block_name. If it cannot find one, it will try and render a partial with the same name within the current controller's view directory. Failing to find that, it will try and render a partial within the global blocks view directory (by default, views/blocks). If that partial also does not exist, it will give up and render nothing. (See [[Render Order]])
-  
-Here, we will see the output "1 2" for the first example (and "" for the second example). But if we pass in "some_parameter3", as follows:
-
-  <%= blocks.use :some_block_name, :some_parameter3 => 3 %>
-
-Then we will see "1 2 3" for the first example (and "3" for the second example). Additionally, we can override any of the previous parameters when using a block simply by passing in the new value as a parameter:
-
-  <%= blocks.use :some_block_name, :some_parameter2 => "overridden", :some_parameter3 => 3 %>
-  
-In this case, we will see "1 overridden 3" for the first example (and "overridden 3" for the second example). Thus, we now have content_for but with parameters, and additional intelligence by utilizing partials.
-
-== table_for
-
-table_for is a useful example of how blocks may be utilized in an invaluable way. It is built entirely using the core blocks library. It is exposed as a helper method with the following prototype:
-
-  table_for(records, options={}, &block)
-
-For example, if you have an Array of objects that respond to the following [:name, :email, :phonenumber] e.g. 
-
-  @records = [OpenStruct.new({:name => "The Name", :email => "The Email", :phonenumber => "A phone number"}),
-              OpenStruct.new({:name => "The Second Name", :email => "The Second Email", :phonenumber => "A second phone number"})]
-
-And using table_for you can very easily specify intricate details about the table (Note: most of the options in this example are optional):
-
-  <%= table_for @records, 
-              :table_html => {:id => "records"}, 
-              :header_html => {:style => "color:red"},
-              :row_html => {:class => lambda { |parameters| cycle('odd', 'even')}},
-              :column_html => {:style => "color:green"} do |table| %>
-    <%= table.column :name, :column_html => {:style => "color:blue"}, :header_html => {:style => "color:orange"} %>
-    <%= table.column :email %>
-    <%= table.column :phonenumber, :column_html => {:style => "color:orange"}, :header_html => {:style => "color:blue"} %>
-    <%= table.column :label => "???" do %>
-      Some Random Column
-    <% end %>
-  <% end %>
-
-Will generate the following table:
-
-  <table id="records">
-    <thead>
-      <tr>
-        <th style="color:orange">Name</th>    
-        <th style="color:red">Email</th>    
-        <th style="color:blue">Phonenumber</th>    
-        <th style="color:red">???</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr class="odd">
-        <td style="color:blue">The Name</td>    
-        <td style="color:green">The Email</td>    
-        <td style="color:orange">A phone number</td>    
-        <td style="color:green">Some Random Column</td>
-      </tr>
-      <tr class="even">
-        <td style="color:blue">The Second Name</td>    
-        <td style="color:green">The Second Email</td>    
-        <td style="color:orange">A second phone number</td>   
-        <td style="color:green">Some Random Column</td>
-      </tr>
-    </tbody>
-  </table>
-  
-See {table_for}[https://github.com/hunterae/blocks/wiki/table_for] for details.  
-
-== Building Layouts
-
-Utilizing blocks, we can rethink the way we define our templates. Everywhere where we might be tempted to write "yield :some_block_name", we can replace with "blocks.use :some_block_name". This gives us
-the ability to provide a default implementation for that block if it cannot be found (see {Providing a Default Implementation of a Block}[https://github.com/hunterae/blocks/wiki/Providing-a-Default-Implementation-of-a-Block]), and provides hooks for being able to render code before and after :some_block_name, utilizing "blocks.before :some_block_name" and "blocks.after :some_block_name" (See {Before and After Blocks}[https://github.com/hunterae/blocks/wiki/Before-and-After-Blocks]]).
-
-See {Building Layouts}[https://github.com/hunterae/blocks/wiki/Building-Layouts] for more details on how to utilize Blocks to build layouts.
-
-== Wiki Docs
-
-* {Basics}[https://github.com/hunterae/blocks/wiki/Basics]
-* {Specifying your blocks as controller level partials}[https://github.com/hunterae/blocks/wiki/Specifying-your-blocks-as-controller-level-partials]
-* {Specifying your blocks as global partials}[https://github.com/hunterae/blocks/wiki/Specifying-your-blocks-as-global-partials]
-* {How Inline Blocks, Controller Level Blocks, and Global Blocks Work Together}[https://github.com/hunterae/blocks/wiki/How-Inline-Blocks,-Controller-Level-Blocks,-and-Global-Blocks-Work-Together]
-* {Building Layouts}[https://github.com/hunterae/blocks/wiki/Building-Layouts]
-* {Render Order}[https://github.com/hunterae/blocks/wiki/Render-Order]
-* {Before and After Blocks}[https://github.com/hunterae/blocks/wiki/Before-and-After-Blocks]
-* {Providing a Default Implementation of a Block}[https://github.com/hunterae/blocks/wiki/Providing-a-Default-Implementation-of-a-Block]
-* {table_for}[https://github.com/hunterae/blocks/wiki/table_for]
-* {Overriding the defaults in table_for}[https://github.com/hunterae/blocks/wiki/Overriding-the-defaults-in-table_for]
-* {Defining your own reusage table_for implementation}[https://github.com/hunterae/blocks/wiki/Defining-your-own-reusage-table_for-implementation]
-* {See more}[https://github.com/hunterae/blocks/wiki]
-
-== Questions or Problems?
-
-If you have any issues with Blocks which you cannot find the solution to in the documentation[https://github.com/hunterae/blocks/wiki], please add an {issue on GitHub}[https://github.com/hunterae/blocks/issues] or fork the project and send a pull request.
-
-== Special Thanks
-
-Thanks to Todd Fisher of Captico for implementation help and setup of gem and to Jon Phillips for suggestions and use case help.
+Note: I am going to be completely rewriting this documentation, and what was here may have been invalid so stay tuned.

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+# If you want to make this the default task
+task :default => :spec
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "blocks"
+    gemspec.summary = "Blocks is an intricate way of rendering blocks of code, while combining some of the best features of content blocks and partials, and adding several new features that go above and beyond what a simple content_for with yield or a render :partial is capable of doing."
+    gemspec.description = "Blocks goes beyond blocks and partials"
+    gemspec.email = "hunterae@gmail.com"
+    gemspec.homepage = "http://github.com/hunterae/blocks"
+    gemspec.authors = ["Andrew Hunter"]
+    gemspec.files =  FileList["[A-Z]*", "{lib,spec,rails}/**/*"] - FileList["**/*.log", "Gemfile", "Gemfile.lock"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+2.1.0

data/lib/blocks.rb

@@ -1,5 +1,31 @@
-require 'blocks/container'
-require 'blocks/builder'
-require 'blocks/table_for'
-require 'blocks/list_for'
-require 'blocks/engine'
+require "action_view"
+require "action_controller"
+
+module Blocks
+  autoload :Base,          "blocks/base"
+  autoload :Container,     "blocks/container"
+  autoload :ViewAdditions, "blocks/view_additions"
+  autoload :ControllerAdditions, "blocks/controller_additions"
+
+  mattr_accessor :template_folder
+  @@template_folder = "blocks"
+
+  mattr_accessor :use_partials
+  @@use_partials = false
+
+  mattr_accessor :surrounding_tag_surrounds_before_and_after_blocks
+  @@surrounding_tag_surrounds_before_and_after_blocks = false
+
+  # Shortcut for using the templating feature / rendering templates
+  def self.render_template(view, partial, options={}, &block)
+    Blocks::Base.new(view, options).render_template(partial, &block)
+  end
+
+  # Default way to setup Blocks
+  def self.setup
+    yield self
+  end
+end
+
+ActionView::Base.send :include, Blocks::ViewAdditions::ClassMethods
+ActionController::Base.send :include, Blocks::ControllerAdditions::ClassMethods

data/lib/blocks/base.rb

@@ -0,0 +1,672 @@
+module Blocks
+  class Base
+    # a pointer to the ActionView that called Blocks
+    attr_accessor :view
+
+    # Hash of block names to Blocks::Container objects
+    attr_accessor :blocks
+
+    # Array of Blocks::Container objects, storing the order of blocks as they were queued
+    attr_accessor :queued_blocks
+
+    # counter, used to give unnamed blocks a unique name
+    attr_accessor :anonymous_block_number
+
+    # A Hash of queued_blocks arrays; a new array is started when method_missing is invoked
+    attr_accessor :block_groups
+
+    # These are the options that are passed into the initalize method
+    attr_accessor :global_options
+
+    # The default folder to look in for global partials
+    attr_accessor :template_folder
+
+    # The variable to use when rendering the partial for the templating feature (by default, "blocks")
+    attr_accessor :variable
+
+    # Boolean variable for whether Blocks should attempt to render blocks as partials if a defined block cannot be found
+    attr_accessor :use_partials
+
+    # Boolean variable for whether Blocks should render before and after blocks inside or outside of a collections' elements' surrounding tags
+    attr_accessor :surrounding_tag_surrounds_before_and_after_blocks
+
+    # Checks if a particular block has been defined within the current block scope.
+    #   <%= blocks.defined? :some_block_name %>
+    # Options:
+    # [+name+]
+    #   The name of the block to check
+    def defined?(name)
+      !blocks[name.to_sym].nil?
+    end
+
+    # Define a block, unless a block by the same name is already defined.
+    #   <%= blocks.define :some_block_name, :parameter1 => "1", :parameter2 => "2" do |options| %>
+    #     <%= options[:parameter1] %> and <%= options[:parameter2] %>
+    #   <% end %>
+    #
+    # Options:
+    # [+name+]
+    #   The name of the block being defined (either a string or a symbol)
+    # [+options+]
+    #   The default options for the block definition. Any or all of these options may be overrideen by
+    #   whomever calls "blocks.render" on this block.
+    # [+block+]
+    #   The block that is to be rendered when "blocks.render" is called for this block.
+    def define(name, options={}, &block)
+      collection = options.delete(:collection)
+
+      if collection
+        collection.each do |object|
+          define(evaluated_proc(name, object, options), options, &block)
+        end
+      else
+        self.define_block_container(name, options, &block)
+      end
+
+      nil
+    end
+
+    # Define a block, replacing an existing block by the same name if it is already defined.
+    #   <%= blocks.define :some_block_name, :parameter1 => "1", :parameter2 => "2" do |options| %>
+    #     <%= options[:parameter1] %> and <%= options[:parameter2] %>
+    #   <% end %>
+    #
+    #   <%= blocks.replace :some_block_name, :parameter3 => "3", :parameter4 => "4" do |options| %>
+    #     <%= options[:parameter3] %> and <%= options[:parameter4] %>
+    #   <% end %>
+    # Options:
+    # [+name+]
+    #   The name of the block being defined (either a string or a symbol)
+    # [+options+]
+    #   The default options for the block definition. Any or all of these options may be overrideen by
+    #   whomever calls "blocks.render" on this block.
+    # [+block+]
+    #   The block that is to be rendered when "blocks.render" is called for this block.
+    def replace(name, options={}, &block)
+      blocks[name.to_sym] = nil
+      self.define_block_container(name, options, &block)
+      nil
+    end
+
+    # Render a block, first rendering any "before" blocks, then rendering the block itself, then rendering
+    # any "after" blocks. Additionally, a collection may also be passed in, and Blocks will render
+    # an the block, along with corresponding before and after blocks for each element of the collection.
+    # Blocks will make either two or four different attempts to render the block, depending on how use_partials
+    # is globally set, or an option is passed in to the render call to either use partials or skip partials:
+    #   1) Look for a block that has been defined inline elsewhere, using the blocks.define method:
+    #      <% blocks.define :wizard do |options| %>
+    #        Inline Block Step#<%= options[:step] %>.
+    #      <% end %>
+    #
+    #      <%= blocks.render :wizard, :step => @step %>
+    #   2) [IF use_partials is globally set to true or passed in as a runtime option,
+    #       and skip_partials is not passed in as a runtime option]
+    #      Look for a partial within the current controller's view directory:
+    #      <%= blocks.render :wizard, :step => @step %>
+    #
+    #      <!-- In /app/views/pages/_wizard.html.erb (assuming it is the pages controller running): -->
+    #      Controller-specific Block Step# <%= step %>.
+    #   3) [IF use_partials is globally set to true or passed in as a runtime option,
+    #       and skip_partials is not passed in as a runtime option]
+    #      Look for a partial with the global blocks view directory (by default /app/views/blocks/):
+    #      <%= blocks.render :wizard, :step => @step %>
+    #
+    #      <!-- In /app/views/blocks/_wizard.html.erb: -->
+    #      Global Block Step#<%= step %>.
+    #   4) Render the default implementation for the block if provided to the blocks.render call:
+    #      <%= blocks.render :wizard, :step => @step do |options| do %>
+    #        Default Implementation Block Step#<%= options %>.
+    #      <% end %>
+    # Options:
+    # [+name_or_container+]
+    #   The name of the block to render (either a string or a symbol)
+    # [+*args+]
+    #   Any arguments to pass to the block to be rendered (and also to be passed to any "before" and "after" blocks).
+    #   The last argument in the list can be a hash and can include the following special options:
+    #     [:collection]
+    #       The collection of elements to render blocks for
+    #     [:as]
+    #       The variable name to assign the current element in the collection being rendered over
+    #     [:surrounding_tag]
+    #       The content tag to render around a block, which might be particularly useful when rendering a collection of blocks,
+    #       such as for a list or table
+    #     [:surrounding_tag_html]
+    #       The attributes to be applied to the HTML content tag, such as styling or special properties. Please note, any Procs passed
+    #       in will automatically be evaluated (For example: :class => lambda { cycle("even", "odd") })
+    #     [:use_partials]
+    #       Overrides the globally defined use_partials and tells Blocks to render partials in trying to render a block
+    #     [:skip_partials]
+    #       Overrides the globally defined use_partials and tells Blocks to not render any partials in trying to render a block
+    # [+block+]
+    #   The default block to render if no such block block that is to be rendered when "blocks.render" is called for this block.
+    def render(name_or_container, *args, &block)
+      options = args.extract_options!
+      collection = options.delete(:collection)
+
+      buffer = ActiveSupport::SafeBuffer.new
+
+      if collection
+        as = options.delete(:as)
+
+        collection.each do |object|
+          cloned_args = args.clone
+          cloned_args.unshift(object)
+          cloned_options = options.clone
+          cloned_options = cloned_options.merge(object.options) if object.is_a?(Blocks::Container)
+          cloned_args.push(cloned_options)
+
+          block_name = evaluated_proc(name_or_container, *cloned_args)
+          as_name = (as.presence || block_name).to_sym
+          cloned_options[as_name] = object
+
+          buffer << render(block_name, *cloned_args, &block)
+        end
+      else
+        surrounding_tag = options.delete(:surrounding_tag)
+        surrounding_tag_html = options.delete(:surrounding_tag_html)
+
+        args.push(options)
+
+        if surrounding_tag_surrounds_before_and_after_blocks
+          buffer << content_tag(surrounding_tag, surrounding_tag_html, *args) do
+            temp_buffer = ActiveSupport::SafeBuffer.new
+            temp_buffer << render_before_blocks(name_or_container, *args)
+            temp_buffer << render_block_with_around_blocks(name_or_container, *args, &block)
+            temp_buffer << render_after_blocks(name_or_container, *args)
+          end
+        else
+          buffer << render_before_blocks(name_or_container, *args)
+          buffer << content_tag(surrounding_tag, surrounding_tag_html, *args) do
+            render_block_with_around_blocks(name_or_container, *args, &block)
+          end
+          buffer << render_after_blocks(name_or_container, *args)
+        end
+      end
+
+      buffer
+    end
+    alias use render
+
+    # Render a block, first rendering any "before" blocks, then rendering the block itself, then rendering
+    # any "after" blocks. Additionally, a collection may also be passed in, and Blocks will render
+    # an the block, along with corresponding before and after blocks for each element of the collection.
+    # Blocks will make two different attempts to render block:
+    #   1) Look for a block that has been defined inline elsewhere, using the blocks.define method:
+    #      <% blocks.define :wizard do |options| %>
+    #        Inline Block Step#<%= options[:step] %>.
+    #      <% end %>
+    #
+    #      <%= blocks.render :wizard, :step => @step %>
+    #   2) Render the default implementation for the block if provided to the blocks.render call:
+    #      <%= blocks.render :wizard, :step => @step do |options| do %>
+    #        Default Implementation Block Step#<%= options %>.
+    #      <% end %>
+    # Options:
+    # [+name_or_container+]
+    #   The name of the block to render (either a string or a symbol)
+    # [+*args+]
+    #   Any arguments to pass to the block to be rendered (and also to be passed to any "before" and "after" blocks).
+    #   The last argument in the list can be a hash and can include the following special options:
+    #     [:collection]
+    #       The collection of elements to render blocks for
+    #     [:as]
+    #       The variable name to assign the current element in the collection being rendered over
+    #     [:surrounding_tag]
+    #       The content tag to render around a block, which might be particularly useful when rendering a collection of blocks,
+    #       such as for a list or table
+    #     [:surrounding_tag_html]
+    #       The attributes to be applied to the HTML content tag, such as styling or special properties. Please note, any Procs passed
+    #       in will automatically be evaluated (For example: :class => lambda { cycle("even", "odd") })
+    # [+block+]
+    #   The default block to render if no such block block that is to be rendered when "blocks.render" is called for this block.
+    def render_without_partials(name_or_container, *args, &block)
+      options = args.extract_options!
+      options[:skip_partials] = true
+      args.push(options)
+      render(name_or_container, *args, &block)
+    end
+
+    # Render a block, first rendering any "before" blocks, then rendering the block itself, then rendering
+    # any "after" blocks. Additionally, a collection may also be passed in, and Blocks will render
+    # an the block, along with corresponding before and after blocks for each element of the collection.
+    # Blocks will make four different attempts to render block:
+    #   1) Look for a block that has been defined inline elsewhere, using the blocks.define method:
+    #      <% blocks.define :wizard do |options| %>
+    #        Inline Block Step#<%= options[:step] %>.
+    #      <% end %>
+    #
+    #      <%= blocks.render :wizard, :step => @step %>
+    #   2) Look for a partial within the current controller's view directory:
+    #      <%= blocks.render :wizard, :step => @step %>
+    #
+    #      <!-- In /app/views/pages/_wizard.html.erb (assuming it is the pages controller running): -->
+    #      Controller-specific Block Step# <%= step %>.
+    #   3) Look for a partial with the global blocks view directory (by default /app/views/blocks/):
+    #      <%= blocks.render :wizard, :step => @step %>
+    #
+    #      <!-- In /app/views/blocks/_wizard.html.erb: -->
+    #      Global Block Step#<%= step %>.
+    #   4) Render the default implementation for the block if provided to the blocks.render call:
+    #      <%= blocks.render :wizard, :step => @step do |options| do %>
+    #        Default Implementation Block Step#<%= options %>.
+    #      <% end %>
+    # Options:
+    # [+name_or_container+]
+    #   The name of the block to render (either a string or a symbol)
+    # [+*args+]
+    #   Any arguments to pass to the block to be rendered (and also to be passed to any "before" and "after" blocks).
+    #   The last argument in the list can be a hash and can include the following special options:
+    #     [:collection]
+    #       The collection of elements to render blocks for
+    #     [:as]
+    #       The variable name to assign the current element in the collection being rendered over
+    #     [:surrounding_tag]
+    #       The content tag to render around a block, which might be particularly useful when rendering a collection of blocks,
+    #       such as for a list or table
+    #     [:surrounding_tag_html]
+    #       The attributes to be applied to the HTML content tag, such as styling or special properties. Please note, any Procs passed
+    #       in will automatically be evaluated (For example: :class => lambda { cycle("even", "odd") })
+    # [+block+]
+    #   The default block to render if no such block block that is to be rendered when "blocks.render" is called for this block.
+    def render_with_partials(name_or_container, *args, &block)
+      options = args.extract_options!
+      options[:use_partials] = true
+      args.push(options)
+      render(name_or_container, *args, &block)
+    end
+
+    # Queue a block for later rendering, such as within a template.
+    #   <%= Blocks::Base.new(self).render_template("shared/wizard") do |blocks| %>
+    #     <% blocks.queue :step1 %>
+    #     <% blocks.queue :step2 do %>
+    #       My overridden Step 2 |
+    #     <% end %>
+    #     <% blocks.queue :step3 %>
+    #     <% blocks.queue do %>
+    #       | Anonymous Step 4
+    #     <% end %>
+    #   <% end %>
+    #
+    #   <!-- In /app/views/shared/wizard -->
+    #   <% blocks.define :step1 do %>
+    #     Step 1 |
+    #   <% end %>
+    #
+    #   <% blocks.define :step2 do %>
+    #     Step 2 |
+    #   <% end %>
+    #
+    #   <% blocks.define :step3 do %>
+    #     Step 3
+    #   <% end %>
+    #
+    #   <% blocks.queued_blocks.each do |block| %>
+    #     <%= blocks.render block %>
+    #   <% end %>
+    #
+    #   <!-- Will render: Step 1 | My overridden Step 2 | Step 3 | Anonymous Step 4-->
+    # Options:
+    # [+*args+]
+    #   The options to pass in when this block is rendered. These will override any options provided to the actual block
+    #   definition. Any or all of these options may be overriden by whoever calls "blocks.render" on this block.
+    #   Usually the first of these args will be the name of the block being queued (either a string or a symbol)
+    # [+block+]
+    #   The optional block definition to render when the queued block is rendered
+    def queue(*args, &block)
+      self.queued_blocks << self.define_block_container(*args, &block)
+      nil
+    end
+
+    # Render a partial, treating it as a template, and any code in the block argument will impact how the template renders
+    #   <%= Blocks::Base.new(self).render_template("shared/wizard") do |blocks| %>
+    #     <% blocks.queue :step1 %>
+    #     <% blocks.queue :step2 do %>
+    #       My overridden Step 2 |
+    #     <% end %>
+    #     <% blocks.queue :step3 %>
+    #     <% blocks.queue do %>
+    #       | Anonymous Step 4
+    #     <% end %>
+    #   <% end %>
+    #
+    #   <!-- In /app/views/shared/wizard -->
+    #   <% blocks.define :step1 do %>
+    #     Step 1 |
+    #   <% end %>
+    #
+    #   <% blocks.define :step2 do %>
+    #     Step 2 |
+    #   <% end %>
+    #
+    #   <% blocks.define :step3 do %>
+    #     Step 3
+    #   <% end %>
+    #
+    #   <% blocks.queued_blocks.each do |block| %>
+    #     <%= blocks.render block %>
+    #   <% end %>
+    #
+    #   <!-- Will render: Step 1 | My overridden Step 2 | Step 3 | Anonymous Step 4-->
+    # Options:
+    # [+partial+]
+    #   The partial to render as a template
+    # [+block+]
+    #   An optional block with code that affects how the template renders
+    def render_template(partial, &block)
+      render_options = global_options.clone
+      render_options[self.variable] = self
+      render_options[:captured_block] = view.capture(self, &block) if block_given?
+
+      view.render partial, render_options
+    end
+
+    # Add a block to render before another block. This before block will be put into an array so that multiple
+    #  before blocks may be queued. They will render in the order in which they are declared when the
+    #  "blocks#render" method is called. Any options specified to the before block will override any options
+    #  specified in the block definition.
+    #   <% blocks.define :wizard, :option1 => 1, :option2 => 2 do |options| %>
+    #     Step 2 (:option1 => <%= options[option1] %>, :option2 => <%= options[option2] %>)<br />
+    #   <% end %>
+    #
+    #   <% blocks.before :wizard, :option1 => 3 do
+    #     Step 0 (:option1 => <%= options[option1] %>, :option2 => <%= options[option2] %>)<br />
+    #   <% end %>
+    #
+    #   <% blocks.before :wizard, :option2 => 4 do
+    #     Step 1 (:option1 => <%= options[option1] %>, :option2 => <%= options[option2] %>)<br />
+    #   <% end %>
+    #
+    #   <%= blocks.render :wizard %>
+    #
+    #   <!-- Will render:
+    #     Step 0 (:option1 => 3, :option2 => 2)<br />
+    #     Step 1 (:option1 => 1, :option2 => 4)<br />
+    #     Step 2 (:option1 => 1, :option2 => 2)<br />
+    #   -->
+    #
+    #   <%= blocks.render :wizard, :step => @step %>
+    # Options:
+    # [+name+]
+    #   The name of the block to render this code before when that block is rendered
+    # [+options+]
+    #   Any options to specify to the before block when it renders. These will override any options
+    #   specified when the block was defined.
+    # [+block+]
+    #   The block of code to render before another block
+    def before(name, options={}, &block)
+      self.queue_block_container("before_#{name.to_s}", options, &block)
+      nil
+    end
+    alias prepend before
+
+    # Add a block to render after another block. This after block will be put into an array so that multiple
+    #  after blocks may be queued. They will render in the order in which they are declared when the
+    #  "blocks#render" method is called. Any options specified to the after block will override any options
+    #  specified in the block definition.
+    #   <% blocks.define :wizard, :option1 => 1, :option2 => 2 do |options| %>
+    #     Step 2 (:option1 => <%= options[option1] %>, :option2 => <%= options[option2] %>)<br />
+    #   <% end %>
+    #
+    #   <% blocks.after :wizard, :option1 => 3 do
+    #     Step 3 (:option1 => <%= options[option1] %>, :option2 => <%= options[option2] %>)<br />
+    #   <% end %>
+    #
+    #   <% blocks.after :wizard, :option2 => 4 do
+    #     Step 4 (:option1 => <%= options[option1] %>, :option2 => <%= options[option2] %>)<br />
+    #   <% end %>
+    #
+    #   <%= blocks.render :wizard %>
+    #
+    #   <!-- Will render:
+    #     Step 2 (:option1 => 1, :option2 => 2)<br />
+    #     Step 3 (:option1 => 3, :option2 => 2)<br />
+    #     Step 4 (:option1 => 1, :option2 => 4)<br />
+    #   -->
+    #
+    #   <%= blocks.render :wizard, :step => @step %>
+    # Options:
+    # [+name+]
+    #   The name of the block to render this code after when that block is rendered
+    # [+options+]
+    #   Any options to specify to the after block when it renders. These will override any options
+    #   specified when the block was defined.
+    # [+block+]
+    #   The block of code to render after another block
+    def after(name, options={}, &block)
+      self.queue_block_container("after_#{name.to_s}", options, &block)
+      nil
+    end
+    alias append after
+    alias for after
+
+    # Add a block to render around another block. This around block will be put into an array so that multiple
+    #  around blocks may be queued. They will render in the order in which they are declared when the
+    #  "blocks#render" method is called, with the last declared around block being rendered as the outer-most code, and
+    #  the first declared around block rendered as the inner-most code. Any options specified to the after block will override any options
+    #  specified in the block definition. The user of an around block must declare a block with at least one parameter and
+    #  should invoke the #call method on that argument.
+    #
+    #   <% blocks.define :my_block do %>
+    #     test
+    #   <% end %>
+    #
+    #   <% blocks.around :my_block do |content_block| %>
+    #     <h1>
+    #       <%= content_block.call %>
+    #     </h1>
+    #   <% end %>
+    #
+    #   <% blocks.around :my_block do |content_block| %>
+    #     <span style="color:red">
+    #       <%= content_block.call %>
+    #     </span>
+    #   <% end %>
+    #
+    #   <%= blocks.render :my_block %>
+    #
+    #   <!-- Will render:
+    #   <h1>
+    #     <span style="color:red">
+    #       test
+    #     </span>
+    #   </h1>
+    #
+    # Options:
+    # [+name+]
+    #   The name of the block to render this code around when that block is rendered
+    # [+options+]
+    #   Any options to specify to the around block when it renders. These will override any options
+    #   specified when the block was defined.
+    # [+block+]
+    #   The block of code to render after another block
+    def around(name, options={}, &block)
+      self.queue_block_container("around_#{name.to_s}", options, &block)
+      nil
+    end
+
+    def evaluated_procs(*args)
+      options = args.shift.presence || {}
+      if options.is_a?(Proc)
+        evaluated_proc(options, *args)
+      else
+        options.inject({}) { |hash, (k, v)| hash[k] = evaluated_proc(v, *args); hash}
+      end
+    end
+
+    def evaluated_proc(*args)
+      return nil unless args.present?
+      v = args.shift
+      v.is_a?(Proc) ? v.call(*(args[0, v.arity])) : v
+    end
+
+    protected
+
+    # If a method is missing, we'll assume the user is starting a new block group by that missing method name
+    def method_missing(m, *args, &block)
+      options = args.extract_options!
+
+      # If the specified block group has already been defined, it is simply returned here for iteration.
+      #  It will consist of all the blocks used in this block group that have yet to be rendered,
+      #   as the call for their use occurred before the template was rendered (where their definitions likely occurred)
+      return self.block_groups[m] unless self.block_groups[m].nil?
+
+      # Allows for nested block groups, store the current block positions array and start a new one
+      original_queued_blocks = self.queued_blocks
+      self.queued_blocks = []
+      self.block_groups[m] = self.queued_blocks
+
+      # Capture the contents of the block group (this will only capture block definitions and block renders; it will ignore anything else)
+      view.capture(global_options.merge(options), &block) if block_given?
+
+      # restore the original block positions array
+      self.queued_blocks = original_queued_blocks
+      nil
+    end
+
+    def initialize(view, options={})
+      self.template_folder = options[:template_folder] ? options.delete(:template_folder) : Blocks.template_folder
+      self.variable = (options[:variable] ? options.delete(:variable) : :blocks).to_sym
+      self.view = view
+      self.global_options = options
+      self.queued_blocks = []
+      self.blocks = {}
+      self.anonymous_block_number = 0
+      self.block_groups = {}
+      self.use_partials = options[:use_partials].nil? ? Blocks.use_partials : options.delete(:use_partials)
+      self.surrounding_tag_surrounds_before_and_after_blocks = options[:surrounding_tag_surrounds_before_and_after_blocks].nil? ? Blocks.surrounding_tag_surrounds_before_and_after_blocks : options.delete(:surrounding_tag_surrounds_before_and_after_blocks)
+    end
+
+    # Return a unique name for an anonymously defined block (i.e. a block that has not been given a name)
+    def anonymous_block_name
+      self.anonymous_block_number += 1
+      "block_#{anonymous_block_number}"
+    end
+
+    def render_block_with_around_blocks(name_or_container, *args, &block)
+      name = name_or_container.is_a?(Blocks::Container) ? name_or_container.name.to_sym : name_or_container.to_sym
+      around_name = "around_#{name.to_s}".to_sym
+
+      around_blocks = blocks[around_name].present? ? blocks[around_name].clone : []
+
+      content_block = Proc.new do
+        block_container = around_blocks.shift
+        if block_container
+          view.capture(content_block, *(args[0, block_container.block.arity - 1]), &block_container.block)
+        else
+          render_block(name_or_container, *args, &block)
+        end
+      end
+      content_block.call
+    end
+
+    # Render a block, first trying to find a previously defined block with the same name
+    def render_block(name_or_container, *args, &block)
+      options = args.extract_options!
+
+      buffer = ActiveSupport::SafeBuffer.new
+
+      block_options = {}
+      if (name_or_container.is_a?(Blocks::Container))
+        name = name_or_container.name.to_sym
+        block_options = name_or_container.options
+      else
+        name = name_or_container.to_sym
+      end
+
+      if blocks[name]
+        block_container = blocks[name]
+        args.push(global_options.merge(block_container.options).merge(block_options).merge(options))
+        buffer << view.capture(*(args[0, block_container.block.arity]), &block_container.block)
+      elsif (use_partials || options[:use_partials]) && !options[:skip_partials]
+        begin
+          begin
+            buffer << view.render("#{name.to_s}", global_options.merge(block_options).merge(options))
+          rescue ActionView::MissingTemplate
+            buffer << view.render("#{self.template_folder}/#{name.to_s}", global_options.merge(block_options).merge(options))
+          end
+        rescue ActionView::MissingTemplate
+          args.push(global_options.merge(options))
+          buffer << view.capture(*(args[0, block.arity]), &block) if block_given?
+        end
+      else
+        args.push(global_options.merge(options))
+        buffer << view.capture(*(args[0, block.arity]), &block) if block_given?
+      end
+
+      buffer
+    end
+
+    # Render all the before blocks for a partial block
+    def render_before_blocks(name_or_container, *args)
+      render_before_or_after_blocks(name_or_container, "before", *args)
+    end
+
+    # Render all the after blocks for a partial block
+    def render_after_blocks(name_or_container, *args)
+      render_before_or_after_blocks(name_or_container, "after", *args)
+    end
+
+    # Utility method to render either the before or after blocks for a partial block
+    def render_before_or_after_blocks(name_or_container, before_or_after, *args)
+      options = args.extract_options!
+
+      block_options = {}
+      if (name_or_container.is_a?(Blocks::Container))
+        name = name_or_container.name.to_sym
+        block_options = name_or_container.options
+      else
+        name = name_or_container.to_sym
+        block_options = blocks[name].options if blocks[name]
+      end
+
+      before_name = "#{before_or_after}_#{name.to_s}".to_sym
+      buffer = ActiveSupport::SafeBuffer.new
+
+      blocks[before_name].each do |block_container|
+        args_clone = args.clone
+        args_clone.push(global_options.merge(block_options).merge(block_container.options).merge(options))
+        buffer << view.capture(*(args_clone[0, block_container.block.arity]), &block_container.block)
+      end if blocks[before_name].present?
+
+      buffer
+    end
+
+    # Build a Blocks::Container object given the passed in arguments
+    def build_block_container(*args, &block)
+      options = args.extract_options!
+      name = args.first ? args.shift : self.anonymous_block_name
+      block_container = Blocks::Container.new
+      block_container.name = name.to_sym
+      block_container.options = options
+      block_container.block = block
+      block_container
+    end
+
+    # Build a Blocks::Container object and add it to an array of containers matching it's block name
+    #  (used only for queuing a collection of before and after blocks for a particular block name)
+    def queue_block_container(*args, &block)
+      block_container = self.build_block_container(*args, &block)
+      if blocks[block_container.name].nil?
+        blocks[block_container.name] = [block_container]
+      else
+        blocks[block_container.name] << block_container
+      end
+    end
+
+    # Build a Blocks::Container object and add it to the global hash of blocks if a block by the same
+    #  name is not already defined
+    def define_block_container(*args, &block)
+      block_container = self.build_block_container(*args, &block)
+      blocks[block_container.name] = block_container if blocks[block_container.name].nil? && block_given?
+      block_container
+    end
+
+    def content_tag(tag, tag_html, *args, &block)
+      if tag
+        view.content_tag(tag, block.call, evaluated_procs(tag_html, *args))
+      else
+        block.call
+      end
+    end
+  end
+end