A JavaScript templating plugin for jQuery. Bumble provides an embedded syntax, similar to PHP or ASP, letting you add intelligent functionality directly within your HTML. And because it's JavaScript, you don't need to execute your templates on a server, making Bumble perfect for lightweight, responsive AJAX apps.
demo
downloads
overview
Bumble templates look like regular HTML code, with interspersed JavaScript.
Hello, <%= "World" %>!
<% if (someStatementIsTrue): %>
<b>Templates are cool!</b>
<% end %>
The templates are stored in their own files, and executed on demand within the JavaScript of your app:
$('#my-container').bumble('path/to/template.jhtml',
{ arg1: 'foo', arg2: 'bar' });
In the example above, the specified template will be downloaded and executed. The supplied arguments will by imported into the template's scope, as variables. The resulting HTML will be injected into the element that matches the jQuery selector.
basic syntax
Bumble supports dynamic includes, asynchronous and synchronous modes, and a few other nifty features. But at its heart, it's just a JavaScript preprocessor; anything you can write in JavaScript, you can write in Bumble.
Within a Bumble template, everything contained inside code brackets (<% and
%>) is evaluated as JavaScript. Everything outside those brackets is evaluated as
plain text and HTML
An included function, echo, provides a way for code blocks to output dynamic text
inline with the plain text outside those blocks.
<p>This is plain text and HTML</p>
<%
echo("But these ");
echo("are JavaScript " + "statements");
%>
encoding content
Often you may need to echo content that includes special XML/HTML characters,
such as left- or right-angle brackets (< and >). Bumble includes a function,
encode to easily format such content for display within HTML.
<%= encode("These <i>tags</i> should be seen as text.") %>
The previous example will output the following in plain text:
These <i>tags</i> should be seen as text.
not:
These tags should be seen as text.
alternative syntax
Much like in ASP or PHP, a shortcut tag is provided for echoing simple statements.
<%= 4 + 5 %>
The previous example is equivalent to this:
<% echo(encode(4 + 5)) %>
During execution of a template, blocks of plain text are evaluated in the context of the code blocks surrounding them. So you can wrap your HTML in loops and conditional statements.
<% for (var i = 0; i < 10; i++) { %>
<li>Item <%= i %></li>
<% } %>
Bumble also offers alternate syntax for loops and control structures, much like PHP. Curly
brackets can sometimes be difficult to follow when mixed into a large
block of HTML. Bumble allows opening brackets to be replaced by colons, as long as they are the
final character of a code block. And it allows closing brackets to be replaced by the word
end, as long as it is the only statement contained within a code block.
The previous looping template could also have been written like so:
<% for (var i = 0; i < 10; i++): %>
<li>Item <%= i %></li>
<% end %>
includes
Sometimes it's desireable to include the contents of one Bumble template within another.
This is easy to do using the run function that's available within Bumble
templates.
<% run('../path/to/template.jhtml', { arg1: 'foo' }) %>
The path to the included template is relative to the path of the current template, not the URL of the calling web page.
By necessity, these included templates are downloaded and executed synchronously. If
there are download delays, however, this can cause a visitor's browser to become unresponsive,
in the same manner as evaluating a long script. In order to avoid this problem, it's recommended
that you cache your included templates using the included preload directive.
<%@ preload="../path/to/template.jhtml" %>
Note the @ symbol immediately after the opening code bracket. It indicates
that this block is a pre-processor directive, and will not be evaluated as JavaScript.
Including this directive anywhere in your template (even at the very end) will ensure
that the specified template is preloaded and cached at the same time that the calling
template is. If your template is loaded asynchronously (which is the default behavior) using the
.bumble method in jQuery, all preloaded templates will also be loaded
asynchronously.
options
The optional options parameter, of the .bumble method
provides the following settings:
advanced
It's possible to use Bumble without injecting the results directly into the DOM. You can execute the contents of a Bumble template, and access the resulting HTML directly.