Skip to content

Commit

Permalink
Update the docs to reflect the new api after the rewrite.
Browse files Browse the repository at this point in the history
  • Loading branch information
@creationix
creationix committed Jan 9, 2010
1 parent 728bb61 commit f5c45fd
Showing 1 changed file with 77 additions and 54 deletions.
131 changes: 77 additions & 54 deletions README.markdown
View file
Original file line number Diff line number Diff line change
@@ -1,109 +1,132 @@
# haml-js - Server side templating language for JavaScript

What's left in this project is the server-side haml language. It has much of the same functionality as the traditional haml. Syntax based on [haml][] from the ruby world.

## NOTE, Project was split

If you're looking for the old haml-js (It was a jQuery plugin that made dom-building easy using a haml-like syntax), it's now renamed to [jquery-haml][]
Ever wanted to use the excellent HAML syntax on a javascript project? Me too, so I made one!. This has most of the same functionality as the traditional [haml][].

## About the language

Here is the first example from the [haml][] site converted to haml-js:
Here is the first example(with a little extra added) from the [haml][] site converted to haml-js:

**haml-js**

.profile
.left.column
#date= print_date()
#address= curent_user.address
.right.column
#email= current_user.email
#bio= current_user.bio
!!! XML
!!! strict
%html{ xmlns: "http://www.w3.org/1999/xhtml" }
%head
%title Sample haml template
%body
.profile
.left.column
#date= print_date()
#address= current_user.address
.right.column
#email= current_user.email
#bio= current_user.bio

**html**

<div class="profile">
<div class="left column">
<div id="date">Thursday, October 8, 2009</div>
<div id="address">Richardson, TX</div>
</div>
<div class="right column">
<div id="email">tim@creationix.com</div>
<div id="bio">Experienced software professional...</div>
</div>
</div>
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Sample haml template
</title></head><body><div class="profile"><div class="left column"><div id="date">January 1, 2009
</div><div id="address">Richardson, TX
</div></div><div class="right column"><div id="email">tim@creationix.com
</div><div id="bio">Experienced software professional...
</div></div></div></body></html>

Note that this works almost the same as ruby's [haml][].
Note that this works almost the same as ruby's [haml][], but doesn't pretty print the html. This would greatly slow down and complicate the code. If you really want pretty printed html, then I suggest writing one using the xml parser library and process the resulting html..

## API

There are three exported functions in the haml.js library. They are:
There are four exported functions in the haml.js library. They are:

### parse(text) -> json data
### Haml.compile(text) -> JavaScript compiled template

Parse takes a block of haml template and parses it into an s-expression like json construct.
Given a haml template as raw text, this compiles it to a javascript expression
that can later be eval'ed to get the final HTML.

The following input:

#home
= title
%ul.menu
%li Go Home
%li Go Back

Produces the following JSON output
Produces the following JavaScript expression:

"<div id=\"home\">" +
title +
"\n" +
"<ul class=\"menu\">" +
"<li>" +
"Go Home\n" +
"</li>" +
"<li>" +
"Go Back\n" +
"</li>" +
"</ul>" +
"</div>"

### Haml.optimize(js) -> optimized JavaScript expression

Takes the output of compile and optimizes it to run faster with the tradeoff of longer compile time. This is useful for framework developers wanting to use haml in their framework and want to cache the compiled templates for performance.

[{"tag":"div","id":"home"},
[{"tag":"ul","class":"menu"},
[{"tag":"li"},"Go Home"],
[{"tag":"li"},"Go Back"]
]
]
With the previous input it outputs:

### to_html(json) -> html text
"<div id=\"home\">" +
title +
"\n<ul class=\"menu\"><li>Go Home\n</li><li>Go Back\n</li></ul></div>"

This takes the json data from the parse step and converts it into html ready for a browser
Notice how congruent static strings are merged into a single string literal when possible.

The input from the previous example outputs this:
### Haml.execute(js, context, locals) -> Executes a compiles template

<div id="home">
<ul class="menu">
<li>Go Home</li>
<li>Go Back</li>
</ul>
</div>
Context is the value of `this` in the template, and locals is a hash of local variables.

### render(text, options) -> html text
### Haml.render(text, options) -> html text

This is a convenience function that parses and converts to html in one shot.
This is a convenience function that compiles and executes to html in one shot. Most casual users will want to use this function exclusively.

The `text` parameter is the haml source already read from a file.

The two recognized `options` are:
The three recognized `options` are:

- **context**: This is the `this` context within the haml template.
- **locals**: This is an object that's used in the `with` scope. Basically it creates local variables and function accessible to the haml template.

- **optimize**: This is a flag to tell the compiler to use the extra optimizations.

See [test.js][] for an example usage of Haml.render

## Plugins

There are plugins in the parser for things like inline script tags, css blocks, and experimental support for if statements and for loops.
There are plugins in the parser for things like inline script tags, css blocks, and support for if statements and for loops.

### If statements
### `:if` statements

`If` statements evaluate a condition for truthiness (as opposed to a strict comparison to `true`) and includes the content inside the block if it's truthy.
`if` statements evaluate a condition for truthiness (as opposed to a strict comparison to `true`) and includes the content inside the block if it's truthy.

:if{ condition : todolist.length > 20 }
:if todolist.length > 20
%p Oh my, you are a busy fellow!

### Foreach loops
### `:each` loops

`:each` loops allow you to loop over a collection including a block of content once for each item. You need to what variable to pull the data from and where to put the index and value. The index variable is optional and defaults to `__key__`.

`Foreach` loops allow you to loop over a collection including a block of content once for each item. You need to specify the array you are looping over (`array`) and the name of the variable the item should be put into (`value`).
Here is an example over a simple array.

%ul.todolist
:foreach{ array : todolist, value : "item" }
:each item in todolist
%li= item.description

You can loop over the keys and values of objects too (Note the inner `:each` loop)

:each item in data
:if item.age < 100
%dl
:each name, value in item
%dt&= name
%dd&= value

## Get Involved

If you want to use this project and something is missing then send me a message. I'm very busy and have several open source projects I manage. I'll contribute to this project as I have time, but if there is more interest for some particular aspect, I'll work on it a lot faster. Also you're welcome to fork this project and send me patches/pull-requests.
Expand Down

0 comments on commit f5c45fd

Please sign in to comment.