hamlbars 1.1.0 → 2.0.0

data/README.md

@@ -12,80 +12,48 @@ you to easily generate [Handlebars](http://handlebarsjs.com) templates using
 Add the following line to your Gemfile (on Rails, inside the `:assets` group):
 
 ```ruby
-gem 'hamlbars', '~> 1.1'
+gem 'hamlbars', '~> 2.0'
 ```
 
-If you are stuck with an older, yanked version like 2012.3.21 and it won't
-update to 1.1, be sure to add `'~> 1.1'` as the version spec and run `bundle
-install`.
+# DEPRECATION WARNING
 
-# Demo Site
-
-If you're unsure how all the pieces fit together then take a quick look at the
-[demo site](http://hamlbars-demo.herokuapp.com/).
-
-# Attribute bindings
-
-You can easily add attribute bindings by adding a `:bind` hash to the tag
-attributes, like so:
-
-```haml
-%div{ :class => 'widget', :bind => { :title => 'App.widgetController.title' }
-```
+As of version 2.0 Hamlbars simply outputs raw Handlebars templates, and you will need to 
+use the precompiler of your choice to compile the assets for your usage.
 
-Which will generate the following output:
+If you're using [Ember.js](http://emberjs.com) then you will need the 
+[ember-rails](http://rubygems.org/gems/ember-rails) gem. If you're just using
+Handlebars templates on their own then you need to use 
+[handlebars_assets](http://rubygems.org/gems/handlebars_assets) to precompile
+for your framework.
 
-```handlebars
-<div class="widget" {{bindAttr title="App.widgetController.title"}}></div>
-```
+Be sure to take a look at Hamlbars' sister project 
+[FlavourSaver](http://rubygems.org/gems/flavour_saver) for pure-ruby server-side
+rendering of Handlebars templates.
 
-# Action handlers
+# Chaining compilation using the Rails asset pipeline
 
-To use Ember's `{{action}}` helper, set the `:_action` attribute, like so:
+When using the `handlebars_assets` or `ember-rails` gems you need to add an 
+extra file extension so that the asset pipeline knows to take the output of
+Hamlbars and send it into the template compiler of your choice.  Luckily
+both gems register the `hbs` extension, so you can enable asset compilation
+by setting `.js.hbs.hamlbars` as the file extension for your templates.
 
-```haml
-%a{ :_action => 'toggle' } Toggle
-%a{ :_action => 'edit article on="doubleClick"' } Edit
-```
-
-This will generate:
-
-```html
-<a {{action toggle}}>Toggle</a>
-<a {{action edit article on="doubleClick"}}>Edit</a>
-```
-
-Note that `:_action` has a leading underscore, to distinguish it from regular
-HTML attributes (`<form action="...">`).
-
-# Event bindings (old syntax)
-
-You can also add one or more event actions by adding an event hash or array of
-event hashes to the tag options. This syntax is being deprecated in favor of
-the newer `:_action` syntax described above.
-
-```haml
-%a{ :event => { :on => 'click', :action => 'clicked' } } Click
-```
-
-or
+# Demo Site
 
-```haml
-%div{ :events => [ { :on => 'mouseover', :action => 'highlightView' }, { :on => 'mouseout', :action => 'disableViewHighlight' } ] }
-```
+If you're unsure how all the pieces fit together then take a quick look at the
+[demo site](http://hamlbars-demo.herokuapp.com/).
 
-Note that the default event is `click`, so it's not necessary to specify it:
+# Handlebars extensions to Haml.
 
-```haml
-%a{ :event => { :action => 'clicked' } } Click
-```
+Hamlbars adds a couple of extensions to Haml in order to allow you to create
+handlebars expressions in your templates.
 
-# Handlebars helper
+## Handlebars helper
 
 You can use the `handlebars` helper (or just `hb` for short) to generate both
 Handlebars blocks and expressions.
 
-## Expressions
+### Expressions
 
 Generating Handlebars expressions is as simple as using the `handlebars` helper
 and providing the expression as a string argument:
@@ -100,7 +68,7 @@ which will will generate:
 {{App.widgetController.title}}
 ```
 
-## Blocks
+### Blocks
 
 Whereas passing a block to the `handlebars` helper will create a Handlebars
 block expression:
@@ -124,7 +92,7 @@ will result in the following markup:
 </ul>
 ```
 
-## Options
+### Options
 
 The `hb` helper can take an optional hash of options which will be rendered
 inside the expression:
@@ -139,68 +107,78 @@ will result in:
 {{view App.InfoView tagName="span"}}
 ```
 
-## Tripple-stash
+### Tripple-stash
 
 You can use the `handlebars!` or `hb!` variant of the `handlebars` helper to
 output "tripple-stash" expressions within which Handlebars does not escape the
 output.
 
-# Configuring template output:
+### In-tag expressions
 
-`hamlbars` has three configuration options, which pertain to the generated
-JavaScript:
+Unfortunately, (or fortunately) due to the nature of Haml, we can't put Handlebars
+expressions in a tag definition, eg:
 
-```ruby
-Hamlbars::Template.template_destination    # default 'Handlebars.templates'
-Hamlbars::Template.template_compiler       # default 'Handlebars.compile'
-Hamlbars::Template.template_partial_method # default 'Handlebars.registerPartial'
+```handlebars
+<{{tagName}}>
+  My content
+</{{tagName}}>
 ```
 
-These settings will work find by default if you are using Handlebars as a
-standalone JavaScript library, however if you are using something that embeds
-Handlebars within it then you'll have to change these.
-
-If you're using [Ember.js](http://www.emberjs.com) then you can use:
+But we can allow you to put Handlebars expressions in to generate tag arguments by
+adding a special `hb` attribute to your tags. For example:
 
-```ruby
-Hamlbars::Template.render_templates_for :ember
+```haml
+%div{:hb => 'idHelper'}
 ```
 
-Which is effectively the same as:
+Which would render the following:
 
-```ruby
-Hamlbars::Template.template_destination = 'Ember.TEMPLATES'
-Hamlbars::Template.template_compiler = 'Ember.Handlebars.compile'
-Hamlbars::Template.template_partial_method = 'Ember.Handlebars.registerPartial'
+```handlebars
+<div {{idHelper}}></div>
 ```
 
-The good news is that if you're using the
-[emberjs-rails](http://www.rubygems.org/gems/emberjs-rails) gem then it will
-automatically detect hamlbars and change it for you. Magic!
+If you need to place more than one expression inside your tag then you can pass an array
+of expressions.
 
-If you're using [ember-rails](http://rubygems.org/gems/ember-rails) then you'll
-need to put this in a initializer.
+## Ember.js specific extensions
 
-# Configuring JavaScript output:
+A large portion of the audience for Hamlbars is using it to generate templates for sites
+using the Ember.js javascript framework.  We have added some special extra syntax to
+cater for Ember's common idioms.
 
-Hamlbars has experimental support for template precompilation using
-[ExecJS](http://rubygems.org/gems/execjs). To enable it, call
+### Attribute bindings
 
-```ruby
-Hamlbars::Template.enable_precompiler!
+You can easily add attribute bindings by adding a `:bind` hash to the tag
+attributes, like so:
+
+```haml
+%div{ :class => 'widget', :bind => { :title => 'App.widgetController.title' }
 ```
 
-You can also disable enclosification (which is enabled by default) using:
+Which will generate the following output:
 
-```ruby
-Hamlbars::Template.disable_closures!
+```handlebars
+<div class="widget" {{bindAttr title="App.widgetController.title"}}></div>
 ```
 
-# Asset pipeline
+### Action handlers
+
+To use Ember's `{{action}}` helper, set the `:_action` attribute, like so:
+
+```haml
+%a{ :_action => 'toggle' } Toggle
+%a{ :_action => 'edit article on="doubleClick"' } Edit
+```
 
-Hamlbars is specifically designed for use with Rails 3.1's asset pipeline.
-Simply create templates ending in `.js.hamlbars` and Sprockets will know what
-to do.
+This will generate:
+
+```html
+<a {{action toggle}}>Toggle</a>
+<a {{action edit article on="doubleClick"}}>Edit</a>
+```
+
+Note that `:_action` has a leading underscore, to distinguish it from regular
+HTML attributes (`<form action="...">`).
 
 # Rails helpers
 
@@ -209,6 +187,8 @@ Probably the best way to do this is to create an initializer.  This is
 dangerous and possibly stupid as a large number of Rails' helpers require
 access to the request object, which is not present when compiling assets.
 
+That said, it can be pretty handy to have access to the route helpers.
+
 **Use at your own risk. You have been warned.**
 
 # License and Copyright.

data/lib/hamlbars/ext/compiler.rb

@@ -36,14 +36,10 @@ module Hamlbars
               handlebars_rendered_attributes << Hamlbars::Ext::Compiler.handlebars_attributes('bindAttr', bind)
             end
 
-            events = attributes.delete('events') || []
-            if event = attributes.delete('event')
-              events << event
-            end
-            events.each do |event|
-              event[:on] = event.delete('on') || event.delete(:on) || 'click'
-              action = event.delete('action') || event.delete(:action)
-              handlebars_rendered_attributes << Hamlbars::Ext::Compiler.handlebars_attributes("action \"#{action}\"", event)
+            if hb = attributes.delete('hb')
+              (hb.respond_to?(:each) ? hb : [hb]).each do |expression|
+                handlebars_rendered_attributes << " {{#{expression}}}"
+              end
             end
 
             # This could be generalized into /_.*/ catch-all syntax, if

data/lib/hamlbars/ext.rb

@@ -1,8 +1,6 @@
 module Hamlbars
   module Ext
-    autoload :Compiler,    File.expand_path('../ext/compiler.rb', __FILE__)
-    autoload :Precompiler, File.expand_path('../ext/precompiler.rb', __FILE__)
-    autoload :Closure,     File.expand_path('../ext/closure.rb', __FILE__)
+    autoload :Compiler, File.expand_path('../ext/compiler.rb', __FILE__)
     autoload :RailsHelper, File.expand_path('../ext/rails_helper.rb', __FILE__)
   end
 end

data/lib/hamlbars/template.rb

@@ -2,74 +2,11 @@ require 'tilt/template'
 
 module Hamlbars
   class Template < Tilt::Template
-    include Ext::Closure
-    enable_closures! # Enable closures by default.
-    include Ext::Precompiler
     if defined? Rails
       include Ext::RailsHelper
-      enable_precompiler! if Rails.env.production?
     end
 
-    JS_ESCAPE_MAP = {
-      "\r\n"  => '\n',
-      "\n"    => '\n',
-      "\r"    => '\n',
-      '"'     => '\\"',
-      "'"     => "\\'"
-    }
-
-    # Used to change the asset path into a string which is
-    # safe to use as a JavaScript object property.
-    def self.path_translator(path)
-      path.downcase.gsub(/[^a-z0-9\/]/, '_')
-    end
-
-    # Handy helper to preconfigure Hamlbars to render for
-    # either :handlebars (default) or :ember.
-    def self.render_templates_for(whom=:handlebars)
-      if whom == :handlebars
-        self.template_destination = 'Handlebars.templates'
-        self.template_compiler = 'Handlebars.compile'
-        self.template_partial_method = 'Handlebars.registerPartial'
-      elsif whom == :ember
-        self.template_destination = 'Ember.TEMPLATES'
-        self.template_compiler = 'Ember.Handlebars.compile'
-        self.template_partial_method = 'Ember.Handlebars.registerPartial'
-      end
-    end
-
-    # The target object where the rendered template will
-    # be stored on the client side.
-    # Defaults to 'Handlebars.templates'
-    def self.template_destination
-      @template_destination ||= 'Handlebars.templates'
-    end
-
-    def self.template_destination=(x)
-      @template_destination = x
-    end
-
-    # The JavaScript function used to compile the HTML
-    # string into a usable Handlebars template.
-    def self.template_compiler
-      @template_compiler ||= 'Handlebars.compile'
-    end
-
-    def self.template_compiler=(x)
-      @template_compiler = x
-    end
-
-    # The JavaScript function used on the compile side to 
-    # register the template as a partial on the client side.
-    def self.template_partial_method
-      @template_partial_method ||= 'Handlebars.registerPartial'
-    end
-
-    def self.template_partial_method=(x)
-      @template_partial_method = x
-    end
-
-    self.default_mime_type = 'application/javascript'
+    self.default_mime_type = 'text/x-handlebars'
 
     def self.engine_initialized?
       defined? ::Haml::Engine
@@ -87,41 +24,15 @@ module Hamlbars
     # Uses Haml to render the template into an HTML string, then 
     # wraps it in the neccessary JavaScript to serve to the client.
     def evaluate(scope, locals, &block)
-      template = if @engine.respond_to?(:precompiled_method_return_value, true)
-                   super(scope, locals, &block)
-                 else
-                   @engine.render(scope, locals, &block)
-                 end
-
-      if scope.respond_to? :logical_path
-        path = scope.logical_path
-      else
-        path = basename
-      end
-
-      if basename =~ /^_/
-        name = partial_path_translator(path)
-        "#{self.class.template_partial_method}('#{name}', '#{template.strip.gsub(/(\r\n|[\n\r"'])/) { JS_ESCAPE_MAP[$1] }}');\n"
+      if @engine.respond_to?(:precompiled_method_return_value, true)
+        super(scope, locals, &block)
       else
-        name = self.class.path_translator(path)
-        "#{self.class.template_destination}[\"#{name}\"] = #{self.class.template_compiler}(\"#{template.strip.gsub(/(\r\n|[\n\r"'])/) { JS_ESCAPE_MAP[$1] }}\");\n"
+        @engine.render(scope, locals, &block)
       end
     end
 
-    # Used to change the asset path into a string which is
-    # safe to use as a JavaScript object property. When
-    # the template is a partial (ie starts with a '_')
-    def partial_path_translator(path)
-      path = remove_underscore_from_partial_path(path)
-      self.class.path_translator(path).gsub(%r{/}, '.')
-    end
-
     private
 
-    def remove_underscore_from_partial_path(path)
-      path.sub(/(.*)(\/|^)_(.+?)$/, '\1\2\3')
-    end
-
     # Precompiled Haml source. Taken from the precompiled_with_ambles
     # method in Haml::Precompiler:
     # http://github.com/nex3/haml/blob/master/lib/haml/precompiler.rb#L111-126

data/lib/hamlbars/version.rb

@@ -1,3 +1,3 @@
 module Hamlbars
-  VERSION = '1.1.0'
+  VERSION = '2.0.0'
 end

metadata

@@ -1,128 +1,128 @@
 --- !ruby/object:Gem::Specification
 name: hamlbars
 version: !ruby/object:Gem::Version
-  version: 1.1.0
   prerelease: 
+  version: 2.0.0
 platform: ruby
 authors:
 - James Harton
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-13 00:00:00.000000000 Z
+date: 2012-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  prerelease: false
   name: haml
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
   type: :runtime
-  prerelease: false
+- !ruby/object:Gem::Dependency
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
+    none: false
+  prerelease: false
   name: sprockets
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
   type: :runtime
-  prerelease: false
+- !ruby/object:Gem::Dependency
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
+    none: false
+  prerelease: false
   name: tilt
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
   type: :runtime
-  prerelease: false
+- !ruby/object:Gem::Dependency
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
+        version: '1.2'
+    none: false
+  prerelease: false
   name: execjs
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '1.2'
+    none: false
   type: :runtime
-  prerelease: false
+- !ruby/object:Gem::Dependency
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '1.2'
-- !ruby/object:Gem::Dependency
+        version: '0'
+    none: false
+  prerelease: false
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
   type: :development
-  prerelease: false
+- !ruby/object:Gem::Dependency
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
+        version: 2.10.0
+    none: false
+  prerelease: false
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 2.10.0
+    none: false
   type: :development
-  prerelease: false
+- !ruby/object:Gem::Dependency
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 2.10.0
-- !ruby/object:Gem::Dependency
+        version: '0'
+    none: false
+  prerelease: false
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  type: :development
 description: Hamlbars allows you to write handlebars templates using the familiar
   Haml syntax.
 email:
@@ -134,9 +134,7 @@ files:
 - README.md
 - History.md
 - MIT-LICENSE
-- lib/hamlbars/ext/closure.rb
 - lib/hamlbars/ext/compiler.rb
-- lib/hamlbars/ext/precompiler.rb
 - lib/hamlbars/ext/rails_helper.rb
 - lib/hamlbars/ext.rb
 - lib/hamlbars/template.rb
@@ -146,28 +144,38 @@ files:
 - vendor/javascripts/precompiler.js
 homepage: https://github.com/jamesotron/hamlbars
 licenses: []
-post_install_message: 
+post_install_message: ! "  DEPRECATION WARNING: Hamlbars 2.0 removes asset compilation!\n\n
+  \ Template compilation in Hamlbars was a major source of confusion and bugs\n  since
+  roughly half of its users are using Handlebars.js in their apps and\n  the other
+  half are using Handlebars as part of Ember.js.\n\n  Hamlbars now simply outputs
+  the rendered HTML marked up with Handlebars\n  sections.  It is up to you to choose
+  the Handlebars compiler that works\n  for you.\n\n  If you're using Ember.js I would
+  suggest adding ember-rails to your\n  Gemfile.\n\n  If you're using Handlebars.js
+  then I would suggest adding handlebars_assets\n  to your Gemfile.\n\n  For both
+  of the above gems you may need to rename your templates to\n  `mytemplate.js.hbs.hamlbars`
+  in order for the output of Hamlbars to be sent\n  into the correct compiler.\n\n
+  \ Thanks for using Hamlbars. You're awesome.\n  @jamesotron\n"
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
       segments:
       - 0
-      hash: -951484081994800646
-required_rubygems_version: !ruby/object:Gem::Requirement
+      hash: 2248097403162291800
   none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
       segments:
       - 0
-      hash: -951484081994800646
+      hash: 2248097403162291800
+  none: false
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24

data/lib/hamlbars/ext/closure.rb

@@ -1,43 +0,0 @@
-module Hamlbars
-  module Ext
-    module Closure
-
-      def self.included(base)
-        base.extend ClassMethods
-      end
-      
-      # Wraps the JavaScript generated by Haml::Template#evaluate
-      # in a JavaScript closure.
-      def evaluate_with_closure(scope, locals, &block)
-        self.class.closures_enabled? ? enclosify { evaluate_without_closure(scope,locals,&block) } : evaluate_without_closure(scope,locals,&block)
-      end
-
-      private
-
-      def enclosify
-        "(function() { #{yield} }).call(this)"
-      end
-
-      module ClassMethods
-        # Enables closure wrapping for rendered templates.
-        def enable_closures!
-          @enable_closures = true
-          unless public_method_defined? :evaluate_without_closure
-            alias_method :evaluate_without_closure, :evaluate
-            alias_method :evaluate, :evaluate_with_closure
-          end
-        end
-
-        def closures_enabled?
-          !!@enable_closures
-        end
-
-        # Disables closure wrapping for rendered templates.
-        def disable_closures!
-          @enable_closures = false
-        end
-      end
-
-    end
-  end
-end

data/lib/hamlbars/ext/precompiler.rb

@@ -1,71 +0,0 @@
-require 'execjs'
-
-module Hamlbars
-  module Ext
-    module Precompiler
-
-      def self.included(base)
-        base.extend ClassMethods
-      end
-
-      # Takes the rendered template and compiles it using the Handlebars
-      # compiler via ExecJS.
-      def evaluate_with_precompiler(scope, locals, &block)
-        if self.class.precompiler_enabled? 
-          precompile { evaluate_without_precompiler(scope,locals,&block) }
-        else
-          evaluate_without_precompiler(scope,locals,&block)
-        end
-      end
-
-      private
-
-      def precompile
-        str = yield
-        str.gsub(Regexp.new("(#{Hamlbars::Template.template_compiler})\((.+)\)")) do |match|
-          # No named groups. WAT!
-          compiler = $1
-          template = $2
-          if compiler =~ /\.compile$/
-            "#{compiler.gsub(/\.compile$/, '.template')}(#{runtime.call('Hamlbars.precompile', template)})"
-          else
-            # Unable to precompile.
-            match
-          end
-        end
-      end
-
-      def runtime
-        Thread.current[:hamlbars_js_runtime] ||= ExecJS.compile(js)
-      end
-
-      def js
-        [ 'handlebars.js', 'precompiler.js' ].map do |name|
-          File.read(File.expand_path("../../../../vendor/javascripts/#{name}", __FILE__))
-        end.join("\n")
-      end
-
-      module ClassMethods
-
-        # Enables use of the Handlebars compiler when rendering
-        # templates.
-        def enable_precompiler!
-          @precompiler_enabled = true
-          unless public_method_defined? :evaluate_without_precompiler
-            alias_method :evaluate_without_precompiler, :evaluate
-            alias_method :evaluate, :evaluate_with_precompiler
-          end
-        end
-
-        def precompiler_enabled?
-          !!@precompiler_enabled
-        end
-
-        def disable_precompiler!
-          @precompiler_enabled = false
-        end
-      end
-
-    end
-  end
-end