haml_coffee_assets 0.0.1 → 0.2.0

data/README.md

@@ -1,14 +1,17 @@
-# HamlCoffeeAssets [![Build Status](https://secure.travis-ci.org/netzpirat/haml_coffee_assets.png)](http://travis-ci.org/netzpirat/haml_coffee_assets)
+# Haml Coffee Assets [![Build Status](https://secure.travis-ci.org/netzpirat/haml_coffee_assets.png)](http://travis-ci.org/netzpirat/haml_coffee_assets)
 
-HamlCoffeeAssets compiles [Haml CoffeeScript](https://github.com/9elements/haml-coffee) templates in the Rails 3.1 asset
-pipeline.
+Haml Coffee Assets compiles [Haml CoffeeScript](https://github.com/netzpirat/haml-coffee) templates in the Rails 3.1
+asset pipeline, so you can use them as JavaScript templates in your JavaScript heavy Rails application.
 
-Tested on MRI Ruby 1.8.7, 1.9.2, REE and the latest versions of JRuby.
+Tested on MRI Ruby 1.8.7, 1.9.2, 1.9.3, REE and the latest version of JRuby.
 
-## HamlCoffee
+**Please note that I'm using haml-coffee from my fork until
+[my pull request](https://github.com/9elements/haml-coffee/pull/7) is merged.**
 
-HamlCoffee allows you to write inline [CoffeeScript](http://jashkenas.github.com/coffee-script/) in your
-[HAML](http://haml-lang.com/) template:
+## Haml Coffee
+
+Haml Coffee allows you to write inline [CoffeeScript](http://jashkenas.github.com/coffee-script/) in your
+[HAML](http://haml-lang.com/) JavaScript templates:
 
 ```haml
 #cart
@@ -27,7 +30,7 @@ HamlCoffee allows you to write inline [CoffeeScript](http://jashkenas.github.com
 
 ## Installation
 
-The simplest way to install Guard is to use [Bundler](http://gembundler.com/).
+The simplest way to install Haml Coffee Assets is to use [Bundler](http://gembundler.com/).
 Add `haml_coffee_assets` and `execjs` to your `Gemfile`:
 
 ```ruby
@@ -37,15 +40,18 @@ group :assets do
 end
 ```
 
-And require the `hamlcoffee.js` in your `application.js.coffee`
+And require the `hamlcoffee.js` in your `app/assets/javascripts/application.js.coffee`:
 
 ```coffeescript
 #= require hamlcoffee
 ```
 
+This provides the default escaping and the global context functions. Read more about it in the configuration section
+below.
+
 ### JavaScript runtimes
 
-HamlCoffeeAssets uses [ExecJS](https://github.com/sstephenson/execjs) to pick the best runtime to evaluate the
+Haml Coffee Assets uses [ExecJS](https://github.com/sstephenson/execjs) to pick the best runtime to evaluate the
 CoffeeScript and generate the JavaScript template.
 
 * With CRuby you want to use a V8 JavaScript Engine or Mozilla SpiderMonkey.
@@ -117,77 +123,125 @@ Windows operating systems.
 
 ## Usage
 
-You should place all your HamlCoffee templates in the `app/assets/templates` directory and include all templates in
-your `application.js.coffee`:
+You should place all your Haml Coffee templates in the `app/assets/templates` directory and include all templates from
+your `app/assets/javascripts/application.js.coffee`:
 
 ```coffeescript
 #= require_tree ../templates
 ```
 
-Now you can start to add your HamlCoffee templates to your template directory. Make sure all your templates have a
-`.hamlc` extension to be recognized by HamlCoffeeAssets.
+Now you can start to add your Haml Coffee templates to your template directory. Make sure all your templates have a
+`.hamlc` extension to be recognized by Haml Coffee Assets.
 
-**Note:** HamlCoffee already generates a JavaScript Template, so there is not need to pass it to the `JST` Sprocket
-processor by using `.jst.hamlc` as extension, and if you do, the HamlCoffee templates will not work.
+**Note:** Haml Coffee already generates a JavaScript Template, so there is not need to pass it to the `JST` Sprocket
+processor by using `.jst.hamlc` as extension, and if you do, the Haml Coffee templates will not work.
 
 ## Configuration
 
+### Document format
+
+By default all Haml Coffee templates are rendered to a HTML5 document. You can choose between the following output
+formats:
+
+* html
+* html4
+* xhtml
+
+If you prefer another HTML format than HTML5, you can set it in your `config/application.rb`:
+
+```ruby
+config.hamlcoffee.format = 'xhtml'
+```
+
 ### Template namespace
 
-By default all HamlCoffee templates are registered under the `JST` namespace.
+By default all Haml Coffee templates are registered under the `JST` namespace.
 
-Example:
+**Example:**
 
-A template located in `app/assets/templates/header.hamlc` with the given content:
+A template `app/assets/templates/header.hamlc` with the given content:
 
 ```haml
 %header
   %h2= title
 ```
 
-will be accessible in your browser as `JST.header`. You can now render the precompiled template with:
+will be accessible in your browser as `JST['header']`. You can now render the precompiled template and pass the data
+to be rendered:
 
 ```javascript
-JST.header.render({ title: 'Hello HamlCoffee' })
+JST['header'].render({ title: 'Hello Haml Coffee' })
 ```
 
-If you prefer another namespace, you can set it in your `application.rb`:
+If you prefer another namespace, you can set it in your `config/application.rb`:
 
 ```ruby
-config.hamlcoffee.namespace = 'HAML'
+config.hamlcoffee.namespace = 'window.HAML'
 ```
 
+#### Template name
+
+The name under which the template can be addressed in the namespace depends not only from the filename, but also on
+the directory name.
+
+The following examples assumes a configured namespace `window.JST` and the asset template directory
+`app/assets/templates`:
+
+* `app/assets/templates/login.hamlc` will become `JST['login']`
+* `app/assets/templates/users/new.hamlc` will become `JST['users/new']`
+* `app/assets/templates/shared/form/address.hamlc` will become `JST['shared/form/address']`
+
 ### Escaping
 
-By default your code block in your HamlCoffee template will be escaped through the `HAML.escape` function that is
-provided in the `haml_coffee_assets.js`.
+All generated output by running CoffeeScript in your template is being escaped, but you can disable escaping of either
+the attributes or the generated Html.
+
+#### Attribute escaping
 
-You can set another escaping function in your `application.rb`:
+You can toggle attribute escaping in your `config/application.rb`:
 
 ```ruby
-config.hamlcoffee.escape = 'App.myEscape'
+config.hamlcoffee.escapeAttributes = false
 ```
 
-or disable escaping completely:
+#### HTML escaping
+
+You can toggle HTML escaping in your `config/application.rb`:
+
+```ruby
+config.hamlcoffee.escapeHtml = false
+```
+
+#### Custom escape function
+
+By default your code block in your Haml Coffee template will be escaped through the `HAML.escape` function that is
+provided in the `hamlcoffee.js` script.
+
+You can set another escaping function in your `config/application.rb`:
 
 ```ruby
-config.hamlcoffee.escape = false
+config.hamlcoffee.customHtmlEscape = 'App.myEscape'
 ```
 
-Your custom escape function must take the unescaped text as parameter and returns the escape function.
-The following example implements only ampersand escaping:
+Your custom escape function must take the unescaped text as parameter and returns the escaped text.
+The following default implementation comes with `hamlcoffee.js`:
 
 ```coffeescript
-App.myEscape = (text) -> text.replace(/&/g, '&')
+App.myEscape = (text) ->
+  ('' + text)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
 ```
 
-### Global Context
+### Global context
 
-HamlCoffeeAssets allows you to configure a global context function that gets merged into the local template context for
+Haml Coffee Assets allows you to configure a global context function that gets merged into the local template context for
 each template.
 
-There is a example implementation provided in the `haml_coffee_assets.js` that uses the `extend` function
-from these frameworks:
+There is a example implementation provided in the `hamlcoffee.js` that can use the `extend` like functions
+from the listed frameworks to merge the global and the local conext data:
 
 * jQuery
 * Underscore.js
@@ -195,17 +249,28 @@ from these frameworks:
 * MooTools
 * Zepto.js
 
-If you use one of these, than you can simply override `HAML.globals` and return the global HAML context object:
+If you use one of these, than you can simply override `HAML.globals` and return the global context data:
 
 ```coffeescript
 HAML.globals = ->
   {
-    authenticated: App.isAuthenticated()
+    isAuthenticated: App.isAuthenticated()
     isAdmin: App.currentUser.hasRole('admin')
   }
 ```
 
-If you like to use your own implementation, simply configure your context function in your `application.rb`:
+Now you can use the properties from the global context in every template:
+
+```haml
+.not-found-error
+  %h1= I18n.t('js.app.notfound.error', { route: @route })
+  - if @isAuthenticated
+    %p= I18n.t('js.app.notfound.homepage')
+  - else
+    %p= I18n.t('js.app.notfound.login')
+```
+
+If you like to use your own implementation, simply configure your context function in your `config/application.rb`:
 
 ```ruby
 config.hamlcoffee.context = 'App.globalTemplateContext'
@@ -217,9 +282,9 @@ or disable the global context completely:
 config.hamlcoffee.context = false
 ```
 
-Your custom context function must take the local context as parameter and returns the merged context function.
-The following example implementation used the _.underscore extend function to merge an inline defined global
-context:
+Your custom context function must take the local context as parameter and returns the merged context data.
+The following example uses the _.underscore `extend` function to merge the global context data with the
+passed local context data:
 
 ```coffeescript
 App.globalTemplateContext = (locals) -> _.extend({}, {

data/lib/haml_coffee_assets/engine.rb

@@ -9,9 +9,12 @@ module HamlCoffeeAssets
     config.hamlcoffee = ActiveSupport::OrderedOptions.new
 
     DEFAULT_CONFIG = {
-        :namespace => 'HAML',
-        :escape    => 'HAML.escape',
-        :context   => 'HAML.context'
+        :format           => 'html5',
+        :namespace        => 'window.JST',
+        :escapeHtml       => true,
+        :escapeAttributes => true,
+        :customHtmlEscape => 'HAML.escape',
+        :context          => 'HAML.context'
     }
 
     # Initialize Haml Coffee Assets after Sprockets
@@ -26,9 +29,12 @@ module HamlCoffeeAssets
       options = DEFAULT_CONFIG.merge(app.config.hamlcoffee)
 
       HamlCoffee.configure do |config|
-        config.namespace = options[:namespace]
-        config.escape    = options[:escape]
-        config.context   = options[:context]
+        config.namespace        = options[:namespace]
+        config.format           = options[:format]
+        config.escapeHtml       = options[:escapeHtml]
+        config.escapeAttributes = options[:escapeAttributes]
+        config.customHtmlEscape = options[:customHtmlEscape]
+        config.context          = options[:context]
       end
     end
 

data/lib/haml_coffee_assets/haml_coffee.rb

@@ -7,7 +7,7 @@ module HamlCoffeeAssets
   module HamlCoffee
     class << self
 
-      mattr_accessor :namespace, :escape, :context
+      mattr_accessor :namespace, :format, :escapeHtml, :escapeAttributes, :customHtmlEscape, :context
 
       # Configure HamlCoffee
       #
@@ -22,7 +22,9 @@ module HamlCoffeeAssets
       # @return [String] the compiled template in JavaScript
       #
       def compile(name, source)
-        runtime.call('HamlCoffeeAssets.compile', namespace, name, source, escape, context)
+        runtime.call('HamlCoffeeAssets.compile',
+                     namespace, name, source, format,
+                     escapeHtml, escapeAttributes, customHtmlEscape, context)
       end
 
       private

data/lib/haml_coffee_assets/haml_coffee_assets.js

@@ -15,15 +15,25 @@ var HamlCoffeeAssets = (function(){
     var Compiler = require('/compiler.js');
 
     /**
-     * Test if the argument is present
+     * Test if the string argument is present
      *
-     * @param object [Object] the object to test
+     * @param object [String] the string to test
      * @return [Boolean] whether the object is present
      */
-    function isPresent(object) {
+    function isStringPresent(object) {
       return toString.call(object) === '[object String]' && object.length !== 0
     }
 
+    /**
+     * Test if the boolean argument is present
+     *
+     * @param object [Boolean] the boolean to test
+     * @return [Boolean] whether the object is present
+     */
+    function isBooleanPresent(object) {
+      return toString.call(object) === '[object Boolean]'
+    }
+
     return {
 
       /**
@@ -32,28 +42,47 @@ var HamlCoffeeAssets = (function(){
        * @param namespace [String] the template namespace
        * @param name [String] the name of the template that is registered to the namespace
        * @param source [String] the template source code to be compiled
-       * @param escape [String] the name of the function to escape the output
+       * @param escapeHtml [Boolean] whether to escape HTML output by default or not
+       * @param escapeAttributes [Boolean] whether to escape HTML attributes output by default or not
+       * @param customHtmlEscape [String] the name of the function to escape the output
        * @param context [String] the name of the function to merge contexts
        */
-      compile: function(namespace, name, source, escape, context) {
+      compile: function(namespace, name, source, format, escapeHtml, escapeAttributes, customHtmlEscape, context) {
 
         var compiler, jst;
 
-        if (!isPresent(namespace)) {
-           namespace = 'HAML'
+        if (!isStringPresent(namespace)) {
+          namespace = 'window.HAML'
         }
 
-        if (isPresent(escape)) {
-          compiler = new Compiler({ escape_html: true, custom_html_escape: escape });
-        } else {
-          compiler = new Compiler({ escape_html: false });
+        if (!isStringPresent(format)) {
+          format = 'html5'
         }
 
+        if (!isBooleanPresent(escapeHtml)) {
+          escapeHtml = true
+        }
+
+        if (!isBooleanPresent(escapeAttributes)) {
+          escapeAttributes = true
+        }
+
+        if (!isStringPresent(customHtmlEscape)) {
+          customHtmlEscape = 'window.HAML.escape'
+        }
+
+        compiler = new Compiler({
+          format: format,
+          escapeHtml: escapeHtml,
+          escapeAttributes: escapeAttributes,
+          customHtmlEscape: customHtmlEscape
+        });
+
         compiler.parse(source);
 
         jst = CoffeeScript.compile(compiler.render(name, namespace));
 
-        if (isPresent(context)) {
+        if (isStringPresent(context)) {
           jst = jst.replace('fn.call(context);', 'fn.call(' + context +'(context));');
         }
 

data/lib/haml_coffee_assets/haml_coffee_template.rb

@@ -32,7 +32,7 @@ module HamlCoffeeAssets
     # Compile the template.
     #
     def evaluate(scope, locals = { }, &block)
-      @output ||= HamlCoffee.compile(name, data)
+      @output ||= HamlCoffee.compile(scope.logical_path, data)
     end
 
   end

data/lib/haml_coffee_assets/version.rb

@@ -1,5 +1,5 @@
 # coding: UTF-8
 
 module HamlCoffeeAssets
-  VERSION = '0.0.1' unless defined?(HamlCoffeeAssets::VERSION)
+  VERSION = '0.2.0' unless defined?(HamlCoffeeAssets::VERSION)
 end