deas-erubis 0.3.0 → 0.4.0

data/README.md

@@ -4,7 +4,113 @@
 
 ## Usage
 
-TODO: Write code samples and usage instructions here
+Register the engine:
+
+```ruby
+require 'deas'
+require 'deas-erubis'
+
+Deas.configure do |c|
+
+  c.template_source "/path/to/templates" do |s|
+    s.engine 'erb', Deas::Erubis::TemplateEngine
+  end
+
+end
+```
+
+Add `.erb` to any template files in your template source path.  Deas will evaluate their content using Erubis when they are rendered.
+
+### Partials
+
+Deas::Erubis provides template helpers for rendering partial templates.
+
+```erb
+# in /path/to/templates/list.html.erb
+<h1><%= list.title %></h1>
+<ul>
+  <% list.items.each do |item| %>
+    <%= partial '_list_item.html', :item => item %>
+  <% end %>
+</ul>
+
+# in /path/to/templates/_list_item.html.erb
+<li><%= item.name %></li>
+
+# output
+<h1>My List</h1>
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+  <li>Item 3</li>
+</ul>
+```
+
+There are also helpers for rendering partials that yield to given content blocks (called "capture partials")
+
+```erb
+# in /path/to/templates/list.html.erb
+<h1><%= list.title %></h1>
+<ul>
+  <% list.items.each do |item| %>
+    <% capture_partial '_list_item.html' do %>
+      <span><%= item.name %></span>
+    <% end %>
+  <% end %>
+</ul>
+
+# in /path/to/templates/_list_item.html.erb
+<li><%= yield %></li>
+
+# output
+# output
+<h1>My List</h1>
+<ul>
+  <li>
+    <span>Item 1</span>
+  </li>
+  <li>
+    <span>Item 2</span>
+  </li>
+  <li>
+    <span>Item 3</span>
+  </li>
+</ul>
+```
+
+### Notes
+
+The engine doesn't allow overriding the template scope but instead allows you to pass in data that binds to the template scope as local methods.  By default, the view handler will be bound to the scope via the `view` method in templates.  If you want to change this, provide a `'handler_local'` option when registering:
+
+```ruby
+c.template_source "/path/to/templates" do |s|
+  s.engine 'erb', Deas::Erubis::TemplateEngine, 'handler_local' => 'view_handler'
+end
+```
+
+By default, `::Erubis::Eruby` is used to evaluate the templates.  However, Erubis provides "enhancers" that add certain features.  You can pass in any custom eruby class (with any enhancers you like) useing the `'eruby'` option when registering:
+
+```ruby
+  c.template_source "/path/to/templates" do |s|
+    s.engine 'erb', Deas::Erubis::TemplateEngine, 'eruby' => MyEnhancedEruby
+  end
+```
+
+The engine doesn't cache templates by default - it opens the file from disk on each render.  To enable caching (which stores the file contents in memory on first use), pass a `'cache'` option when registering:
+
+```ruby
+  c.template_source "/path/to/templates" do |s|
+    s.engine 'erb', Deas::Erubis::TemplateEngine, 'cache' => true
+  end
+```
+
+If you wish to provide custom template helpers, organize them in module(s) and pass them with the `'helpers'` option when registering:
+
+```ruby
+  c.template_source "/path/to/templates" do |s|
+    s.engine 'erb', Deas::Erubis::TemplateEngine, 'helpers' => [MyAwesomeHelpers, NotSoAwesomeHelpers]
+  end
+```
 
 ## Installation
 

data/deas-erubis.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |gem|
 
   gem.add_development_dependency("assert", ["~> 2.12"])
 
-  gem.add_dependency("deas", ["~> 0.29"])
+  gem.add_dependency("deas", ["~> 0.30"])
   gem.add_dependency("erubis")
 
 end

data/lib/deas-erubis.rb

@@ -15,8 +15,9 @@ module Deas::Erubis
       @erb_source ||= Source.new(self.source_path, {
         :eruby          => self.opts['eruby'],
         :cache          => self.opts['cache'],
-        :deas_source    => self.opts['deas_template_source'],
-        :default_locals => { self.erb_logger_local => self.logger }
+        :default_source => self.opts['default_template_source'],
+        :helpers        => self.opts['helpers'],
+        :locals         => { self.erb_logger_local => self.logger }
       })
     end
 

data/lib/deas-erubis/source.rb

@@ -19,22 +19,22 @@ module Deas::Erubis
       @cache         = opts[:cache] ? Hash.new : NullCache.new
       @context_class = build_context_class(opts)
 
-      @deas_source = opts[:deas_source]
+      @default_source = opts[:default_source]
     end
 
     def render(file_name, locals, &content)
-      load(file_name).evaluate(@context_class.new(@deas_source, locals), &content)
+      load(file_name).evaluate(@context_class.new(@default_source, locals), &content)
     end
 
     def compile(filename, content)
-      eruby(filename, content).evaluate(@context_class.new(@deas_source, {}))
+      template(filename, content).evaluate(@context_class.new(@default_source, {}))
     end
 
-    def eruby(filename, content)
-      @eruby_class.new(content, {
+    def template(filename, content)
+      Template.new(@eruby_class.new(content, {
         :bufvar   => BUFVAR_NAME,
         :filename => filename
-      })
+      }))
     end
 
     def inspect
@@ -49,7 +49,7 @@ module Deas::Erubis
       @cache[file_name] ||= begin
         filename = source_file_path(file_name).to_s
         content = File.send(File.respond_to?(:binread) ? :binread : :read, filename)
-        eruby(filename, content)
+        template(filename, content)
       end
     end
 
@@ -60,11 +60,11 @@ module Deas::Erubis
     def build_context_class(opts)
       Class.new do
         include ::Deas::Erubis::TemplateHelpers
-        # TODO: mixin context helpers? `opts[:template_helpers]`
-        (opts[:default_locals] || {}).each{ |k, v| define_method(k){ v } }
+        [*(opts[:helpers] || [])].each{ |helper| include helper }
+        (opts[:locals]  || {}).each{ |k, v| define_method(k){ v } }
 
-        def initialize(deas_source, locals)
-          @deas_source = deas_source
+        def initialize(default_source, locals)
+          @default_source = default_source
 
           metaclass = class << self; self; end
           metaclass.class_eval do
@@ -76,6 +76,21 @@ module Deas::Erubis
       end
     end
 
+    class Template
+      attr_reader :src, :filename, :eruby_class, :eruby_bufvar
+
+      def initialize(erubis_eruby)
+        @src          = erubis_eruby.src
+        @filename     = erubis_eruby.filename
+        @eruby_class  = erubis_eruby.class
+        @eruby_bufvar = erubis_eruby.instance_variable_get('@bufvar')
+      end
+
+      def evaluate(context)
+        context.instance_eval(@src, @filename)
+      end
+    end
+
     class NullCache
       def [](file_name);         end
       def []=(file_name, value); end

data/lib/deas-erubis/template_helpers.rb

@@ -11,12 +11,20 @@ module Deas::Erubis
 
     module Methods
 
-      def partial(n, l = nil)
-        @deas_source.partial(n, l || {})
+      def partial(name, locals = nil)
+        source_partial(@default_source, name, locals)
       end
 
-      def capture_partial(n, l = nil, &c)
-        _erb_buffer @deas_source.partial(n, l || {}, &Proc.new{ _erb_capture(&c) })
+      def capture_partial(name, locals = nil, &c)
+        source_capture_partial(@default_source, name, locals, &c)
+      end
+
+      def source_partial(source, name, locals = nil)
+        source.partial(name, locals || {})
+      end
+
+      def source_capture_partial(source, name, locals = nil, &c)
+        _erb_buffer source.partial(name, locals || {}, &Proc.new{ _erb_capture(&c) })
       end
 
       private

data/lib/deas-erubis/version.rb

@@ -1,4 +1,4 @@
 module Deas; end
 module Deas::Erubis
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/test/support/factory.rb

@@ -59,6 +59,7 @@ module Factory
     "  <h1>local1: #{locals['local1']}</h1>\n"\
     "<p>logger: #{engine.logger.to_s}</p>\n\n"\
     "  <span>No locals!</span>\n\n"\
+    "  <span>No locals!</span>\n\n"\
     "</div>\n"
   end
 
@@ -74,6 +75,7 @@ module Factory
     "<h1>local1: #{locals['local1']}</h1>\n"\
     "<p>logger: #{engine.logger.to_s}</p>\n"\
     "<span>No locals!</span>\n"\
+    "<span>No locals!</span>\n"\
     "</div>\n"
   end
 

data/test/support/templates/with_capture_partial.erb

@@ -4,4 +4,5 @@
   <% end %>
   <% capture_partial '_partial', 'local1' => local1 %>
   <% capture_partial '_partial_no_locals' %>
+  <% source_capture_partial @default_source, '_partial_no_locals' %>
 </div>

data/test/support/templates/with_partial.erb

@@ -1,4 +1,5 @@
 <div>
   <%= partial '_partial', 'local1' => local1 %>
   <%= partial '_partial_no_locals' %>
+  <%= source_partial @default_source, '_partial_no_locals' %>
 </div>

data/test/system/template_engine_tests.rb

@@ -53,10 +53,10 @@ class Deas::Erubis::TemplateEngine
   class TemplateHelperTests < SystemTests
     desc "template helpers"
     setup do
-      @deas_source = Deas::TemplateSource.new(TEMPLATE_ROOT).tap do |s|
+      @source = Deas::TemplateSource.new(TEMPLATE_ROOT).tap do |s|
         s.engine 'erb', Deas::Erubis::TemplateEngine
       end
-      @engine = @deas_source.engines['erb']
+      @engine = @source.engines['erb']
     end
 
     should "render partials" do

data/test/unit/source_tests.rb

@@ -35,7 +35,7 @@ class Deas::Erubis::Source
     subject{ @source }
 
     should have_readers :root, :eruby_class, :cache, :context_class
-    should have_imeths :render, :compile, :eruby
+    should have_imeths :render, :compile, :template
 
     should "know its root" do
       assert_equal @root, subject.root.to_s
@@ -51,15 +51,13 @@ class Deas::Erubis::Source
       assert_equal eruby, source.eruby_class
     end
 
-    should "build eruby instances for a given template file" do
-      assert_kind_of subject.eruby_class, subject.eruby('basic', Factory.string)
-    end
-
-    should "build its eruby instances with the correct bufvar name" do
-      eruby = subject.eruby('basic', Factory.string)
+    should "build template objects for template files" do
+      filename = 'basic'
+      template = subject.template(filename, Factory.string)
 
-      exp = Deas::Erubis::Source::BUFVAR_NAME
-      assert_equal exp, eruby.instance_variable_get('@bufvar')
+      assert_equal filename,                          template.filename
+      assert_equal subject.eruby_class,               template.eruby_class
+      assert_equal Deas::Erubis::Source::BUFVAR_NAME, template.eruby_bufvar
     end
 
     should "not cache templates by default" do
@@ -81,12 +79,25 @@ class Deas::Erubis::Source
       context = subject.context_class.new('deas-source', {})
       assert_responds_to :partial, context
       assert_responds_to :capture_partial, context
+      assert_responds_to :source_partial, context
+      assert_responds_to :source_capture_partial, context
+    end
+
+    should "mixin custom template helpers to its context class" do
+      source = @source_class.new(@root, :helpers => SomeCustomHelpers)
+      assert_includes SomeCustomHelpers, source.context_class
+
+      source = @source_class.new(@root, :helpers => [SomeCustomHelpers])
+      assert_includes SomeCustomHelpers, source.context_class
+
+      context = source.context_class.new('deas-source', {})
+      assert_responds_to :a_custom_method, context
     end
 
     should "optionally take and apply default locals to its context class" do
       local_name, local_val = [Factory.string, Factory.string]
       source = @source_class.new(@root, {
-        :default_locals => { local_name => local_val }
+        :locals => { local_name => local_val }
       })
       context = source.context_class.new('deas-source', {})
 
@@ -102,11 +113,11 @@ class Deas::Erubis::Source
       assert_equal local_val, context.send(local_name)
     end
 
-    should "set any deas source given to its context class as an ivar on init" do
-      deas_source = 'a-deas-source'
-      context = subject.context_class.new(deas_source, {})
+    should "set any default source given to its context class as an ivar on init" do
+      default_source = 'a-default-source'
+      context = subject.context_class.new(default_source, {})
 
-      assert_equal deas_source, context.instance_variable_get('@deas_source')
+      assert_equal default_source, context.instance_variable_get('@default_source')
     end
 
   end
@@ -126,16 +137,16 @@ class Deas::Erubis::Source
       assert_equal exp, subject.render(@file_name, @file_locals)
     end
 
-    should "pass its deas source to its context class" do
-      deas_source = 'a-deas-source'
-      source = @source_class.new(@root, :deas_source => deas_source)
+    should "pass its default source to its context class" do
+      default_source = 'a-deas-source'
+      source = @source_class.new(@root, :default_source => default_source)
       context_class = nil
       Assert.stub(source.context_class, :new) do |s, l|
         context_class = ContextClassSpy.new(s, l)
       end
       source.render(@file_name, @file_locals)
 
-      assert_equal deas_source, context_class.deas_source
+      assert_equal default_source, context_class.default_source
     end
 
   end
@@ -146,12 +157,12 @@ class Deas::Erubis::Source
       @source = @source_class.new(@root, :cache => true)
     end
 
-    should "cache template eruby instances by their file name" do
+    should "cache templates by their file name" do
       exp = Factory.basic_erb_rendered(@file_locals)
       assert_equal exp, @source.render(@file_name, @file_locals)
 
       assert_equal [@file_name], @source.cache.keys
-      assert_kind_of @source.eruby_class, @source.cache[@file_name]
+      assert_kind_of Template, @source.cache[@file_name]
     end
 
   end
@@ -162,7 +173,7 @@ class Deas::Erubis::Source
       @source = @source_class.new(@root, :cache => false)
     end
 
-    should "not cache template eruby instances" do
+    should "not cache templates" do
       exp = Factory.basic_erb_rendered(@file_locals)
       assert_equal exp, @source.render(@file_name, @file_locals)
 
@@ -239,9 +250,9 @@ class Deas::Erubis::Source
   end
 
   class ContextClassSpy
-    attr_reader :deas_source
-    def initialize(deas_source, locals)
-      @deas_source = deas_source
+    attr_reader :default_source
+    def initialize(default_source, locals)
+      @default_source = default_source
       metaclass = class << self; self; end
       metaclass.class_eval do
         locals.each do |key, value|
@@ -251,4 +262,8 @@ class Deas::Erubis::Source
     end
   end
 
+  module SomeCustomHelpers
+    def a_custom_method; end
+  end
+
 end

data/test/unit/template_engine_tests.rb

@@ -40,13 +40,18 @@ class Deas::Erubis::TemplateEngine
     end
 
     should "pass any given deas template source to its source" do
-      deas_source = 'a-deas-source'
+      default_source = 'a-default-source'
       source_opts = nil
 
       Assert.stub(Deas::Erubis::Source, :new){ |root, opts| source_opts = opts }
-      Deas::Erubis::TemplateEngine.new('deas_template_source' => deas_source).erb_source
+      Deas::Erubis::TemplateEngine.new('default_template_source' => default_source).erb_source
 
-      assert_equal deas_source, source_opts[:deas_source]
+      assert_equal default_source, source_opts[:default_source]
+    end
+
+    should "pass any given helpers option to its source" do
+      engine = Deas::Erubis::TemplateEngine.new('helpers' => [SomeCustomHelpers])
+      assert_includes SomeCustomHelpers, engine.erb_source.context_class
     end
 
     should "use 'view' as the handler local name by default" do
@@ -71,4 +76,8 @@ class Deas::Erubis::TemplateEngine
 
   end
 
+  module SomeCustomHelpers
+    def a_custom_method; end
+  end
+
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: deas-erubis
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 15
   prerelease: 
   segments: 
   - 0
-  - 3
+  - 4
   - 0
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Kelly Redding
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2015-01-14 00:00:00 Z
+date: 2015-02-04 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   requirement: &id001 !ruby/object:Gem::Requirement 
@@ -39,11 +39,11 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 49
+        hash: 55
         segments: 
         - 0
-        - 29
-        version: "0.29"
+        - 30
+        version: "0.30"
   type: :runtime
   name: deas
   version_requirements: *id002