Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Merge pull request #22 from joliss/doc

Doc
  • Loading branch information...
commit 63adadad32e4c244713243cc892c796e1cdf2c2c 2 parents 7612294 + 1ad878f
James Harton authored May 29, 2012

Showing 2 changed files with 117 additions and 47 deletions. Show diff stats Hide diff stats

  1. 2  History.md
  2. 162  README.md
2  History.md
Source Rendered
... ...
@@ -1,5 +1,7 @@
1 1
 # master
2 2
 
  3
+# 1.0.0
  4
+
3 5
 * Drop support for `.hbs` extension (#11)
4 6
 
5 7
 # 2012.3.21
162  README.md
Source Rendered
@@ -3,127 +3,195 @@
3 3
 [![Build Status](https://secure.travis-ci.org/jamesotron/hamlbars.png?branch=master)](http://travis-ci.org/jamesotron/hamlbars)
4 4
 [![Dependency Status](https://gemnasium.com/jamesotron/hamlbars.png)](https://gemnasium.com/jamesotron/hamlbars)
5 5
 
6  
-[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).
  6
+[Hamlbars](https://github.com/jamesotron/hamlbars) is a Ruby gem which allows
  7
+you to easily generate [Handlebars](http://handlebarsjs.com) templates using
  8
+[Haml](http://www.haml-lang.com).
  9
+
  10
+# Installation
  11
+
  12
+Add the following line to your Gemfile (on Rails, inside the `:assets` group):
  13
+
  14
+```ruby
  15
+gem 'hamlbars', '~> 1.0'
  16
+```
  17
+
  18
+If you are stuck with an older, yanked version like 2012.3.21 and it won't
  19
+update to 1.0, be sure to add `'~> 1.0'` as the version spec and run `bundle
  20
+install`.
7 21
 
8 22
 # Demo Site
9 23
 
10  
-If you're unsure how all the pieces fit together then take a quick look at the [demo site](http://hamlbars-demo.herokuapp.com/).
  24
+If you're unsure how all the pieces fit together then take a quick look at the
  25
+[demo site](http://hamlbars-demo.herokuapp.com/).
11 26
 
12 27
 # Attribute bindings
13 28
 
14  
-You can easily add attribute bindings by adding a `:bind` hash to the tag attributes, like so:
  29
+You can easily add attribute bindings by adding a `:bind` hash to the tag
  30
+attributes, like so:
15 31
 
16  
-    %div{ :class => 'widget', :bind => { :title => 'App.widgetController.title' }
  32
+```haml
  33
+%div{ :class => 'widget', :bind => { :title => 'App.widgetController.title' }
  34
+```
17 35
 
18 36
 Which will generate the following output:
19 37
 
20  
-    <div class="widget" {{bindAttr title="App.widgetController.title"}}></div>
  38
+```handlebars
  39
+<div class="widget" {{bindAttr title="App.widgetController.title"}}></div>
  40
+```
21 41
 
22 42
 # Event bindings
23 43
 
24  
-You can add one or more event actions by adding an event hash or array or event hashes to the tag options:
  44
+You can add one or more event actions by adding an event hash or array or event
  45
+hashes to the tag options:
25 46
 
26  
-    %a{ :event => { :on => 'click', :action => 'clicked' } } Click
  47
+```haml
  48
+%a{ :event => { :on => 'click', :action => 'clicked' } } Click
  49
+```
27 50
 
28 51
 or
29 52
 
30  
-    %div{ :events => [ { :on => 'mouseover', :action => 'highlightView' }, { :on => 'mouseout', :action => 'disableViewHighlight' } ] }
  53
+```haml
  54
+%div{ :events => [ { :on => 'mouseover', :action => 'highlightView' }, { :on => 'mouseout', :action => 'disableViewHighlight' } ] }
  55
+```
31 56
 
32 57
 Note that the default event is `click`, so it's not necessary to specify it:
33 58
 
34  
-    %a{ :event => { :action => 'clicked' } } Click
  59
+```haml
  60
+%a{ :event => { :action => 'clicked' } } Click
  61
+```
35 62
 
36  
-# Handlebar helper
  63
+# Handlebars helper
37 64
 
38  
-You can use the `handlebars` helper (or just `hb` for short) to generate both Handlebar blocks and expressions.
  65
+You can use the `handlebars` helper (or just `hb` for short) to generate both
  66
+Handlebars blocks and expressions.
39 67
 
40 68
 ## Expressions
41 69
 
42  
-Generating Handlebars expressions is as simple as using the `handlebars` helper and providing the expression as a string argument:
  70
+Generating Handlebars expressions is as simple as using the `handlebars` helper
  71
+and providing the expression as a string argument:
43 72
 
44  
-    = hb 'App.widgetController.title'
  73
+```haml
  74
+= hb 'App.widgetController.title'
  75
+```
45 76
 
46 77
 which will will generate:
47 78
 
48  
-    {{App.widgetController.title}}
  79
+```handlebars
  80
+{{App.widgetController.title}}
  81
+```
49 82
 
50 83
 ## Blocks
51 84
 
52  
-Whereas passing a block to the `handlebars` helper will create a Handlebars block expression:
  85
+Whereas passing a block to the `handlebars` helper will create a Handlebars
  86
+block expression:
53 87
 
54  
-    %ul.authors
55  
-    = hb 'each authors' do
56  
-      %li<
57  
-	= succeed ',' do
58  
-	  = hb 'lastName'
59  
-	= hb 'firstName'
  88
+```haml
  89
+%ul.authors
  90
+= hb 'each authors' do
  91
+  %li<
  92
+    = succeed ',' do
  93
+      = hb 'lastName'
  94
+    = hb 'firstName'
  95
+```
60 96
 
61 97
 will result in the following markup:
62 98
 
63  
-    <ul class="authors">
64  
-       {{#each authors}}
65  
-         <li>{{lastName}}, {{firstName}}</li>
66  
-       {{/each}}
67  
-    </ul>
  99
+```handlebars
  100
+<ul class="authors">
  101
+   {{#each authors}}
  102
+     <li>{{lastName}}, {{firstName}}</li>
  103
+   {{/each}}
  104
+</ul>
  105
+```
68 106
 
69 107
 ## Options
70 108
 
71  
-The `hb` helper can take an optional hash of options which will be rendered inside the expression:
  109
+The `hb` helper can take an optional hash of options which will be rendered
  110
+inside the expression:
72 111
 
73  
-    = hb 'view App.InfoView', :tagName => 'span'
  112
+```haml
  113
+= hb 'view App.InfoView', :tagName => 'span'
  114
+```
74 115
 
75 116
 will result in:
76 117
 
77  
-    {{view App.InfoView tagName="span"}}
  118
+```handlebars
  119
+{{view App.InfoView tagName="span"}}
  120
+```
78 121
 
79 122
 ## Tripple-stash
80 123
 
81  
-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.
  124
+You can use the `handlebars!` or `hb!` variant of the `handlebars` helper to
  125
+output "tripple-stash" expressions within which Handlebars does not escape the
  126
+output.
82 127
 
83 128
 # Configuring template output:
84 129
 
85  
-`hamlbars` has three configuration options, which pertain to the generated JavaScript:
  130
+`hamlbars` has three configuration options, which pertain to the generated
  131
+JavaScript:
86 132
 
87  
-    Hamlbars::Template.template_destination    # default 'Handlebars.templates'
88  
-    Hamlbars::Template.template_compiler       # default 'Handlebars.compile'
89  
-    Hamlbars::Template.template_partial_method # default 'Handlebars.registerPartial'
  133
+```ruby
  134
+Hamlbars::Template.template_destination    # default 'Handlebars.templates'
  135
+Hamlbars::Template.template_compiler       # default 'Handlebars.compile'
  136
+Hamlbars::Template.template_partial_method # default 'Handlebars.registerPartial'
  137
+```
90 138
 
91  
-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.
  139
+These settings will work find by default if you are using Handlebars as a
  140
+standalone JavaScript library, however if you are using something that embeds
  141
+Handlebars within it then you'll have to change these.
92 142
 
93 143
 If you're using [Ember.js](http://www.emberjs.com) then you can use:
94 144
 
95  
-    Hamlbars::Template.render_templates_for :ember
  145
+```ruby
  146
+Hamlbars::Template.render_templates_for :ember
  147
+```
96 148
 
97 149
 Which is effectively the same as:
98 150
 
99  
-    Hamlbars::Template.template_destination = 'Ember.TEMPLATES'
100  
-    Hamlbars::Template.template_compiler = 'Ember.Handlebars.compile'
101  
-    Hamlbars::Template.template_partial_method = 'Ember.Handlebars.registerPartial'
  151
+```ruby
  152
+Hamlbars::Template.template_destination = 'Ember.TEMPLATES'
  153
+Hamlbars::Template.template_compiler = 'Ember.Handlebars.compile'
  154
+Hamlbars::Template.template_partial_method = 'Ember.Handlebars.registerPartial'
  155
+```
102 156
 
103  
-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!
  157
+The good news is that if you're using the
  158
+[emberjs-rails](http://www.rubygems.org/gems/emberjs-rails) gem then it will
  159
+automatically detect hamlbars and change it for you. Magic!
104 160
 
105  
-If you're using [ember-rails](http://rubygems.org/gems/ember-rails) then you'll need to put this in a initializer.
  161
+If you're using [ember-rails](http://rubygems.org/gems/ember-rails) then you'll
  162
+need to put this in a initializer.
106 163
 
107 164
 # Configuring JavaScript output:
108 165
 
109  
-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:
  166
+Hamlbars has experimental support for template precompilation using
  167
+[ExecJS](http://rubygems.org/gems/execjs). To enable it, call
110 168
 
111  
-    Hamlbars::Template.enable_precompiler!
  169
+```ruby
  170
+Hamlbars::Template.enable_precompiler!
  171
+```
112 172
 
113 173
 You can also disable enclosification (which is enabled by default) using:
114 174
 
115  
-    Hamlbars::Template.disable_closures!
  175
+```ruby
  176
+Hamlbars::Template.disable_closures!
  177
+```
116 178
 
117 179
 # Asset pipeline
118 180
 
119  
-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.
  181
+Hamlbars is specifically designed for use with Rails 3.1's asset pipeline.
  182
+Simply create templates ending in `.js.hamlbars` and Sprockets will know what
  183
+to do.
120 184
 
121 185
 # Rails helpers
122 186
 
123  
-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.
  187
+You can enable support by calling `Hamlbars::Template.enable_rails_helpers!`.
  188
+Probably the best way to do this is to create an initializer.  This is
  189
+dangerous and possibly stupid as a large number of Rails' helpers require
  190
+access to the request object, which is not present when compiling assets.
124 191
 
125 192
 **Use at your own risk. You have been warned.**
126 193
 
127 194
 # License and Copyright.
128 195
 
129  
-Hamlbars is Copyright &copy; 2012 [Sociable Limited](http://sociable.co.nz/) and licensed under the terms of the MIT License.
  196
+Hamlbars is Copyright &copy; 2012 [Sociable Limited](http://sociable.co.nz/)
  197
+and licensed under the terms of the MIT License.

0 notes on commit 63adada

Please sign in to comment.
Something went wrong with that request. Please try again.