Skip to content

Latest commit

 

History

History
200 lines (140 loc) · 5.7 KB

README.md

File metadata and controls

200 lines (140 loc) · 5.7 KB
Raw

Bujagali

A template system in JavaScript (kind of). Developed and currently in production at Rdio.

Overview

Bujagali is a flexible template system that is a thin layer on top of JavaScript which makes it easier to write HTML (or any templated text) using JavaScript. The syntax is modeled off of the Django templating system, but the behavior is substantially different.

Bujagali is really fast, really flexible, and really hard to use. It's written for people who know JavaScript well and is probably completely unusable by most designers.

The basic principle is to compile templates on the server-side to JS functions, then load them lazily on the client to render JSON data.

This system is designed to work in either server-side or client-side JavaScript environments. It depends on the excellent underscore library, so you can reference _ from anywhere in your templates.

There are 3 aspects to the system that require documentation.

  • Writing templates
  • Converting templates to JavaScript
  • Rendering templates

Writing Templates

Every template is provided with a context variable, called ctx, that contains the object the template was rendered with.

###Special Tags

There are two special tags that must come at the top of your templates. These are used to reuse code found in other templates, and examples of their use is given in the 'Regular Tags' section below

#import <template path> This ensures that a template is rendered before rendering your template. This is used to make sure that templates containing macros (described below) have been loaded and are those macros are available to use by the time your template is rendered. Imports must be the first thing in a template.

#extends <template path> This tag includes the template you specify in the current template. These must occur above all other markup, but after #import tags. This is used to provide template inheritance, where the template being extended will later call into the current template (see below for an example).

###Regular Tags

{{ <data> }}

Output whatever is returned, usually a variable or the result of some operation.

Example:

<h1>Name: {{ ctx.myName }}</h1>
<h2>Address: {{ self.formatAddress(ctx.myName) }}</h2>
<h3>Birth year: {{ 2010 - ctx.age }}</h3>

{% <javascript> %}

Execute the enclosed JavaScript, don't alter the markup in any way.

Example:

{% if (ctx.fruits && ctx.fruits.length) {
    _.each(ctx.fruits, function(fruit) { %}
        <li>{{ fruit }}</li>
    {% });
} %}

{$ <block name> $}

This is one part of how inheritance is done. This tag will define a block for a subtemplate to override. This allows you to define where markup from a template that extends the current template will be placed. This will call a function of the name specified and output the result into the parent template.

Example:

Master template

<html>
    <head>
        <title>{{ ctx.title }}</title>
        {$ scripts $}
        {$ css $}
    </head>
    <body>
        {$ content $}
    </body>
</html>

Subtemplate

#extends /relative/path/to/master/template

{% function scripts() { %}
    <script type="text/javascript" src="/myprogram.js"></script>
{% }
function css() { %}
    <link type="text/css" rel="stylesheet" href="/mystyle.css" />
{% }
function content() { %}
    Hello World!
{% } %}

{= <macro name>(<macro arguments>) <macro content> =}

This allows you to extend the template system and reuse pieces of templates in other places.

Example:

In some template:

{= render_address(address)
    <div class="address">
        <div class="street">{{ address.street }}</div>
        {% if (address.aptNum) { %}
            <div class="num">{{ address.aptNum }}</div>
        {% } %}
        <div class="line2">
            {{ address.city }}, {{ address.state }} {{ address.zip }}
        </div>
    </div>
=}

Then in some other template:

#import /relative/path/to/first/template

<div class="address-list">
    {% _.each(ctx.addresses, function(address) { %}
        {{ self.render_address(address) }}
    {% } %}
</div>

{# <comment> #}

Everything between these tags will be ignored and will not end up in the compiled template.

###Advanced Concepts

self

self refers to the current instance of the template being rendered. You almost always want to call macros and other functions provided by the templating system with self. For instance, escape is a function available to all templates in Bujagali.

<h1>Name: {{ self.escape(ctx.name) }}</h1>

Macros defined by other templates are also available through self (so long as you #import them first)

#import /myheadertemplate.html

<div class="header">{{ self.render_header(ctx) }}</div>

emit

emit is a function that is available to all templates. It is what is called by the moustache tag ({{ }}). This can be useful for making some markup less confusing.

Instead of

The car is{% if (ctx.sex == 'female') { %} hers.{% } else { %} his.{% } %}

You could do

The car is{% ctx.sex == 'female' ? emit(' hers.') : emit(' his.'); %}

This example is a little contrived as you could also do

The car is{{ ctx.sex == 'female' ? ' hers.' : ' his.' }}

But it does come in useful sometimes, I swear.

###Provided functions See the API docs for what functions are available to you from your templates and how to extend that set.

Converting Templates to JavaScript

Documentation in development...

Rendering Templates

Documentation in development...