1 | # Haml Coffee Templates [![Build Status](https://secure.travis-ci.org/netzpirat/haml-coffee.png)](http://travis-ci.org/netzpirat/haml-coffee)
|
2 |
|
3 | Haml Coffee is a JavaScript templating solution that uses [Haml](http://haml-lang.com/) as markup, understands inline
|
4 | [CoffeeScript](http://jashkenas.github.com/coffee-script/) and generates a JavaScript function that renders to HTML. It
|
5 | can be used in client-side JavaScript applications that are using
|
6 | [Backbone.js](http://documentcloud.github.com/backbone/), [Spine.js](http://spinejs.com/),
|
7 | [JavaScriptMVC](http://javascriptmvc.com/), [KnockoutJS](http://knockoutjs.com/) and others, or on the server-side in
|
8 | frameworks like [Express](http://expressjs.com/).
|
9 |
|
10 | You can try Haml Coffee online by visiting [Haml Coffee Online](http://haml-coffee-online.herokuapp.com/).
|
11 |
|
12 | ## Installation
|
13 |
|
14 | Haml Coffee is available in NPM and can be installed with:
|
15 |
|
16 | ```bash
|
17 | $ npm install haml-coffee
|
18 | ```
|
19 |
|
20 | Please have a look at the [CHANGELOG](https://github.com/netzpirat/haml-coffee/blob/master/CHANGELOG.md) when upgrading to a
|
21 | newer Haml Coffee version with `npm update`.
|
22 |
|
23 | ## Integration
|
24 |
|
25 | There are different packages available to integrate Haml Coffee into your workflow:
|
26 |
|
27 | ### Node.JS
|
28 |
|
29 | * [grunt-haml](https://github.com/concordusapps/grunt-haml) for projects using [Grunt](http://gruntjs.com/).
|
30 | * [hem-haml-coffee](https://github.com/vojto/hem-haml-coffee) for projects using [Hem](https://github.com/maccman/hem/).
|
31 | * [stitch-haml-coffee](https://github.com/jnbt/stitch-haml-coffee) for projects using [Stitch](https://github.com/sstephenson/stitch).
|
32 | * [Mincer](https://github.com/nodeca/mincer) the Sprockets inspired web assets compiler.
|
33 |
|
34 | ### Ruby/Rails
|
35 |
|
36 | * [haml_coffee_assets](https://github.com/netzpirat/haml_coffee_assets) for projects using Rails.
|
37 | * [guard-haml-coffee](https://github.com/ouvrages/guard-haml-coffee) for projects using [Guard](https://github.com/guard/guard).
|
38 |
|
39 | ### Browser
|
40 |
|
41 | * [Haml Coffee compiler](https://raw.github.com/netzpirat/haml-coffee/master/dist/compiler/hamlcoffee.js)
|
42 | ([minified](https://raw.github.com/netzpirat/haml-coffee/master/dist/compiler/hamlcoffee.min.js))
|
43 | for compiling in the browser.
|
44 |
|
45 | The browser distribution doesn't come bundled with CoffeeScript, so you'll have to make sure you've
|
46 | included it before requiring haml-coffee.
|
47 |
|
48 | ## Compile Haml Coffee
|
49 |
|
50 | ### Using the API
|
51 |
|
52 | You can compile a Haml Coffee template to a JavaScript function and execute the function with the locals to render the
|
53 | HTML. The following code
|
54 |
|
55 | ```coffeescript
|
56 | hamlc = require 'haml-coffee'
|
57 | tmpl = hamlc.compile '%h1= @title'
|
58 | html = tmpl title: 'Haml Coffee rocks!'
|
59 | ```
|
60 |
|
61 | will create the HTML `<h1>Haml Coffee rocks!</h1>`.
|
62 |
|
63 | The `compile` function can take the compiler options as second parameter to customize the template function:
|
64 |
|
65 | ```coffeescript
|
66 | hamlc.compile '%h1= @title'
|
67 | cleanValue: false
|
68 | escapeHtml: false
|
69 | ```
|
70 |
|
71 | See the [compiler options](#compiler-options) for detailed information about all the available options and browse
|
72 | the [codo](https://github.com/netzpirat/codo) generated
|
73 | [Haml Coffee API documentation](http://coffeedoc.info/github/netzpirat/haml-coffee/master/).
|
74 |
|
75 | ### Using with Express
|
76 |
|
77 | You can configure [Express](http://expressjs.com/) to use Haml Coffee as template engine.
|
78 |
|
79 | #### Express 3
|
80 |
|
81 | Starting with version 1.4.0, Haml Coffee has support for Express 3 and can be registered as view engine as follows:
|
82 |
|
83 | ```coffeescript
|
84 | express = require 'express'
|
85 | app = express()
|
86 |
|
87 | app.engine 'hamlc', require('haml-coffee').__express
|
88 | ```
|
89 |
|
90 | Alternatively you can also use [consolidate.js](https://github.com/visionmedia/consolidate.js) to register the engine:
|
91 |
|
92 | ```coffeescript
|
93 | express = require 'express'
|
94 | cons = require 'consolidate'
|
95 | app = express()
|
96 |
|
97 | app.engine 'hamlc', cons['haml-coffee']
|
98 | ```
|
99 |
|
100 | #### Express 2
|
101 |
|
102 | Starting with version 0.5.0, Haml Coffee has support for Express 2 and can be registered as view engine as follows:
|
103 |
|
104 | ```coffeescript
|
105 | express = require 'express'
|
106 |
|
107 | app = express.createServer()
|
108 | app.register '.hamlc', require('haml-coffee')
|
109 | ```
|
110 |
|
111 | Alternatively you can also use [consolidate.js](https://github.com/visionmedia/consolidate.js) to register the engine:
|
112 |
|
113 | ```coffeescript
|
114 | express = require 'express'
|
115 | cons = require 'consolidate'
|
116 |
|
117 | app = express.createServer()
|
118 | app.register '.hamlc', cons['haml-coffee']
|
119 | ```
|
120 |
|
121 | #### Express Usage
|
122 |
|
123 | ##### Layouts
|
124 |
|
125 | Express 2 uses a layout file `layout.hamlc` by default and you have to insert the rendered view body into the layout like
|
126 | this:
|
127 |
|
128 | ```haml
|
129 | !!!
|
130 | %head
|
131 | %title Express App
|
132 | %body
|
133 | != @body
|
134 | ```
|
135 |
|
136 | Now you can create a Haml Coffee view
|
137 |
|
138 | ```haml
|
139 | %h1= "Welcome #{ @name }"
|
140 | %p You've rendered your first Haml Coffee view.
|
141 | ```
|
142 |
|
143 | that you can render with:
|
144 |
|
145 | ```coffeescript
|
146 | app.get '/', (req, res) ->
|
147 | res.render 'index.hamlc', name: 'Express user'
|
148 | ```
|
149 |
|
150 | Express 3 has removed layout support, but you can get it back by installing
|
151 | [express-partials](https://github.com/publicclass/express-partials) and configure it as middleware:
|
152 |
|
153 | ```
|
154 | partials = require 'express-partials'
|
155 | app.use partials()
|
156 | ```
|
157 |
|
158 | ##### Default template engine
|
159 |
|
160 | It's possible to use Haml Coffee as the default template engine by setting the `view engine`:
|
161 |
|
162 | ```coffeescript
|
163 | app.configure ->
|
164 | app.set 'view engine', 'hamlc'
|
165 | ```
|
166 |
|
167 | which allows you to omit the `.hamlc` extension when rendering a template:
|
168 |
|
169 | ```coffeescript
|
170 | app.get '/', (req, res) ->
|
171 | res.render 'index', name: 'Express user'
|
172 | ```
|
173 |
|
174 | ##### Compiler options
|
175 |
|
176 | With Express 3, you can set global compiler options by using `app.locals`:
|
177 |
|
178 | ```
|
179 | app.locals.uglify = true
|
180 | ```
|
181 |
|
182 | which is the same as:
|
183 |
|
184 | ```
|
185 | res.render view, { uglify: true }
|
186 | ```
|
187 |
|
188 | See the [compiler options](#compiler-options) for detailed information about all the available options.
|
189 |
|
190 | ### Using the CLI tool
|
191 |
|
192 | After the installation you will have a `haml-coffee` binary that can be used to compile single templates and even
|
193 | compile multiple templates recursively into a single file.
|
194 |
|
195 | ```bash
|
196 | $ haml-coffee
|
197 | Usage: node haml-coffee
|
198 |
|
199 | Options:
|
200 | -i, --input Either a file or a directory name to be compiled
|
201 | -o, --output Set the output filename
|
202 | -n, --namespace Set a custom template namespace
|
203 | -t, --template Set a custom template name
|
204 | -b, --basename Ignore file path when generate the template name
|
205 | -e, --extend Extend the template scope with the context
|
206 | ```
|
207 |
|
208 | _The following section describes only the options that are unique to the command line tool._
|
209 |
|
210 | You can see all the available options by executing `haml-coffee --help` and have a look at the
|
211 | [compiler options](#compiler-options) for detailed information about all the options.
|
212 |
|
213 | The `input` and `output` are optional and you can also directly redirect the streams.
|
214 |
|
215 | #### Input filename
|
216 |
|
217 | You can either specify a single template or a directory with the `-i`/`--input` argument. When you supply a directory,
|
218 | templates are being searched recursively:
|
219 |
|
220 | ```bash
|
221 | $ haml-coffee -i template.haml
|
222 | ```
|
223 |
|
224 | This will generate a template with the same name as the file but the extension changed to `.jst`. The above command for
|
225 | example would generate a template named `template.jst`.
|
226 |
|
227 | A valid Haml Coffee template must have one of the following extensions: `.haml`, `.html.haml`, `.hamlc` or
|
228 | `.html.hamlc`.
|
229 |
|
230 | #### Output filename
|
231 |
|
232 | You can specify a single output file name to be used instead of the automatic generated output file name with the
|
233 | `-o`/`--output` argument:
|
234 |
|
235 | ```bash
|
236 | $ haml-coffee -i template.haml -o t.js
|
237 | ```
|
238 |
|
239 | This creates a template named `t.js`. You can also set a directory as input and give an output file name for
|
240 | concatenating all templates into a single file:
|
241 |
|
242 | ```bash
|
243 | $ haml-coffee -i templates -o all.js
|
244 | ```
|
245 |
|
246 | This will create all the templates under the `templates` directory into a single, combined output file `all.js`.
|
247 |
|
248 | #### Template namespace
|
249 |
|
250 | Each template will register itself by default under the `window.HAML` namespace, but you can change the namespace with
|
251 | the `-n`/`--namespace` argument:
|
252 |
|
253 | ```bash
|
254 | $ haml-coffee -i template.haml -n exports.JST
|
255 | ```
|
256 |
|
257 | #### Template name
|
258 |
|
259 | Each template must have a unique name under which it can be addressed. By default the template name is derived from the
|
260 | template file name by stripping off all extensions and remove illegal characters. Directory names are converted to
|
261 | nested namespaces under the default namespace. For example, a template named `user/show-admin.html.haml` will result in
|
262 | a template that can be accessed by `window.HAML['user/show_admin']`.
|
263 |
|
264 | Given the `-b`/`--basename` argument, the deduced template name will not include the path to the template. For example,
|
265 | a template named `user/show-admin.html.haml` will result in a template that can be accessed by
|
266 | `window.HAML['show_admin']` instead of `window.HAML['user/show_admin']`.
|
267 |
|
268 | With the `-t`/`--template` argument you can set a template name manually:
|
269 |
|
270 | ```bash
|
271 | $ haml-coffee -i template.haml -n exports.JST -t other
|
272 | ```
|
273 |
|
274 | This will result in a template that can be accessed by `exports.JST['other']`.
|
275 |
|
276 | #### Extend the template scope
|
277 |
|
278 | By extending the template scope with the context, you can access your context data without `@` or `this`:
|
279 |
|
280 | ```Haml
|
281 | %h2= title
|
282 | ```
|
283 |
|
284 | This effect is achieved by using the [with](https://developer.mozilla.org/en/JavaScript/Reference/Statements/with)
|
285 | statement. Using with is forbidden in ECMAScript 5 strict mode.
|
286 |
|
287 | #### Stream redirection
|
288 |
|
289 | You can use Haml Coffee on the command line to enter a template and stop it with `Ctrl-D`:
|
290 |
|
291 | ```bash
|
292 | $ haml-coffee -p amd
|
293 | %h1 Hello AMD
|
294 | ^D
|
295 | ```
|
296 |
|
297 | which will output the AMD module source code to the console. You either have to set the placement option to `amd` or
|
298 | give it a template name like
|
299 |
|
300 | ```bash
|
301 | $ haml-coffee -t name
|
302 | %p JST rocks!
|
303 | ^D
|
304 | ```
|
305 |
|
306 | which will output the JST source code. Now you can also redirect files like:
|
307 |
|
308 | ```bash
|
309 | $ haml-coffee -t name < input.hamlc > output.jst
|
310 | ```
|
311 |
|
312 | ## Haml support
|
313 |
|
314 | Haml Coffee implements the [Haml Spec](https://github.com/haml/haml-spec) to ensure some degree of compatibility to
|
315 | other Haml implementations and the following sections are fully compatible to Ruby Haml:
|
316 |
|
317 | * Plain text
|
318 | * Multiline: `|`
|
319 | * Element names: `%`
|
320 | * Attributes: `{}` or `()`
|
321 | * Class and ID: `.` and `#`, implicit `div` elements
|
322 | * Self-closing tags: `/`
|
323 | * Doctype: `!!!`
|
324 | * HTML comments: `/`, conditional comments: `/[]`, Haml comments: `-#`
|
325 | * Running CoffeeScript: `-`, inserting CoffeeScript: `=`
|
326 | * CoffeeScript interpolation: `#{}`
|
327 | * Whitespace preservation: `~`
|
328 | * Whitespace removal: `>` and `<`
|
329 | * Escaping `\`
|
330 | * Escaping HTML: `&=`, unescaping HTML: `!=`
|
331 | * Filters: `:plain`, `:javascript`, `:css`, `:cdata`, `:escaped`, `:preserve`
|
332 | * Boolean attributes conversion
|
333 | * Haml object reference syntax: `[]`
|
334 |
|
335 | Please consult the official [Haml reference](http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html) for more
|
336 | details.
|
337 |
|
338 | Haml Coffee supports both Ruby 1.8 and Ruby 1.9 style attributes. So the following Ruby 1.8 style attribute
|
339 |
|
340 | ```haml
|
341 | %a{ :href => 'http://haml-lang.com/', :title => 'Haml home' } Haml
|
342 | ```
|
343 |
|
344 | can also be written in Ruby 1.9 style:
|
345 |
|
346 | ```haml
|
347 | %a{ href: 'http://haml-lang.com/', title: 'Haml home' } Haml
|
348 | ```
|
349 |
|
350 | HTML style tags are also supported:
|
351 |
|
352 | ```haml
|
353 | %a( href='http://haml-lang.com/' title='Haml home') Haml
|
354 | ```
|
355 |
|
356 | ### Helpers
|
357 |
|
358 | Haml Coffee supports a small subset of the Ruby Haml [helpers](http://haml-lang.com/docs/yardoc/Haml/Helpers.html). The
|
359 | provided helpers will bind the helper function to the template context, so it isn't necessary to use `=>`.
|
360 |
|
361 | #### Surround
|
362 |
|
363 | Surrounds a block of Haml code with strings, with no whitespace in between.
|
364 |
|
365 | ```haml
|
366 | != surround '(', ')', ->
|
367 | %a{:href => "food"} chicken
|
368 | ```
|
369 |
|
370 | produces the HTML output
|
371 |
|
372 | ```html
|
373 | (<a href='food'>chicken</a>)
|
374 | ```
|
375 |
|
376 | #### Succeed
|
377 |
|
378 | Appends a string to the end of a Haml block, with no whitespace between.
|
379 |
|
380 | ```haml
|
381 | click
|
382 | != succeed '.', ->
|
383 | %a{:href=>"thing"} here
|
384 | ```
|
385 |
|
386 | produces the HTML output
|
387 |
|
388 | ```html
|
389 | click
|
390 | <a href='thing'>here</a>.
|
391 | ```
|
392 |
|
393 | #### Precede
|
394 |
|
395 | Prepends a string to the beginning of a Haml block, with no whitespace between.
|
396 |
|
397 | ```haml
|
398 | != precede '*', ->
|
399 | %span.small Not really
|
400 | ```
|
401 |
|
402 | produces the HTML output
|
403 |
|
404 | ```html
|
405 | *<span class='small'>Not really</span>
|
406 | ```
|
407 |
|
408 | ### Object reference: `[]`
|
409 |
|
410 | Haml Coffee supports object references, but they are implemented slightly different due to the underlying runtime and
|
411 | different code style for CoffeeScript.
|
412 |
|
413 | Square brackets contain a CoffeeScript object or class that is used to set the class and id of that tag. The class is
|
414 | set to the object’s constructor name (transformed to use underlines rather than camel case) and the id is set to the
|
415 | object’s constructor name, followed by the value of its `id` property or its `#to_key` or `#id` functions (in that
|
416 | order). Additionally, the second argument (if present) will be used as a prefix for both the id and class attributes.
|
417 |
|
418 | For example:
|
419 |
|
420 | ```haml
|
421 | %div[@user, 'greeting']
|
422 | Hello
|
423 | ```
|
424 |
|
425 | is compiled to:
|
426 |
|
427 | ```html
|
428 | <div class='greeting_user' id='greeting_user_15'>
|
429 | Hello!
|
430 | </div>
|
431 | ```
|
432 |
|
433 | If the user object is for example a Backbone model with the id of 15. If you require that the class be something other
|
434 | than the underscored object’s constructor name, you can implement the `#hamlObjectRef` function on the object:
|
435 |
|
436 | ```haml
|
437 | :coffeescript
|
438 | class User
|
439 | id: 23
|
440 | hamlObjectRef: -> 'custom'
|
441 |
|
442 | %div[new User()]
|
443 | Hello
|
444 | ```
|
445 |
|
446 | is compiled to:
|
447 |
|
448 | ```html
|
449 | <div class='custom' id='custom_23'>
|
450 | Hello!
|
451 | </div>
|
452 | ```
|
453 |
|
454 | ### Directives
|
455 |
|
456 | Haml Coffee supports currently a single directive that extends the Haml syntax.
|
457 |
|
458 | ### Include
|
459 |
|
460 | You can use the `+include` directive to include another template:
|
461 |
|
462 | ```haml
|
463 | %h1 Include
|
464 | +include 'partials/test'
|
465 | ```
|
466 |
|
467 | This will look up the specified template and include it. So if the partial `partials/test` contains
|
468 |
|
469 | ```haml
|
470 | %p Partial content
|
471 | ```
|
472 |
|
473 | The final result will be
|
474 |
|
475 | ```html
|
476 | <h1>Include</h1>
|
477 | <p>Partial content</p>
|
478 | ```
|
479 |
|
480 | ## CoffeeScript support
|
481 |
|
482 | Haml and CoffeeScript are a winning team, both use indention for blocks and are a perfect match for this reason. You can
|
483 | use CoffeeScript instead of Ruby in your Haml tags and the attributes.
|
484 |
|
485 | **It's not recommended to put too much logic into the template.**
|
486 |
|
487 | ### Attributes
|
488 |
|
489 | When you define an attribute value without putting it into quotes (single or double quotes), it's considered to be
|
490 | CoffeeScript code to be run at render time. By default, attributes values from CoffeeScript code are escaped before
|
491 | inserting into the document. You can change this behaviour by setting the appropriate compiler option.
|
492 |
|
493 | HTML style attributes are the most limited and can only assign a simple variable:
|
494 |
|
495 | ```haml
|
496 | %img(src='/images/demo.png' width=@width height=@height alt=alt)
|
497 | ```
|
498 |
|
499 | Both the `@width` and `@height` values must be passed as locals when rendering the template and `alt` must be defined
|
500 | before the `%img` tag.
|
501 |
|
502 | Ruby style tags can be more complex and can call functions:
|
503 |
|
504 | ```haml
|
505 | %header
|
506 | %user{ :class => App.currentUser.get('status') }= App.currentUser.getDisplayName()
|
507 | ```
|
508 |
|
509 | Attribute definitions are also supported in the Ruby 1.9 style:
|
510 |
|
511 | ```haml
|
512 | %header
|
513 | %user{ class: App.currentUser.get('status') }= App.currentUser.getDisplayName()
|
514 | ```
|
515 |
|
516 | More fancy stuff can be done when use interpolation within a double quoted attribute value:
|
517 |
|
518 | ```haml
|
519 | %header
|
520 | %user{ class: "#{ if @user.get('roles').indexOf('admin') is -1 then 'normal' else 'admin' }" }= @user.getDisplayName()
|
521 | ```
|
522 |
|
523 | _But think twice about it before putting such fancy stuff into your template, there are better places like models,
|
524 | views or helpers to put heavy logic into._
|
525 |
|
526 | You can define your attributes over multiple lines and the next line must not be correctly indented, so you can align
|
527 | them properly:
|
528 |
|
529 | ```haml
|
530 | %input#password.hint{ type: 'password', name: 'registration[password]',
|
531 | data: { hint: 'Something very important', align: 'left' } }
|
532 | ```
|
533 |
|
534 | In the above example you also see the usage for generating HTML5 data attributes.
|
535 |
|
536 | ### Running Code
|
537 |
|
538 | You can run any CoffeeScript code in your template:
|
539 |
|
540 | ```haml
|
541 | - for project in @projects
|
542 | - if project.visible
|
543 | .project
|
544 | %h1= project.name
|
545 | %p&= project.description
|
546 | ```
|
547 |
|
548 | There are several supported types to run your code:
|
549 |
|
550 | * Run code without insert anything into the document: `-`
|
551 | * Run code and insert the result into the document: `=`
|
552 |
|
553 | All inserted content from running code is escaped by default. You can change this behaviour by setting the appropriate
|
554 | compiler option.
|
555 |
|
556 | There are three variations to run code and insert its result into the document, two of them to change the escaping style
|
557 | chosen in the compile option:
|
558 |
|
559 | * Run code and do not escape the result: `!=`
|
560 | * Run code and escape the result: `&=`
|
561 | * Preserve whitespace when insert the result: `~`
|
562 |
|
563 | Again, please consult the official [Haml reference](http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html) for more
|
564 | details. Haml Coffee implements the same functionality like Ruby Haml, only for CoffeeScript.
|
565 |
|
566 | #### Multiline code blocks
|
567 |
|
568 | Running code must be placed on a single line and unlike Ruby Haml, you cannot stretch a it over multiple lines by
|
569 | putting a comma at the end.
|
570 |
|
571 | However, you can use multiline endings `|` to stretch your code over multiple lines to some extend:
|
572 |
|
573 | ```Haml
|
574 | - links = { |
|
575 | home: '/', |
|
576 | docs: '/docs', |
|
577 | about: '/about' |
|
578 | } |
|
579 |
|
580 | %ul
|
581 | - for name, link of links
|
582 | %li
|
583 | %a{ href: link }= name
|
584 | ```
|
585 |
|
586 | Please note, that since the line is concatenated before the compilation, you cannot omit the curly braces and the
|
587 | commas in the above example, like you'd do in normal CoffeeScript code. Therefore it's recommended to use the
|
588 | CoffeeScript filter to have real multiline code blocks:
|
589 |
|
590 | ```Haml
|
591 | :coffeescript
|
592 | links =
|
593 | home: '/'
|
594 | docs: '/docs'
|
595 | about: '/about'
|
596 |
|
597 | %ul
|
598 | - for name, link of links
|
599 | %li
|
600 | %a{ href: link }= name
|
601 | ```
|
602 |
|
603 | #### Functions
|
604 |
|
605 | You can also create functions that generate Haml:
|
606 |
|
607 | ```haml
|
608 | - sum = (a, b) ->
|
609 | %div
|
610 | %span= a
|
611 | %span= b
|
612 | %span= a+b
|
613 | = sum(1,2)
|
614 | = sum(3,4)
|
615 | ```
|
616 |
|
617 | or pass generated HTML output through a function for post-processing.
|
618 |
|
619 | ```haml
|
620 | = postProcess ->
|
621 | %a{ href: '/' }
|
622 | ```
|
623 |
|
624 | The content of the `:coffeescript` filter is run when the template is rendered and doesn't output anything into the
|
625 | resulting document. This comes in handy when you have code to run over multiple lines and don't want to prefix each line
|
626 | with `-`:
|
627 |
|
628 | ```haml
|
629 | %body
|
630 | :coffeescript
|
631 | tags = ['CoffeeScript', 'Haml']
|
632 | project = 'Haml Coffee'
|
633 | %h2= project
|
634 | %ul
|
635 | - for tag in tags
|
636 | %li= tag
|
637 | ```
|
638 |
|
639 | ## Compiler options
|
640 |
|
641 | The following section describes all the available compiler options that you can use through the JavaScript API,
|
642 | as Express view option or as argument to the command line utility.
|
643 |
|
644 | The command line arguments may be slightly different. For example instead of passing `--escape-html=false` you have to
|
645 | use the `--disable-html-escaping` argument. You can see a list of all the command line arguments by executing
|
646 | `haml-coffee --help`.
|
647 |
|
648 | ### HTML generation options
|
649 |
|
650 | The HTML options change the way how the generated HTML will look like.
|
651 |
|
652 | #### Output format
|
653 |
|
654 | * Name: 'format'
|
655 | * Type: `String`
|
656 | * Default: `html5`
|
657 |
|
658 | The Haml parser knows different HTML formats to which a given template can be rendered and it must be one of:
|
659 |
|
660 | * xhtml
|
661 | * html4
|
662 | * html5
|
663 |
|
664 | Doctype, self-closing tags and attributes handling depends on this setting. Please consult the official
|
665 | [Haml reference](http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html) for more details.
|
666 |
|
667 | #### Uglify output
|
668 |
|
669 | * Name: `uglify`
|
670 | * Type: `Boolean`
|
671 | * Default: `false`
|
672 |
|
673 | All generated HTML tags are properly indented by default, so the output looks nice. This can be helpful when debugging.
|
674 | You can skip the indention by setting the `uglify` option to false. This save you some bytes and you'll have increased
|
675 | rendering speed.
|
676 |
|
677 | #### HTML escape
|
678 |
|
679 | * Name: `escapeHtml`
|
680 | * Type: `Boolean`
|
681 | * Default: `true`
|
682 |
|
683 | The reserved HTML characters `"`, `'`, `&`, `<` and `>` are converted to their HTML entities by default when they are
|
684 | inserted into the HTML document from evaluated CoffeeScript.
|
685 |
|
686 | You can always change the escaping mode within the template to either force escaping with `&=` or force unescaping with
|
687 | `!=`.
|
688 |
|
689 | #### Attributes escape
|
690 |
|
691 | * Name: `escapeAttributes`
|
692 | * Type: `Boolean`
|
693 | * Default: `true`
|
694 |
|
695 | All HTML attributes that are generated by evaluating CoffeeScript are also escaped by default. You can turn of HTML
|
696 | escaping of the attributes only by setting `escapeAttributes` to false. You can't change this behaviour in the template
|
697 | since there is no Haml markup for this to instruct the compiler to change the escaping mode.
|
698 |
|
699 | #### Clean CoffeeScript values
|
700 |
|
701 | * Name: `cleanValue`
|
702 | * Type: `Boolean`
|
703 | * Default: `true`
|
704 |
|
705 | Every output that is generated from evaluating CoffeeScript code is cleaned before inserting into the document. The
|
706 | default implementation converts `null` or `undefined` values into an empty string and marks real boolean values with a
|
707 | hidden marker character. The hidden marker character is necessary to distinguish between String values like `'true'`,
|
708 | `'false'` and real boolean values `true`, `false` in the markup, so that a boolean attribute conversion can quickly
|
709 | convert these values to the correct HTML5/XHTML/HTML4 representation.
|
710 |
|
711 | #### Preserve whitespace tags
|
712 |
|
713 | * Name: `preserve`
|
714 | * Type: `String`
|
715 | * Default: `textarea,pre`
|
716 |
|
717 | The `preserve` option defines a list of comma separated HTML tags that are whitespace sensitive. Content from these tags
|
718 | must be preserved, so that the indention has no influence on the displayed content. This is simply done by converting
|
719 | the newline characters to their equivalent HTML entity.
|
720 |
|
721 | #### Autoclose tags
|
722 |
|
723 | * Name: `autoclose`
|
724 | * Type: `String`
|
725 | * Default: `meta,img,link,br,hr,input,area,param,col,base`
|
726 |
|
727 | The autoclose option defines a list of tag names that should be automatically closed if they have no content.
|
728 |
|
729 | #### Module loader support
|
730 |
|
731 | * Name: `placement`
|
732 | * Type: `String`
|
733 | * Default: `global`
|
734 |
|
735 | The `placement` option defines where the template function is inserted
|
736 | upon compilation.
|
737 |
|
738 | Possible values are:
|
739 |
|
740 | * `global` <br />
|
741 | Inserts the optionally namespaced template function into `window.HAML`.
|
742 |
|
743 | * 'standalone' <br />
|
744 | Returns the template function without wrapping it
|
745 |
|
746 | * `amd` <br />
|
747 | Wraps the template function into a `define()` statement to allow async
|
748 | loading via AMD.
|
749 |
|
750 | See AMD support for more information.
|
751 |
|
752 | ### Module dependencies
|
753 |
|
754 | * Name: `dependencies`
|
755 | * Type: `Object`
|
756 | * Default: `{ hc: 'hamlcoffee' }`
|
757 |
|
758 | The `dependencies` option allows you to define the modules that must be required for the AMD template `define` function.
|
759 | The object key will be the function parameter name of the module the object value defines. See AMD support for more
|
760 | information.
|
761 |
|
762 | ### Data attribute hyphenation
|
763 |
|
764 | * Name: `hyphenateDataAttrs`
|
765 | * Type: `Boolean`
|
766 | * Default: `true`
|
767 |
|
768 | Convert underscores to hyphens for data attribute keys, see
|
769 | [the Ruby Haml reference](http://haml.info/docs/yardoc/file.REFERENCE.html#html5_custom_data_attributes).
|
770 |
|
771 | ### Custom helper function options
|
772 |
|
773 | Haml Coffee provides helper functions for HTML escaping, value cleaning and whitespace preservation, which must be
|
774 | available at render time. By default every generated template function is self-contained and includes all of the helper
|
775 | functions.
|
776 |
|
777 | However you can change the reference to each helper function by providing the appropriate compiler option and there
|
778 | are good reasons to do so:
|
779 |
|
780 | * You want to reduce the template size and provide all the helpers from a central place.
|
781 | * You want to customize a helper function to better fit your needs.
|
782 |
|
783 | To change these functions, simply assign the new function name to one of the following options:
|
784 |
|
785 | * `customHtmlEscape`: Escape the reserved HTML characters into their equivalent HTML entity.
|
786 | * `customPreserve`: Converting newlines into their HTML entity.
|
787 | * `customFindAndPreserve`: Find whitespace sensitive tags and preserve their content.
|
788 | * `customCleanValue`: Clean the value that is returned after evaluating some inline CoffeeScript.
|
789 | * `customSurround`: Surrounds a block of Haml code with strings, with no whitespace in between.
|
790 | * `customSucceed`: Appends a string to the end of a Haml block, with no whitespace between.
|
791 | * `customPrecede`: Prepends a string to the beginning of a Haml block, with no whitespace between.
|
792 | * `customReference`: Creates the Haml object reference.
|
793 |
|
794 | The `customSurround`, `customSucceed` and `customPrecede` are bound to the template context.
|
795 |
|
796 | You can find a default implementation for all these helper functions in
|
797 | [Haml Coffee Assets](https://github.com/netzpirat/haml_coffee_assets/blob/master/vendor/assets/javascripts/hamlcoffee.js.coffee.erb).
|
798 |
|
799 | ## AMD support
|
800 |
|
801 | * Global dependencies
|
802 | * Trivial dependency detection
|
803 |
|
804 | Haml Coffee has built in AMD support by setting the `placement` option to `amd`. This will generate a module definition
|
805 | for the JavaScript template. The `dependencies` options can be used to provide a mapping of module names to parameters.
|
806 | To illustrate this, the default value will result in the following module declaration:
|
807 |
|
808 | ```CoffeeScript
|
809 | define ['hamlcoffee'], (hc) ->
|
810 | ```
|
811 |
|
812 | When the template contains a require call in the form of
|
813 |
|
814 | ```CoffeeScript
|
815 | - require 'module'
|
816 | - require 'deep/nested/other'
|
817 | ```
|
818 |
|
819 | it will be added to the module definition list
|
820 |
|
821 | ```CoffeeScript
|
822 | define ['hamlcoffee', 'module', 'deep/nested/other'], (hc, module, other) ->
|
823 | ```
|
824 |
|
825 | allowing you to render a partial template:
|
826 |
|
827 | ```CoffeeScript
|
828 | != module()
|
829 | != other()
|
830 | ```
|
831 |
|
832 | Of course the require call can have different quotes or parenthesises, allowing you to directly require and render:
|
833 |
|
834 | ```CoffeeScript
|
835 | != require("another/other")()
|
836 | ```
|
837 |
|
838 | ## Development information
|
839 |
|
840 | Haml Coffee uses [Grunt](http://gruntjs.com/) for development, which you can install with
|
841 | [NPM](https://npmjs.org/):
|
842 |
|
843 | ```bash
|
844 | $ npm install
|
845 | ```
|
846 |
|
847 | and run Grunt to automatically run the Jasmine specs on file modification:
|
848 |
|
849 | ```bash
|
850 | $ grunt
|
851 | ```
|
852 |
|
853 | ## Changelog
|
854 |
|
855 | Feel free to take a look at the crispy [changelog](https://github.com/netzpirat/haml-coffee/blob/master/CHANGELOG.md)
|
856 | instead of crawling through the commit history.
|
857 |
|
858 | ## Related projects
|
859 |
|
860 | Haml Coffee in the Rails asset pipeline:
|
861 |
|
862 | * [haml-coffee-assets](https://github.com/netzpirat/haml_coffee_assets)
|
863 |
|
864 | ## Authors
|
865 |
|
866 | * [Michael Kessler](https://github.com/netzpirat) ([@netzpirat](http://twitter.com/#!/netzpirat), [mksoft.ch](https://mksoft.ch))
|
867 | * [Sebastion Deutsch](https://github.com/sebastiandeutsch) ([@sippndipp](http://twitter.com/#!/sippndipp), [9elements](http://9elements.com))
|
868 | * [Jan Varwig](https://github.com/janv) ([@agento](http://twitter.com/#!/agento), [9elements](http://9elements.com))
|
869 |
|
870 | ## Contributors
|
871 |
|
872 | See all contributors on [the contributor page](https://github.com/netzpirat/haml-coffee/contributors).
|
873 |
|
874 | ## License
|
875 |
|
876 | (The MIT License)
|
877 |
|
878 | Copyright (c) 2011 9elements, 2011-2013 Michael Kessler
|
879 |
|
880 | Permission is hereby granted, free of charge, to any person obtaining
|
881 | a copy of this software and associated documentation files (the
|
882 | 'Software'), to deal in the Software without restriction, including
|
883 | without limitation the rights to use, copy, modify, merge, publish,
|
884 | distribute, sublicense, and/or sell copies of the Software, and to
|
885 | permit persons to whom the Software is furnished to do so, subject to
|
886 | the following conditions:
|
887 |
|
888 | The above copyright notice and this permission notice shall be
|
889 | included in all copies or substantial portions of the Software.
|
890 |
|
891 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
892 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
893 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
894 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
895 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
896 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
897 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|