Browser Usage

toffee is a command-line program that compiles your .toffee templates into .js files you can use in the browser. For your convenience, there are both simple and advanced ways to use it. Most of the advanced features center around performance, while still allowing templates to include each other via the partial command.

Prerequisite

If you haven't yet, install the toffee program:

> npm install -g toffee

Getting help

At any time, this will get you basic help:

> toffee --help

Simple Option #1 - Compile everything into one .js file

> toffee some_dir -o my_templates.js

This recursively hunts for all .toffee files in some_dir, compiling all of them into one self-contained my_templates.js file. That file is a standalone engine. Including it in a page exposes all your templates.

Let's say you want to render <some_dir>/bleah/foo.toffee.

<script src="my_templates.js"></script>
<script>
  var some_html = toffee.templates["/bleah/foo.toffee"].render(some_vars);
</script>

Note how templates are referred to relative to the base (compilation root) path. This is important, as it allows partials with relative paths to work.

Simple Option #2 - Compile separate .js files

If you call toffee with -d , it will compile your input file(s) into individual .js files, mirroring the directory structure of the input. See:

> toffee some_dir -d output_templates

Usage is almost identical, except you then have to include the templates you want in the browser. If foo.toffee uses bar.toffee, make sure to include that too.

<script src="output_templates/bleah/foo.js"></script>
<script src="output_templates/bleah/bar.js"></script>
<script>
  var some_html = toffee.templates["/bleah/foo.toffee"].render(some_vars);
</script>

Advanced Stuff

Excluding headers to shrink file size

In both of the above examples, those js files have ~2kB of boilerplate JS that's part of the toffee engine. You can exclude those headers with -n

> toffee some_dir -n -d output_templates

However, you then need to provide the toffee.js file yourself, which is provided in this repository.

<script src="toffee.js"></script>
<script src="output_templates/bleah/foo.js"></script>
<script src="output_templates/bleah/bar.js"></script>
<script>
  var some_html = toffee.templates["/bleah/foo.toffee"].render(some_vars);
</script>

Minimizing JS with uglifyJS

Passing -m will make your .js files much smaller:

> toffee some_dir -m -d output_templates

This comes at two costs, however: compilation takes longer, and debugging your templates is much harder. It's advised to save this for production.

Outputting CoffeeScript instead of JS

Pass -c to output .coffee files instead.

> toffee some_dir -c -o coffee_out/

Outputting to stdout

Pass -p to print to standard output instead of outputting to a file. It can be stimulating to pair this with -c mentioned above, to see what CoffeeScript toffee generates.

> toffee some_dir -p -c

Specifying a bundle path to avoid collisions and allow cross-compilation includes/partials

If you call toffee 2 times from the command line to compile 2 different files or directories, you should consider passing a bundle path, so that (1) a template in dir1 can include a template in dir2, and (2) you can avoid a problem if dir1/foo.toffee and dir2/foo.toffee both exist.

> toffee democrats/   -b political_templates -o democrats.js
> toffee republicans/ -b political_templates -o republicans.js

This places templates inside toffee.templates["/political_templates/...

For example:

<script src="democrats.js"></script>
<script src="republicans.js"></script>
<script>
  var output = toffee.templates["/political_templates/democrats/foo/bar.toffee"].render(some_vars);
</script>

This allows templates in democrats.js to refer to templates in republicans.js, since they now have relative paths to each other.

If you're using templates both server and browser-side, your goal with a bundle path should be to keep relative paths the same as on the server. If you follow this convention, partials will be exactly the same in the browser and on the server, and your templates will work everywhere.

For example, if you have a /templates/ directory, and you want to compile /templates/components/ and /templates/foo/bar/ separately into bundles, you should do this:

> toffee templates/components/  -b templates/ -o components.js
> toffee templates/foo/bar/ -b templates/foo/ -o bar.js

This generates two files, components.js and bar.js. Including them both will define every template in the appropriate place:

toffee.templates["/templates/components/..."]
toffee.templates["/templates/foo/bar/..."]

See Also

• Wiki Home
• Readme.md