building-blocks 0.0.7 → 0.0.8

data/README.rdoc

@@ -0,0 +1,241 @@
+= BuildingBlocks
+
+BuildingBlocks is an intricate way of rendering blocks of code, while adding several features that go above and beyond what a simple content_for with yield is capable of doing.
+
+1. It provides the ability to pass parameters to a defined block of code (something content_for with yield is incapable of doing). 
+2. It provides "before" and "after" hooks that can render code before and after a specified block of code is rendered (this can be particularly useful when you want to specify a dynamic list of javascript or stylesheet includes after your standard includes).
+3. It allows the developer to define a block of code as a global partial, a controller-specific partial, or an inline block of code, all with the same syntax usage.
+4. (Probably the most powerful aspect) It allows the developer to build complex reusable UI components by essentially providing their own DTD (see the separate project {table-for}[https://github.com/hunterae/table-for] for an example of a nice table builder that was created using minimal code by apply BuildingBlocks).
+
+== Installation
+
+In <b>Rails 3</b>, add this to your Gemfile.
+
+  gem "building-blocks"
+
+== Defining and using blocks
+
+The syntax for defining and using blocks is similar to how content_for and yield are used. At its simplest form:
+
+  <% blocks.define :my_block do %>
+    My code to render
+  <% end %>
+
+  <!-- Elsewhere, you can use the block as follows -->
+  <%= blocks.use :my_block %>
+
+  <!-- Will render: My code to render -->
+
+== Passing parameters to blocks
+
+Parameters may also be passed into defined blocks:
+
+  <% blocks.define :my_block do |options| %>
+    The user of this block passed in "<%= options[:my_parameter] %>" as :my_parameter.
+  <% end %>
+
+  <!-- Elsewhere, you can use the block as follows -->
+  <%= blocks.use :my_block, :my_parameter => "The value I'm passing in"  %>
+
+  <!-- Will render: The user of this block passed in "The value I'm passing in" as :my_parameter. -->
+
+  <!-- If the anticipated parameters are not passed: -->
+  <%= blocks.use :my_block %>
+
+  <!-- Will render: The user of this block passed in "" as :my_parameter. -->
+
+The parameters are not required, but unexpected results might occur if the "necessary" parameters are not passed in.
+
+== Passing non-hash parameters into defined blocks:
+
+  <% blocks.define :my_block do |first_parameter, second_parameter, options| %>
+    First parameter: <%= first_parameter %>, Second parameter: <%= second_parameter %>, Third parameter: <%= options[:third_parameter] %>
+  <% end %>
+
+  <!-- Elsewhere, you can use the block as follows -->
+  <%= blocks.use :my_block, "Value 1", 2, :third_parameter => "Value 3" %>
+
+  <!-- Will render: First parameter: Value 1, Second parameter: 2, Third parameter: Value 3 -->
+
+== Providing default values for parameters to blocks
+
+In the last example, the parameter the block was expecting was not passed in. For this reason, it is possible to specify default values for the parameters when you define a block. If parameters are passed in when the block is used, the values passed in override the default values.
+
+  <% blocks.define :my_block, :parameter1 => "Parameter 1", :parameter2 => "Parameter 2" do |options| %>
+    The values specified are :parameter1 = "<%= options[:parameter1] %>", :parameter2 = "<%= options[:parameter2] %>"
+  <% end %>
+
+  <!-- Elsewhere, you can use the block as follows (specifying zero, one, or both of the parameters the block uses) -->
+  <%= blocks.use :my_block %><br />
+  <%= blocks.use :my_block, :parameter1 => "New Parameter 1" %><br />
+  <%= blocks.use :my_block, :parameter2 => "New Parameter 2" %><br />
+  <%= blocks.use :my_block, :parameter1 => "New Parameter 1", :parameter2 => "New Parameter 2" %>
+
+  <!--
+  Will render:
+  The values specified are :parameter1 = "Parameter 1", :parameter2 = "Parameter 2"
+  The values specified are :parameter1 = "New Parameter 1", :parameter2 = "Parameter 2"
+  The values specified are :parameter1 = "Parameter 1", :parameter2 = "New Parameter 2"
+  The values specified are :parameter1 = "New Parameter 1", :parameter2 = "New Parameter 2"
+  -->
+
+== Providing a default definition for a block
+
+What happens if you attempt to "use" a block that hasn't been "define"d? Nothing will get rendered.
+
+However, you may want to provide a default definition for a block to "use" if such a block was never "define"d. You can do this as follows:
+
+  <%= blocks.use :my_block, :my_parameter_1 => "Parameter 1" do %>
+    This is my default definition of :my_block.
+  <% end %>
+
+In this case, BuildingBlocks will see if any block by the name :my_block has ever been defined. When it doesn't find one, it will simply render the default definition and you will see:
+  This is my default definition of :my_block.
+
+If however, you have defined :my_block elsewhere, it would have used that definition:
+
+  <% blocks.define :my_block do |options| %>
+    Some other definition of :my_block with :my_parameter_1 set to "<%= options[:my_parameter_1] %>"
+  <% end %>
+
+  <!-- Elsewhere, you can use the block as follows -->
+  <%= blocks.use :my_block, :my_parameter_1 => "Parameter 1" do %>
+    This is my default definition of :my_block.
+  <% end %>
+
+  <!-- Will render: Some other definition of :my_block with :my_parameter_1 set to "Parameter 1" -->
+  <!-- (since the block was defined, i.e. the default definition is not needed) -->
+
+== Using "before" and "after filters"
+
+"Before" and "After" hooks render code before and after the code produced by a "blocks.use" call. A practical example of this would be adding view-specific javascript and stylesheet includes to a global layout file.
+
+In your application.html layout file, you might use this as follows:
+
+  <html>
+    <head>
+      <%= blocks.use :includes do %>
+        <%= blocks.use :stylesheets do %>
+          <%= stylesheet_link_tag "jquery" %>
+        <% end %>
+        <%= blocks.use :javscripts do %>
+          <%= javascript_include_tag "jquery" %>
+        <% end %>
+      <% end %>
+    </head>
+    <body>
+      <%= yield %>
+    </body>
+  </html>
+
+Then, in a specific view that is rendered using this layout, you can add stylesheets before or after the list of stylesheets includes, before or after the list of javascript includes, or before or after the entire list of stylesheet and javascript includes. For example, index.html.erb might add in more stylesheets and javascripts:
+
+  <% blocks.before :includes do %>
+    <%= stylesheet_link_tag "first_overall_stylesheet" %>
+  <% end %>
+
+  <% blocks.after :includes do %>
+    <%= stylesheet_link_tag "last_overall_stylesheet" %>
+  <% end %>
+
+  <% blocks.before :stylesheets do %>
+    <%= stylesheet_link_tag "stylesheet_before_jquery" %>
+  <% end %>
+
+  <% blocks.after :stylesheets do %>
+    <%= stylesheet_link_tag "stylesheet_after_jquery" %>
+  <% end %>
+
+  <% blocks.before :javascripts do %>
+    <%= javascript_include_tag "javascript_before_jquery" %>
+  <% end %>
+
+  <% blocks.after :javascripts do %>
+    <%= javascript_include_tag "stylesheet_before_jquery" %>
+  <% end %>
+
+  <!--
+  When index.html.erb is rendered, it will output:
+  <html>
+    <head>
+      <link href="/stylesheets/first_overall_stylesheet.css" media="screen" rel="stylesheet" type="text/css" />
+      <link href="/stylesheets/stylesheet_before_jquery.css" media="screen" rel="stylesheet" type="text/css" />
+      <link href="/stylesheets/jquery.css" media="screen" rel="stylesheet" type="text/css" />
+      <link href="/stylesheets/stylesheet_after_jquery.css" media="screen" rel="stylesheet" type="text/css" />
+      <script src="/javascripts/javascript_before_jquery.js" type="text/javascript"></script>
+      <script src="/javascripts/jquery.js" type="text/javascript"></script>
+      <script src="/javascripts/javascript_after_jquery.js" type="text/javascript"></script>
+      <link href="/stylesheets/last_overall_stylesheet.css" media="screen" rel="stylesheet" type="text/css" />
+    </head>
+    <body>
+    </body>
+  </html>
+   -->
+(An alternative syntax to "blocks.before" and "blocks.after" would be, respectively, "blocks.prepend" and "blocks.append")
+
+== Blocks as Partials
+
+Using exactly the same syntax for "using" blocks, one can put the code to be rendered in it's own separate file (in a partial). When "blocks.use :some_block" is called, the system will first look for a block defined inline (i.e. one that has been defined using "blocks.define :some_block"). Failing to find that, it will see if a default implementation has been provided for the block and render it if one has been specified. Failing to find that, it will look for a partial by the same name in your current controller's view directory. And failing to find that partial, it will look for a partial in the global blocks' directory (by default, /app/views/blocks). Any parameters passed in as a hash will be initialized in the partial as local variables.
+
+As an example, consider the following code, running in a view for PagesController:
+
+  <%= blocks.use :wizard, :step => @step %>
+
+  <!-- 1) Check and see if there was a block defined called "wizard" somewhere prior to its use... No? then... -->
+  <!-- 2) Check and see if there is a default definition provided for "wizard", i.e. specified in the "blocks.use" call... No? Then... -->
+  <!-- 3) Check and see if there is a controller-specific partial /app/views/pages/wizard.html.erb. No? Then... -->
+  <!-- 4) Check and see if there is a global partial /app/views/blocks/wizard.html.erb. No? Then render nothing. -->
+
+Let's look at each example individually, written in the order that BuildingBlocks attempts to render them:
+
+1. Inline definition of a block:
+  <% blocks.define :wizard do |options| %>
+    Inline Block Step#<%= options[:step] %>.
+  <% end %>
+
+  <!-- Elsewhere, you can use the block as follows -->
+  <%= blocks.use :wizard, :step => @step %>
+2. Default implementation of a block:
+  <%= blocks.use :wizard, :step => @step do |options| do %>
+    Default Implementation Block Step#<%= options %>.
+  <% end %>
+3. Controller-specific partial:
+  <%= blocks.use :wizard, :step => @step %>
+
+  <!-- In /app/views/pages/_wizard.html.erb: -->
+  Controller-specific Block Step# <%= step %>.
+4. Global partial:
+  <%= blocks.use :wizard, :step => @step %>
+
+  <!-- In /app/views/blocks/_wizard.html.erb: -->
+  Global Block Step#<%= step %>.
+
+== Overall Render Order
+
+Putting all the pieces together from the previous examples, here is what BuildingBlock is doing when a block is rendered:
+link:/hunterae/building-blocks/raw/master/blocks_render_order.png
+
+== Templating
+
+The most advanced feature of BuildingBlocks is the ability to utilize it for templating and writing your own DTD specifications for the components you write.
+
+As an example, consider {table-for}[https://github.com/hunterae/table-for], a library that was written with minimal codes that provides its user with a very nice, easy-to-use table builder. A sample usage might look something like:
+
+  <%= table_for @users do |table| %>
+    <% table.column :name do |user| %>
+      <%= "#{user.first_name} #{user.last_name}" %>
+    <% end %>
+    <% table.column :email %>
+  <% end %>
+
+MORE EXPLANATION TO COME
+
+== MORE COMING SOON...
+
+== Questions or Problems?
+
+If you have any issues with BuildingBlocks which you cannot find the solution to in the documentation, please add an {issue on GitHub}[https://github.com/hunterae/building-blocks/issues] or fork the project and send a pull request.
+
+== Special Thanks
+
+Thanks to {Todd Fisher}[https://github.com/taf2] of LivingSocial for implementation help and setup of gem and {Jon Phillips}[https://github.com/elguapo1611] of LivingSocial for suggestions and use case help.

data/VERSION

@@ -1 +1 @@
-0.0.7
+0.0.8

data/lib/building-blocks.rb

@@ -2,7 +2,7 @@ require "action_view"
 
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 
-require "building_blocks/building_blocks"
+require "building_blocks/base"
 require "building_blocks/container"
 require "building_blocks/helper_methods"
 

data/lib/building_blocks/{building_blocks.rb → base.rb}

@@ -1,24 +1,22 @@
 module BuildingBlocks
   class Base
     attr_accessor :view
-    
-    attr_accessor :blocks 
-    
+
+    attr_accessor :blocks
+
     attr_accessor :block
-    
+
     # Array of BuildingBlocks::Container objects, storing the order of blocks as they were used
-    attr_accessor :block_positions
-    
+    attr_accessor :queued_blocks
+
     # counter, used to give unnamed blocks a unique name
     attr_accessor :anonymous_block_number
-    
-    attr_accessor :start_rendering_blocks 
-    
+
     attr_accessor :block_groups
 
     # These are the options that are passed into the initalize method
     attr_accessor :global_options
-    
+
     # Checks if a particular block has been defined within the current block scope.
     #   <%= blocks.defined? :some_block_name %>
     # Options:
@@ -27,40 +25,30 @@ module BuildingBlocks
     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 
+    #   The default options for the block definition. Any or all of these options may be overrideen by
     #   whomever calls "blocks.use" on this block.
     # [+block+]
     #   The block that is to be rendered when "blocks.use" is called for this block.
     def define(name, options={}, &block)
-      # Check if a block by this name is already defined.
-      if blocks[name.to_sym].nil?
-        # Store the attributes of the defined block in a container for later use
-        block_container = BuildingBlocks::Container.new
-        block_container.name = name
-        block_container.options = options
-        block_container.block = block
-      
-        blocks[name.to_sym] = block_container 
-      end
-      
+      self.define_block_container(name, options, &block)
       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 %>
@@ -68,58 +56,53 @@ module BuildingBlocks
     # [+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 
+    #   The default options for the block definition. Any or all of these options may be overrideen by
     #   whomever calls "blocks.use" on this block.
     # [+block+]
     #   The block that is to be rendered when "blocks.use" is called for this block.
     def replace(name, options={}, &block)
       blocks[name.to_sym] = nil
-      define(name, options, &block)
+      self.define_block_container(name, options, &block)
+      nil
     end
-  
+
     def use(*args, &block)
-      options = args.extract_options!      
-      
+      options = args.extract_options!
+
       # If the user doesn't specify a block name, we generate an anonymous block name to assure other
       #  anonymous blocks don't override its definition
       name = args.first ? args.shift : self.anonymous_block_name
-      
-      block_container = BuildingBlocks::Container.new
-      block_container.name = name
-      block_container.options = options
-      block_container.block = block
 
-      blocks[name.to_sym] = block_container if !name.is_a?(BuildingBlocks::Container) and blocks[name.to_sym].nil? and block_given?
-      
-      if start_rendering_blocks        
-        render_block name, args, options
-      else
-        # Delays rendering this block until the partial has been rendered and all the blocks have had a chance to be defined
-        self.block_positions << block_container 
-        nil
-      end
-      
-      # nil
+      self.render_block name, args, options
     end
-    
+
+    def queue(*args, &block)
+      options = args.extract_options!
+
+      # If the user doesn't specify a block name, we generate an anonymous block name to assure other
+      #  anonymous blocks don't override its definition
+      name = args.first ? args.shift : self.anonymous_block_name
+
+      # Delays rendering this block until the partial has been rendered and all the blocks have had a chance to be defined
+      self.queued_blocks << self.define_block_container(name, options, &block)
+      nil
+    end
+
     def render
-      self.start_rendering_blocks = false
-      
-      global_options[:captured_block] = view.capture(self, &self.block) if self.block
-      
-      self.start_rendering_blocks = true
+      raise "Must specify :template parameter in order to render" unless global_options[:template]
 
+      global_options[:captured_block] = view.capture(self, &self.block) if self.block
       view.render global_options[:template], global_options
     end
-    
+
     def before(name, options={}, &block)
       name = "before_#{name.to_s}".to_sym
-      
+
       block_container = BuildingBlocks::Container.new
       block_container.name = name
       block_container.options = options
       block_container.block = block
-      
+
       if view.blocks.blocks[name].nil?
         blocks[name] = [block_container]
       else
@@ -129,15 +112,15 @@ module BuildingBlocks
       nil
     end
     alias prepend before
-    
+
     def after(name, options={}, &block)
       name = "after_#{name.to_s}".to_sym
-      
+
       block_container = BuildingBlocks::Container.new
       block_container.name = name
       block_container.options = options
       block_container.block = block
-      
+
       if view.blocks.blocks[name].nil?
         blocks[name] = [block_container]
       else
@@ -147,51 +130,52 @@ module BuildingBlocks
       nil
     end
     alias append after
-    
+
     # 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, options={}, &block) 
+    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_block_positions = self.block_positions
-      self.block_positions = []
-      self.block_groups[m] = self.block_positions
-     
+      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 uses)
       view.capture(global_options.merge(options), &block) if block_given?
-      
+
       # restore the original block positions array
-      self.block_positions = original_block_positions
+      self.queued_blocks = original_queued_blocks
       nil
     end
-    
+
     protected
-    
+
     def initialize(view, options={}, &block)
       options[options[:variable] ? options[:variable].to_sym : :blocks] = self
       options[:templates_folder] = "blocks" if options[:templates_folder].nil?
-      
+
       self.view = view
       self.global_options = options
       self.block = block
-      self.block_positions = []
-      self.blocks = {}    
+      self.queued_blocks = []
+      self.blocks = {}
       self.anonymous_block_number = 0
-      self.block_groups = {}      
-      self.start_rendering_blocks = true
+      self.block_groups = {}
     end
-    
+
     def anonymous_block_name
       self.anonymous_block_number = self.anonymous_block_number + 1
       "block_#{anonymous_block_number}"
     end
-    
-    def render_block(name_or_container, args, runtime_options={})  
+
+    def render_block(name_or_container, args, runtime_options={})
       buffer = ActiveSupport::SafeBuffer.new
-      
+
       block_options = {}
       if (name_or_container.is_a?(BuildingBlocks::Container))
         name = name_or_container.name.to_sym
@@ -199,18 +183,18 @@ module BuildingBlocks
       else
         name = name_or_container.to_sym
       end
-      
+
       buffer << render_before_blocks(name_or_container, runtime_options)
-       
-      if blocks[name]  
+
+      if blocks[name]
         block_container = blocks[name]
-        
+
         args.push(global_options.merge(block_container.options).merge(block_options).merge(runtime_options))
-        
+
         # If the block is taking more than one parameter, we can use *args
         if block_container.block.arity > 1
           buffer << view.capture(*args, &block_container.block)
-          
+
         # However, if the block only takes a single parameter, we do not want ruby to try to cram the args list into that parameter
         #   as an array
         else
@@ -218,13 +202,13 @@ module BuildingBlocks
         end
       elsif view.blocks.blocks[name]
         block_container = view.blocks.blocks[name]
-        
+
         args.push(global_options.merge(block_container.options).merge(block_options).merge(runtime_options))
-        
+
         # If the block is taking more than one parameter, we can use *args
         if block_container.block.arity > 1
           buffer << view.capture(*args, &block_container.block)
-          
+
         # However, if the block only takes a single parameter, we do not want ruby to try to cram the args list into that parameter
         #   as an array
         else
@@ -242,15 +226,15 @@ module BuildingBlocks
           # This block does not exist and no partial can be found to satify it
         end
       end
-      
+
       buffer << render_after_blocks(name_or_container, runtime_options)
-      
+
       buffer
     end
-    
+
     def render_before_blocks(name_or_container, runtime_options={})
       options = global_options
-      
+
       block_options = {}
       if (name_or_container.is_a?(BuildingBlocks::Container))
         name = name_or_container.name.to_sym
@@ -258,39 +242,37 @@ module BuildingBlocks
       else
         name = name_or_container.to_sym
       end
-      
+
       before_name = "before_#{name.to_s}".to_sym
-      
-      if blocks[name]  
+
+      if blocks[name]
         block_container = blocks[name]
-        
         options = options.merge(block_container.options)
       elsif view.blocks.blocks[name]
         block_container = view.blocks.blocks[name]
-        
         options = options.merge(block_container.options)
-      end      
-      
+      end
+
       buffer = ActiveSupport::SafeBuffer.new
-      
+
       unless blocks[before_name].nil?
         blocks[before_name].each do |block_container|
           buffer << view.capture(options.merge(block_container.options).merge(block_options).merge(runtime_options), &block_container.block)
         end
       end
-      
+
       unless view.blocks.blocks[before_name].nil? || view.blocks.blocks == blocks
         view.blocks.blocks[before_name].each do |block_container|
           buffer << view.capture(options.merge(block_container.options).merge(block_options).merge(runtime_options), &block_container.block)
         end
       end
-      
+
       buffer
     end
-    
+
     def render_after_blocks(name_or_container, runtime_options={})
       options = global_options
-      
+
       block_options = {}
       if (name_or_container.is_a?(BuildingBlocks::Container))
         name = name_or_container.name.to_sym
@@ -298,34 +280,43 @@ module BuildingBlocks
       else
         name = name_or_container.to_sym
       end
-      
+
       after_name = "after_#{name.to_s}".to_sym
-      
-      if blocks[name]  
+
+      if blocks[name]
         block_container = blocks[name]
-        
+
         options = options.merge(block_container.options)
       elsif view.blocks.blocks[name]
         block_container = view.blocks.blocks[name]
-        
+
         options = options.merge(block_container.options)
-      end      
-      
+      end
+
       buffer = ActiveSupport::SafeBuffer.new
- 
+
       unless blocks[after_name].nil?
         blocks[after_name].each do |block_container|
           buffer << view.capture(options.merge(block_container.options).merge(block_options).merge(runtime_options), &block_container.block)
         end
       end
-      
+
       unless view.blocks.blocks[after_name].nil? || view.blocks.blocks == blocks
         view.blocks.blocks[after_name].each do |block_container|
           buffer << view.capture(options.merge(block_container.options).merge(block_options).merge(runtime_options), &block_container.block)
         end
       end
-      
+
       buffer
     end
+
+    def define_block_container(name, options, &block)
+      block_container = BuildingBlocks::Container.new
+      block_container.name = name
+      block_container.options = options
+      block_container.block = block
+      blocks[name.to_sym] = block_container if blocks[name.to_sym].nil? && block_given?
+      block_container
+    end
   end
 end

data/spec/building-blocks/base_spec.rb

@@ -0,0 +1,84 @@
+require "spec_helper"
+
+describe BuildingBlocks::Base do
+  before :each do
+    @builder = BuildingBlocks::Base.new({})
+  end
+
+  describe "defined? method" do
+    it "should be able to determine if a block by a specific name is already defined" do
+      @builder.defined?(:test_block).should be_false
+      @builder.define :test_block do end
+      @builder.defined?(:test_block).should be_true
+      @builder.defined?("test_block").should be_true
+    end
+  end
+
+  describe "define method" do
+    it "should be able to define a new block" do
+      block = Proc.new { |options| }
+
+      @builder.define :test_block, :option1 => "value1", :option2 => "value2", &block
+
+      test_block = @builder.blocks[:test_block]
+      test_block.options[:option1].should eql("value1")
+      test_block.options[:option2].should eql("value2")
+      test_block.name.should eql(:test_block)
+      test_block.block.should eql(block)
+    end
+    
+    it "should not replace a defined block with another attempted definition" do
+      block1 = Proc.new do |options| end
+      @builder.define :test_block, :option1 => "value1", :option2 => "value2", &block1
+
+      block2 = Proc.new do |options| end
+      @builder.define :test_block, :option3 => "value3", :option4 => "value4", &block2
+
+      test_block = @builder.blocks[:test_block]
+       test_block.options[:option1].should eql("value1")
+       test_block.options[:option2].should eql("value2")
+       test_block.options[:option3].should be_nil
+       test_block.options[:option4].should be_nil
+       test_block.name.should eql(:test_block)
+       test_block.block.should eql(block1)
+    end
+  end
+
+  describe "replace method" do
+    it "should be able to replace a defined block" do
+      block1 = Proc.new do |options| end
+      @builder.define :test_block, :option1 => "value1", :option2 => "value2", &block1
+
+      block2 = Proc.new do |options| end
+      @builder.replace :test_block, :option3 => "value3", :option4 => "value4", &block2
+
+      test_block = @builder.blocks[:test_block]
+      test_block.options[:option1].should be_nil
+      test_block.options[:option2].should be_nil
+      test_block.options[:option3].should eql("value3")
+      test_block.options[:option4].should eql("value4")
+      test_block.name.should eql(:test_block)
+      test_block.block.should eql(block2)
+    end
+  end
+
+  describe "use method" do
+    it "should be able to use a defined block by its name" do
+      @builder.expects(:render_block).with(:test_block, [], {})
+
+      block = Proc.new do |options| end
+      @builder.define :test_block, :option1 => "value1", :option2 => "value2", &block
+
+      @builder.use :test_block
+    end
+
+    it "should be able to use a defined block by its name and pass in runtime arguments" do
+      @builder.expects(:render_block).with(:test_block, ["value5"], {:option3 => "value3", :option4 => "value4"})
+
+      block = Proc.new do |options| end
+      @builder.define :test_block, :option1 => "value1", :option2 => "value2", &block
+
+      @builder.use :test_block, "value5", :option3 => "value3", :option4 => "value4"
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'building-blocks' # and any other gems you need
+
+RSpec.configure do |config|
+  config.mock_with :mocha
+  # config.mock_with :flexmock
+  # config.mock_with :rr
+  # config.mock_with :rspec
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: building-blocks
 version: !ruby/object:Gem::Version 
-  hash: 17
-  prerelease: false
+  hash: 15
+  prerelease: 
   segments: 
   - 0
   - 0
-  - 7
-  version: 0.0.7
+  - 8
+  version: 0.0.8
 platform: ruby
 authors: 
 - Andrew Hunter
@@ -15,12 +15,10 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-10-20 00:00:00 -04:00
+date: 2012-01-20 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  prerelease: false
-  type: :runtime
   name: building-blocks
   version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
@@ -31,10 +29,10 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  requirement: *id001
-- !ruby/object:Gem::Dependency 
   prerelease: false
   type: :runtime
+  requirement: *id001
+- !ruby/object:Gem::Dependency 
   name: rails
   version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
@@ -47,7 +45,23 @@ dependencies:
         - 0
         - 0
         version: 3.0.0
+  prerelease: false
+  type: :runtime
   requirement: *id002
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  prerelease: false
+  type: :development
+  requirement: *id003
 description: ""
 email: hunterae@gmail.com
 executables: []
@@ -61,10 +75,12 @@ files:
 - Rakefile
 - VERSION
 - lib/building-blocks.rb
-- lib/building_blocks/building_blocks.rb
+- lib/building_blocks/base.rb
 - lib/building_blocks/container.rb
 - lib/building_blocks/helper_methods.rb
 - rails/init.rb
+- spec/building-blocks/base_spec.rb
+- spec/spec_helper.rb
 has_rdoc: true
 homepage: http://github.com/hunterae/building-blocks
 licenses: []
@@ -95,7 +111,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.5.2
 signing_key: 
 specification_version: 3
 summary: ""