blocks 1.1.4 → 1.1.5

data/README.rdoc

@@ -2,7 +2,7 @@
 
 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) and list generator (list_for).
+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
 
@@ -21,9 +21,7 @@ Alternatively, you can install it as a plugin.
 
 == Getting Started
 
-At the very simplest level, blocks may be used in much the same way that content_for and yield are used:
-
-To define a block:
+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] %>
@@ -31,87 +29,35 @@ To define a block:
     <%= options[:some_parameter3] %>
   <% end %>
 
-Here, we are specifying 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, no error will occur if the user fails to specify "some_parameter3".
+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:
 
-Now, we may use the above block like follows:
+  <%= some_parameter if defined?(some_parameter)%>
+  <%= some_parameter2 if defined?(some_parameter2) %>
+  <%= some_parameter3 if defined?(some_parameter3) %>
 
-  <%= blocks.use :some_block_name %>
-  
-Here, we will see the output "1 2". But if we pass in "some_parameter3", as follows:
+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?". 
 
-  <%= blocks.use :some_block_name, :some_parameter3 => 3 %>
+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".
 
-Then we will see "1 2 3". Additionally, we can override any of the previous parameters when using a block simply by passing in the new value as a parameter:
+Now, we may use the above block as follows:
 
-  <%= blocks.use :some_block_name, :some_parameter2 => "overridden", :some_parameter3 => 3 %>
+  <%= blocks.use :some_block_name %>
   
-In this case, we will see "1 overridden 3". Thus, we now have content_for but with parameters.
-
-== Providing a Default Implementation of a Block
-
-We can easily provide a default implementation of a block that will be used wherever it is specified unless that block has been specified elsewhere, in which case that version of the block will be rendered in it place. A perfect example of this would be by placing a default implementation of a block inside of a layout, and optionally specifying a different implementation to be rendered inside of your view. For example, inside one of my layouts (such as "views/layouts/application.html.erb"), I may provide my default page title:
-
-  <title>
-    <%= blocks.use :title do %>
-      My default page title
-    <% end %>
-  </title>
+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]])
   
-Then, inside of a specific layout (such as "views/home/index.html.erb"), I may provide a specific page title for that particular view:
+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.define :title do %>
-    A different page title
-  <% end %>
-
-When the home index page is rendered, it's page title will be "A different page title" (assuming the HomeController uses the default application layout), but any other page that uses the default application layout will show "My default page title" as its page title. This occurs since the view is parsed first, so the definition of the block named "title" will already exist by the time the layout is rendered. However, for any page that does not specify a definition of the block "title", the default implementation provided by the layout (using the command "blocks.use") will be used. 
-
-What would happen, though, if no default implementation were provided? In other words, what if the code in the layout looked like this:
-
-  <title>
-    <%= blocks.use :title %>
-  </title>
-  
-Well, in the case where the block if defined in the view (as was the case with "views/home/index.html.erb"), a title will be provided for the page. However, for any other page, since it can't find any implementation of the named block, it will simply return nothing, and you will have a page with no title. 
-
-== Using partials
-
-It's not completely accurate to say that if no block definition is found (as was the case above), "blocks.use :title" will simply return nothing. It will first try and render a partial with that name. By default, it will look for a partial named "_title.html.erb" in the "view/blocks" directory (or "_title.html.haml" if you're using haml). It will attempt to render that partial with all the options passed in as local variables to the partial. 
-
-== Before and After Blocks
-
-Blocks provides a very convenient way to specify blocks that are to be rendered before a specific block or after a specific block. For example:
+  <%= blocks.use :some_block_name, :some_parameter3 => 3 %>
 
-  <%= blocks.define :some_block do %>
-    Some Block
-  <% end %>
-  
-  <%= blocks.before :some_block do %>
-    Before 1
-  <% end %>
-  
-  <%= blocks.prepend :some_block do %>
-    Before 2
-  <% end %>
-  
-  <%= blocks.after :some_block do %>
-    After 1
-  <% end %>
-  
-  <%= blocks.append :some_block do %>
-    After 2
-  <% end %>
-  
-Here, "blocks.before" is synonymous with "blocks.prepend" and "blocks.after" is synonymous with "blocks.append". Now, if somewhere, we called:
+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 %>
+  <%= blocks.use :some_block_name, :some_parameter2 => "overridden", :some_parameter3 => 3 %>
   
-We would see: "Before 1 Before 2 Some Block After 1 After 2". 
-
-What's particularly useful about this is that it doesn't matter if the "before" / "prepend" and "after" / "append" some before or after the "block.define" call. The only thing that matters is that the "blocks.define" occurs before the "blocks.use" call.
+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 using blocks in a very practical way. It is built entirely using the core blocks library. It is exposed as a helper method with the following prototype:
+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)
 
@@ -120,38 +66,75 @@ For example, if you have an Array of objects that respond to the following [:nam
   @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 define each column with the following:
-
-   <%= table_for @records do |table| %>
-      <%= table.column :name %>
-      <%= table.column :email %>
-      <%= table.column :phonenumber %>
-   <% end %>
+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>
+  <table id="records">
     <thead>
       <tr>
-        <th>Name</th>
-        <th>Email</th>
-        <th>Phonenumber</th>
+        <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>The Name</td>
-        <td>The Email</td>
-        <td>A phone number</td>
+        <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>The Second Name</td>
-        <td>The Second Email</td>
-        <td>A second phone number</td>
+        <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
 

data/app/views/blocks/_table.html.erb

@@ -1,13 +1,13 @@
-<%= table.define :edit do |row, options| %>
-  <%= link_to "Edit", [:edit, options[:scope], options[:record]].flatten %>
+<%= table.define :edit do |record, options| %>
+  <%= link_to "Edit", [:edit, options[:scope], record].flatten %>
 <% end %>
 
-<%= table.define :show do |row, options| %>
-  <%= link_to "Show", [options[:scope], options[:record]].flatten %>
+<%= table.define :show do |record, options| %>
+  <%= link_to "Show", [options[:scope], record].flatten %>
 <% end %>
 
-<%= table.define :delete do |row, options| %>
-  <%= link_to "Delete", [options[:scope], options[:record]].flatten, :method => "delete", :confirm => "Are you sure you want to delete this #{options[:record].class.to_s.humanize}?" %>
+<%= table.define :delete do |record, options| %>
+  <%= link_to "Delete", [options[:scope], record].flatten, :method => "delete", :confirm => "Are you sure you want to delete this #{record.class.to_s.humanize}?" %>
 <% end %>
 
 <%= table.define :thead do %>
@@ -44,20 +44,20 @@
 
 <%= table.define :rows do %>
   <% records.each do |record| %>
-    <%= table.use :row, :record => record %>
+    <%= table.use :row, record %>
   <% end %>
 <% end %>
 
-<%= table.define :row do |options| %>
+<%= table.define :row do |record, options| %>
   <%= content_tag :tr, evaluated_content_options(options[:row_html], options) do %>
-    <%= table.use :data_columns, options %>
+    <%= table.use :data_columns, record, options %>
   <% end %>
 <% end %>
 
-<%= table.define :data_columns do |options| %>
+<%= table.define :data_columns do |record, options| %>
   <% table.columns.each do |column| %>
     <%= content_tag :td, options.merge(column.options)[:column_html] do %>
-      <%= table.use column, options[:record], options.merge(:column => column) %>
+      <%= table.use column, record, options.merge(:column => column) %>
     <% end %>
   <% end %>
 <% end %>

metadata

@@ -2,7 +2,7 @@
 name: blocks
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 1.1.4
+  version: 1.1.5
 platform: ruby
 authors: 
 - Andrew Hunter
@@ -11,7 +11,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-08 00:00:00 -05:00
+date: 2011-04-15 00:00:00 -04:00
 default_executable: 
 dependencies: []