hamlbars 1.0.0

data/History.md

@@ -0,0 +1,7 @@
+# master
+
+* Drop support for `.hbs` extension (#11)
+
+# 2012.3.21
+
+* (No history past this point. Here be dragons.)

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008-2010 Justin French
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,129 @@
+# Hamlbars
+
+[![Build Status](https://secure.travis-ci.org/jamesotron/hamlbars.png?branch=master)](http://travis-ci.org/jamesotron/hamlbars)
+[![Dependency Status](https://gemnasium.com/jamesotron/hamlbars.png)](https://gemnasium.com/jamesotron/hamlbars)
+
+[Hamlbars](https://github.com/jamesotron/hamlbars) is a Ruby gem which allows you to easily generate [Handlebar](http://handlebarsjs.com) templates using [Haml](http://www.haml-lang.com).
+
+# 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:
+
+    %div{ :class => 'widget', :bind => { :title => 'App.widgetController.title' }
+
+Which will generate the following output:
+
+    <div class="widget" {{bindAttr title="App.widgetController.title"}}></div>
+
+# Event bindings
+
+You can add one or more event actions by adding an event hash or array or event hashes to the tag options:
+
+    %a{ :event => { :on => 'click', :action => 'clicked' } } Click
+
+or
+
+    %div{ :events => [ { :on => 'mouseover', :action => 'highlightView' }, { :on => 'mouseout', :action => 'disableViewHighlight' } ] }
+
+Note that the default event is `click`, so it's not necessary to specify it:
+
+    %a{ :event => { :action => 'clicked' } } Click
+
+# Handlebar helper
+
+You can use the `handlebars` helper (or just `hb` for short) to generate both Handlebar blocks and expressions.
+
+## Expressions
+
+Generating Handlebars expressions is as simple as using the `handlebars` helper and providing the expression as a string argument:
+
+    = hb 'App.widgetController.title'
+
+which will will generate:
+
+    {{App.widgetController.title}}
+
+## Blocks
+
+Whereas passing a block to the `handlebars` helper will create a Handlebars block expression:
+
+    %ul.authors
+    = hb 'each authors' do
+      %li<
+	= succeed ',' do
+	  = hb 'lastName'
+	= hb 'firstName'
+
+will result in the following markup:
+
+    <ul class="authors">
+       {{#each authors}}
+         <li>{{lastName}}, {{firstName}}</li>
+       {{/each}}
+    </ul>
+
+## Options
+
+The `hb` helper can take an optional hash of options which will be rendered inside the expression:
+
+    = hb 'view App.InfoView', :tagName => 'span'
+
+will result in:
+
+    {{view App.InfoView tagName="span"}}
+
+## 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:
+
+`hamlbars` has three configuration options, which pertain to the generated JavaScript:
+
+    Hamlbars::Template.template_destination    # default 'Handlebars.templates'
+    Hamlbars::Template.template_compiler       # default 'Handlebars.compile'
+    Hamlbars::Template.template_partial_method # default 'Handlebars.registerPartial'
+
+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:
+
+    Hamlbars::Template.render_templates_for :ember
+
+Which is effectively the same as:
+
+    Hamlbars::Template.template_destination = 'Ember.TEMPLATES'
+    Hamlbars::Template.template_compiler = 'Ember.Handlebars.compile'
+    Hamlbars::Template.template_partial_method = 'Ember.Handlebars.registerPartial'
+
+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're using [ember-rails](http://rubygems.org/gems/ember-rails) then you'll need to put this in a initializer.
+
+# Configuring JavaScript output:
+
+As of version 2012.3.21 `hamlbars` has experimental support for template precompilation using [ExecJS](http://rubygems.org/gems/execjs).  If you want to enable this support you can use:
+
+    Hamlbars::Template.enable_precompiler!
+
+You can also disable enclosification (which is enabled by default) using:
+
+    Hamlbars::Template.disable_closures!
+
+# Asset pipeline
+
+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.
+
+# Rails helpers
+
+You can enable support by calling `Hamlbars::Template.enable_rails_helpers!`. 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.
+
+**Use at your own risk. You have been warned.**
+
+# License and Copyright.
+
+Hamlbars is Copyright &copy; 2012 [Sociable Limited](http://sociable.co.nz/) and licensed under the terms of the MIT License.

data/lib/hamlbars/ext/closure.rb

@@ -0,0 +1,43 @@
+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/compiler.rb

@@ -0,0 +1,45 @@
+module Hamlbars
+  module Ext
+    module Compiler
+    end
+  end
+end
+
+module Haml
+  module Compiler
+
+    class << self
+      # Overload build_attributes in Haml::Compiler to allow
+      # for the creation of handlebars bound attributes by
+      # adding :bind hash to the tag attributes.
+      def build_attributes_with_handlebars_attributes (is_html, attr_wrapper, escape_attrs, attributes={})
+        attributes[:bind] = attributes.delete('bind') if attributes['bind']
+        attributes[:event] = attributes.delete('event') if attributes['event']
+        attributes[:events] = attributes.delete('events') if attributes['events']
+        attributes[:events] ||= []
+        attributes[:events] << attributes.delete(:event) if attributes[:event]
+
+        handlebars_rendered_attributes = []
+        handlebars_rendered_attributes << handlebars_attributes('bindAttr', attributes.delete(:bind)) if attributes[:bind]
+        attributes[:events].each do |event|
+          event[:on] = event.delete('on') || event.delete(:on) || 'click'
+          action = event.delete('action') || event.delete(:action)
+          handlebars_rendered_attributes << handlebars_attributes("action \"#{action}\"", event)
+        end
+        attributes.delete(:events)
+
+        (handlebars_rendered_attributes * '') +
+          build_attributes_without_handlebars_attributes(is_html, attr_wrapper, escape_attrs, attributes)
+      end
+      alias build_attributes_without_handlebars_attributes build_attributes
+      alias build_attributes build_attributes_with_handlebars_attributes 
+
+      private
+
+      def handlebars_attributes(helper, attributes)
+        rendered_attributes = [].tap { |r|attributes.each { |k,v| r << "#{k}=\"#{v}\"" } }.join(' ')
+        " {{#{helper} #{rendered_attributes}}}"
+      end
+    end
+  end
+end

data/lib/hamlbars/ext/precompiler.rb

@@ -0,0 +1,71 @@
+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

data/lib/hamlbars/ext/rails_helper.rb

@@ -0,0 +1,38 @@
+module Hamlbars
+  module Ext
+    module RailsHelper
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      def evaluate(scope,locals,&block)
+        scope = scope.dup
+
+        scope.class.send(:include, ActionView::Helpers) if defined?(::ActionView)
+        if defined?(::Rails)
+          scope.class.send(:include, Rails.application.helpers)
+          scope.class.send(:include, Rails.application.routes.url_helpers)
+          scope.default_url_options = Rails.application.config.action_controller.default_url_options || {}
+        end
+        super(scope, locals, &block)
+      end
+
+      module ClassMethods
+        def enable_rails_helpers!
+          (Rails.env == 'development' ? Logger.new(STDOUT) : Rails.logger).warn "WARNING (hamlbars): Enabling helpers in assets can have unintended consequences and violates separation of concerns. You have been warned."
+          @enable_rails_helpers = true
+        end
+
+        def rails_helpers_enabled?
+          !!@enable_rails_helpers
+        end
+
+        def disable_rails_helpers!
+          @enable_rails_helpers = false
+        end
+      end
+
+    end
+  end
+end

data/lib/hamlbars/ext.rb

@@ -0,0 +1,8 @@
+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 :RailsHelper, File.expand_path('../ext/rails_helper.rb', __FILE__)
+  end
+end

data/lib/hamlbars/template.rb

@@ -0,0 +1,207 @@
+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'
+
+    def self.engine_initialized?
+      defined? ::Haml::Engine
+    end
+
+    def initialize_engine
+      require_template_library 'haml'
+    end
+
+    def prepare
+      options = @options.merge(:filename => eval_file, :line => line)
+      @engine = ::Haml::Engine.new(data, options)
+    end
+
+    # 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"
+      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"
+      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
+    def precompiled_template(locals)
+      @engine.precompiled
+    end
+
+    def precompiled_preamble(locals)
+      local_assigns = super
+      @engine.instance_eval do
+        <<-RUBY
+          begin
+            extend Haml::Helpers
+            _hamlout = @haml_buffer = Haml::Buffer.new(@haml_buffer, #{options_for_buffer.inspect})
+            _erbout = _hamlout.buffer
+            __in_erb_template = true
+            _haml_locals = locals
+        #{local_assigns}
+        RUBY
+      end
+    end
+
+    def precompiled_postamble(locals)
+      @engine.instance_eval do
+        <<-RUBY
+        #{precompiled_method_return_value}
+          ensure
+            @haml_buffer = @haml_buffer.upper
+          end
+        RUBY
+      end
+    end
+  end
+end
+
+module Haml
+  module Helpers
+
+    module HamlbarsExtensions
+      # Used to create handlebars expressions within HAML,
+      # if you pass a block then it will create a Handlebars
+      # block helper (ie "{{#expression}}..{{/expression}}" 
+      # otherwise it will create an expression 
+      # (ie "{{expression}}").
+      def handlebars(expression, options={}, &block)
+        express(['{{','}}'],expression,options,&block)
+      end
+      alias hb handlebars
+
+      # The same as #handlebars except that it outputs "triple-stash"
+      # expressions, which means that Handlebars won't escape the output.
+      def handlebars!(expression, options={}, &block)
+        express(['{{{','}}}'],expression,options,&block)
+      end
+      alias hb! handlebars!
+
+    private
+
+      def make(expression, options)
+        if options.any?
+          expression << " " << options.map {|key, value| "#{key}=\"#{value}\"" }.join(' ')
+        else
+          expression
+        end
+      end
+
+      def express(demarcation,expression,options={},&block)
+        if block.respond_to? :call
+          content = capture_haml(&block)
+          output = "#{demarcation.first}##{make(expression, options)}#{demarcation.last}#{content.strip}#{demarcation.first}/#{expression.split(' ').first}#{demarcation.last}"
+        else
+          output = "#{demarcation.first}#{make(expression, options)}#{demarcation.last}"
+        end
+
+        output = Haml::Util.html_safe(output) if Haml::Util.rails_xss_safe?
+        output
+      end
+    end
+
+    include HamlbarsExtensions
+  end
+end
+

data/lib/hamlbars/version.rb

@@ -0,0 +1,3 @@
+module Hamlbars
+  VERSION = '1.0.0'
+end

data/lib/hamlbars.rb

@@ -0,0 +1,22 @@
+require 'haml'
+require 'sprockets'
+
+module Hamlbars
+
+  if defined? Rails
+    class Engine < Rails::Engine
+    end
+  end
+
+  ROOT = File.expand_path(File.dirname(__FILE__))
+
+  autoload :Ext,      File.join(ROOT, 'hamlbars', 'ext')
+  autoload :Template, File.join(ROOT, 'hamlbars', 'template')
+
+  Haml::Compiler.send(:include, Ext::Compiler)
+
+  if defined? Sprockets
+    Sprockets.register_engine '.hamlbars', Template
+  end
+
+end