blockpile 0.2.0 → 0.3.0

data/.gitignore

@@ -0,0 +1 @@
+pkg/*

data/README.rdoc

@@ -0,0 +1,137 @@
+== Blockpile
+
+Piles of extendable rails view blocks, triggered and masked behind simple helpers
+
+== What?
+
+Sometimes within rails, view logic can become complex. As complexity begins to increase, a common theme or pattern occurs:
+
+* View logic begins to grow overly complex for what makes sense in view templates. Lengthy, confusing, and downright dirty views cause you to loose sleep.
+* Logic can be broken out of the view templates and placed into the controller.
+* Eventually, when the view logic is needed in another request, the only solution is to pull the entire logic into a helper method.
+
+So what's the problem?
+
+Rails view helpers are great for view logic, and especially for small reusable view components. Unfortunately, complex view logic is almost always a rats nest of logic and string interpolation. In fact, I'm still not sure how this has become a viable solution for rails developers, as it seems to go against what I understand to be the "rails way". To their defense, there simply isn't any other way. Until now!
+
+To better illustrate the problem, I decided to insert a snippet of a rails view helper from a popular project management tool "Redmine":
+
+  def render_project_hierarchy(projects)
+    s = ''
+    if projects.any?
+      ancestors = []
+      projects.each do |project|
+        if (ancestors.empty? || project.is_descendant_of?(ancestors.last))
+          s << "<ul class='projects #{ ancestors.empty? ? 'root' : nil}'>\n"
+        else
+          ancestors.pop
+          s << "</li>"
+          while (ancestors.any? && !project.is_descendant_of?(ancestors.last)) 
+            ancestors.pop
+            s << "</ul></li>\n"
+          end
+        end
+        classes = (ancestors.empty? ? 'root' : 'child')
+        s << "<li class='#{classes}'><div class='#{classes}'>" +
+               link_to(h(project), {:controller => 'projects', :action => 'show', :id => project}, :class => "project #{User.current.member_of?(project) ? 'my-project' : nil}")
+        s << "<div class='wiki description'>#{textilizable(project.short_description, :project => project)}</div>" unless project.description.blank?
+        s << "</div>\n"
+        ancestors << project
+      end
+      s << ("</li></ul>\n" * ancestors.size)
+    end
+    s
+  end
+
+So even if you are talented enough to understand what this code is doing, let me ask 2 questions:
+
+* Do you mind if we upgrade the markup language to fit a new design?
+* Even though this is an acceptable solution, does it really feel good to have this nest under your hood?
+
+Before we move on, let me add that I'm not trashing the Redmine code-base. In fact, I chose an example from this project simply because the author is fantastic and this example mirrors at least one helper method in every rails app.
+
+== Enter Blockpile
+
+A blockpile solves this particular problem by slicing the view layer into 2 finer layers: logic, and template. It is no different than a controller/template relationship, except that a blockpile can be easily distributed across the application just as a helper method can.
+
+From a high level, a blockpile consists of 3 components:
+
+* A Ruby Class file
+* A template file (erb only for now, others coming soon)
+* A function call to include the blockpile in your existing templates
+
+== Example
+
+To keep this example simple, I'll show you one way to clean up the example above. Since I'm lazy, I'm not actually going to fix the example above but show the concept which could be filled in later.
+
+=== Ruby Class file
+	# app/helpers/blockpiles/project_hierarchy.erb
+
+	class ProjectHierarchy < Blockpile::Base
+
+	  def build(options={})
+		# use this instead of initialize
+		@projects = options[:project]
+		prepare_hierarchy
+	  end
+
+	  def prepare_hierarchy
+	    # fill in hierarchy here
+	  end
+
+	  def projects
+		# fill in code
+	  end
+
+	  def project_children(project)
+	    # could return project children
+	  end
+
+	end
+
+Here we can take care of all logic, in preparation for the view. We need not interpolate, as the template file will pull data from this class instance when needed. Here we can focus on the beauty and elegance of Ruby, and not on the mixture of presentation.
+
+=== A template file
+
+	# app/views/blockpiles/project_hierarchy.html.erb
+	
+	
+	<ul>
+		<% projects.each do |project| %>
+		
+			<li><%= project.name %></li>
+			
+			<% project_children(project).each do |child| %>
+				<li class="child"><%= child.name %></li>
+			<% end %>
+		
+		<% end %>
+	</ul>
+	
+The purpose of the template file is to "pull" logic from the Blockpile Class. We are assuming all logic will be taken care of in the class, and here we can simply focus on our view presentation, using only conditional logic (if else etc).
+
+=== helper-like function call
+
+	# app/views/{controller}/{action}.html.erb
+	
+	<%= project_hierarchy :project => @project %>
+
+There is no boiler plate for turning your Blockpile Class into a helper method, it happens under the hood. Notice we are passing @project, that will be available in your class through the options hash in the build function. The input of the builder method is completely up to you. In this example I chose to use an "options" hash. You could replace that with 3 input arguments instead if you prefer, in which case you would simply pass @project instead of assigning to a hash key.
+
+=== Summary
+	
+In essence, what could be a horrible nest of string interpolation and logic, can become a clean isolation of logic and markup language. I realize this sample solution is lacking, but I'll leave the actual logic to the developer. 
+
+=== Generator
+
+You can quickly create a Blockpile Class and Template pair by using the generator:
+
+	rails generate blockpile project_hierarchy
+	
+And thats it! You now have a Blockpile ready for use, with a helper method called "project_hierarchy".
+
+== Customize your piles
+
+Coming soon.
+
+Copyright (c) 2010 Tyler Flint, released under the MIT license

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/blockpile.gemspec

@@ -5,24 +5,26 @@
 
 Gem::Specification.new do |s|
   s.name = %q{blockpile}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tyler Flint"]
-  s.date = %q{2010-08-08}
+  s.date = %q{2010-08-16}
   s.description = %q{This module attempts to create structured view helpers. Essentially, a blockpile consists of a ruby class file, and a template. This allows for isolated blocks of view logic, that can maintain a clean separation of markup language from ruby code. Blocks can be inherited from to DRY up view logic.}
   s.email = %q{tylerflint@gmail.com}
   s.extra_rdoc_files = [
-    "README"
+    "README.rdoc"
   ]
   s.files = [
-    "MIT-LICENSE",
-     "README",
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.rdoc",
      "Rakefile",
      "VERSION",
      "blockpile.gemspec",
      "lib/blockpile.rb",
      "lib/blockpile/base.rb",
+     "lib/blockpile/paths.rb",
      "lib/blockpile/setup.rb",
      "lib/generators/blockpile/USAGE",
      "lib/generators/blockpile/blockpile_generator.rb",

data/lib/blockpile/base.rb

@@ -9,7 +9,7 @@ class Blockpile::Base
   end
   
   def to_html
-    render_template @template
+    render_template
   end
   
   def build
@@ -19,9 +19,21 @@ class Blockpile::Base
 protected
   
   # Assumes /views/helper/ as base
-  def render_template(template)
-    @path ||= '/app/views/blockpiles/'
-    ERB.new( File.read(Rails.root.to_s + @path + template + ".html.erb") ).result binding
+  def render_template
+    ERB.new( File.read( get_template ) ).result binding
+  end
+  
+  def get_template
+    get_paths.each do |path|
+      if File::exists?( path + "/" + @template + ".html.erb")
+        return path +  "/" + @template + ".html.erb"
+      end
+    end
+    raise "Unable to find template for this blockpile"
+  end
+  
+  def get_paths
+    Blockpile::Paths.get_paths
   end
   
   def method_missing(*args, &block)

data/lib/blockpile/paths.rb

@@ -0,0 +1,15 @@
+module Blockpile
+  module Paths
+    
+    @@paths = []
+    
+    def self.add_template_path(path)
+      @@paths << path
+    end
+    
+    def self.get_paths
+      @@paths
+    end
+    
+  end
+end

data/lib/blockpile/setup.rb

@@ -1,15 +1,15 @@
 module Blockpile
   module Setup
     def self.add_load_path(path)
-      ActiveSupport::Dependencies.autoload_paths << path
-      Dir.glob(path + "*.rb") do |file|
+      Dir.glob(path + "/**/*.rb") do |file|
+        ActiveSupport::Dependencies.autoload_paths << File.dirname(file)
         file_name   = file.split(/\//).pop.gsub(/.rb/, '')
-        class_name  = file_name.classify 
+        class_name  = file_name.classify
         ActionView::Base.class_eval %{
           def #{file_name}(*args, &block)
-              block = #{class_name}.new(self, session, params, '#{file_name}', *args)
-              yield block
-              raw block.to_html
+              blockpile = #{class_name}.new(self, session, params, '#{file_name}', *args)
+              yield blockpile if block_given?
+              raw blockpile.to_html
           end
         }
       end

data/lib/blockpile.rb

@@ -1,17 +1,20 @@
 require 'rails'
 require 'blockpile/setup'
 require 'blockpile/base'
+require 'blockpile/paths'
 
 module Blockpile
   class Railtie < Rails::Railtie
     initializer "blockpile.setup default directories" do
       Blockpile.setup do |config|
-        config.add_load_path Rails.root.to_s + '/app/helpers/blockpiles/'
+        config.add_load_path Rails.root.to_s + '/app/helpers/blockpiles'
       end
+      Blockpile::Paths.add_template_path Rails.root.to_s + '/app/views/blockpiles/'
     end
   end
   
   def self.setup
     yield Blockpile::Setup
   end
+  
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Tyler Flint
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-08 00:00:00 -06:00
+date: 2010-08-16 00:00:00 -06:00
 default_executable: 
 dependencies: []
 
@@ -25,15 +25,17 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README
+- README.rdoc
 files: 
+- .gitignore
 - MIT-LICENSE
-- README
+- README.rdoc
 - Rakefile
 - VERSION
 - blockpile.gemspec
 - lib/blockpile.rb
 - lib/blockpile/base.rb
+- lib/blockpile/paths.rb
 - lib/blockpile/setup.rb
 - lib/generators/blockpile/USAGE
 - lib/generators/blockpile/blockpile_generator.rb

data/README

@@ -1,13 +0,0 @@
-Blockpile
-=========
-
-Introduction goes here.
-
-
-Example
-=======
-
-Example goes here.
-
-
-Copyright (c) 2010 [name of plugin creator], released under the MIT license