The Chicago Boss API is mostly stable, but still might change before 1.0.

Chicago Boss liked Django's templating language so much, he decided to steal it. Template files go in your project's src/view/ folder (in subdirectories that correspond to the controller name), and will have access to the variables you pass from your Controller. The template file associated with the function foo_controller:bar will be src/view/foo/bar.html. (Template filenames can also use .txt, .dtl and .js file extensions.)

Note: if you use the the extends tag, the file path should be relative to your project's src/view/ directory.

Chicago Boss has support for the most common features of the Django Template Language, so many existing Django templates should work out of the box. Your templates will be compiled down to Erlang BEAM code using ErlyDTL to give you the fastest Erlang templates this side of Stockholm.

100% of Django filters are supported. The only unsupported tag is csrf_token.

Custom tags

If you use repeated logic or template snippets, you can put helper templates into your project's src/view/lib/tag_html directory. The variables appearing in helper templates must be supplied by the caller. For example, if you have a file called "src/view/lib/tag_html/my_custom_tag.html" which uses a variable called "foo", you can invoke it from other templates like:

{% my_custom_tag foo="bar" %}

String literals or variables may be passed as arguments to custom tags.

Another option for factoring out repeated logic is to use ErlyDTL's "include" tag. The difference between using an "include" tag and custom tags is that "include" will have access to all variables currently in the caller's scope, whereas custom tags only have access to the variables explicitly passed in. (In addition, custom tags are compiled only once for the entire project, but included files are compiled for each template that includes it.)

Helper modules for custom tags and filters

For more complicated processing, you can create helper modules. Tag helper modules reside in src/view/lib/tag_modules, and export functions which take in a proplist of variables and return rendered HTML. Filter helper modules reside in src/view/lib/filter_modules, and export functions which take in a binary string and return a filter iolist. See those directories in your project for examples.

Configuring ErlyDTL

By default, ErlyDTL escapes HTML in values that are passed in template variables. This behaviour is configurable in CB, by setting the value of template_auto_escape to either true or false in boss.config.

Implicit variables

The following variables are automatically passed to your views without you doing any work:

Experimental Template Languages

Two other template languages are supported on an experimental basis: Jade (provided by jaderl) and embedded Elixir.

Jade

To use Jade, simply create templates with extension ".jade".

Embedded Elixir

To use embedded Elixir, create templates with extension ".eex", and prefix your variables with @.

Example Elixir:

A message for you: <%= @message %>

<%# This is a comment %>

<%= Enum.map @puppies, fn(puppy) -> %>
Name: <%= puppy.name %>
<% end %>

For more information on embedded Elixir, see the EEx docs.