A fast HTML5 view engine that renders using virtual-dom in the browser and strings in NodeJS.
{{name.toUpperCase}}'s image gallery
Breezy uses custom HTML elements and attributes with Expressions as placeholders to render HTML5 based templates. For example, the following HTML template:
{{site.title}} {{name.toUpperCase}}'s image gallery
Rendered with the following data
var data = site: title: 'My page' name: 'david' { return thisimages === 0; } { return thisimages === thisimageslength - 1; } images: src: 'http://placehold.it/350x150' description: 'The first image' src: 'http://placehold.it/350x150' description: 'Another image' src: 'http://placehold.it/350x150' description: 'The last image' ;
Will result in:
My pageDAVID's image gallery
{{name.toUpperCase}}'s image gallery
Breezy can be used with NodeJS where it outputs a plain string or in the browser where a virtual-dom is created which is then used to quickly update only the parts of the DOM that actually changed.
In the browser you will also get automatically updating templates as your data changes when Polymer's ObserveJS is included.
{{name.toUpperCase}}'s image gallery
After
npm install breezy
Lets assume we are using the following data:
var data = site: title: 'My page' name: 'david' { return thisimages === 0; } { return thisimages === thisimageslength - 1; } images: src: 'http://placehold.it/350x150' description: 'The first image' src: 'http://placehold.it/350x150' description: 'Another image' src: 'http://placehold.it/350x150' description: 'The last image' ;
To use Breezy programmatically in Node just require it and call .render(content, data)
or .renderFile(path, data)
:
var breezy = ;var html = breezy;console; // Or compiled with a template stringvar renderer = breezy; console;
It can also be loaded as a view engine in your Express app:
var express = ;var app = ; app;app;app; app;
{{name.toUpperCase}}'s image gallery
The easiest way to get Breezy into the browser is via the Bower package:
bower install breezy
You can also download the distributable from the latest release. Then include it in your page:
dist/breezy.js
can also be loaded as an AMD and CommonJS module. If included without a module loader, the global variable breezy
will be available.
Breezy has no hard dependencies but if you want your templates to automatically update when the displayed data change, you will also need to include ObserveJS:
bower install observe-js
And in the page as well:
Next we have to supply the template and data that we want to render to breezy.render
. You can use a string (for example the .innerHTML
content of a <script type="text/html>
tag) or create your templates in-page and pass the DOM element that you want to make live. All together it looks like this:
My image gallery {{name.toUpperCase}}'s image gallery {{description}}:
If you don't include ObserveJS you will have to call the renderer returned by breezy.render
manually to update the view. If used properly this will probably be faster than observing objects. The end of the script then looks like:
var renderer = breezy; var counter = 0;// Lets make something happen;
Note: You can retrieve the context data from any DOM node using breezy.context(node)
. With the above example:
var node = document0;var image = breezy; console;// -> { src: 'http://placehold.it/350x150', description: 'The first image' }
This makes it easy to get and modify the data in event listeners etc.
Expressions
Breezy uses expressions as placeholders that will be substituted with the value when rendered. Expression are very similar to JavaScript property lookups and function calls with the tenary operator. A full expression looks like:
path[.to.method] [args... ] [? truthy] [: falsy]
path
is either a direct or dot-separated nested property lookup. args
can be any number of (whitespace separated) parameters if the result of the path lookup is a function. Each parameter can either be another path or a sinlge- or doublequoted string. The optional truthy and falsy block can be used to change the return value to another value or string.
Examples:
- Look up the
name
property:name
- Look up
site
and get thetitle
:site.title
- Get
name
and call thetoUpperCase
string method:name.toUpperCase
- Call the
helpers.equal
method to check the name against a string:helpers.equal name 'David'
- Call
helpers.equal
method and returnYes
if it matches (null
otherwise):helpers.equal name 'David' ? 'Yes'
- Call
helpers.equal
method and returnNo
if it does not match (null
otherwise):helpers.equal name 'David' : 'No'
- Call
helpers.equal
method and returnYes
if andNo
if it does not match:helpers.equal name 'David' ? 'Yes' : 'No'
helpers.equal
simply looks like:
helpers: { return first === second; }
Expressions can be used in Attributes or any other text when wrapped with double curly braces {{}}
:
Hi {{name.toUpperCase}} how are you?
Note: Dynamically adding attributes like <img {{helpers.equal name 'David' ? 'alt="This is David"'}}>
is currently not supported. This can almost always be done in a more HTML-y way, anyway, for example using a custom attribute.
Context
Normally properties are looked up as you would expect, for example
gets the attributes from the second image in the array. However, if the property is not found in the current context, Breezy will try to look it up at the parent and so on until we are at the root level (the data object you passed to the renderer). What this means is that for
{{site.title}}
where the current context is the image we are currently iterating over, site.title
is not a property of the current image. We will find it however one level higher at the root element.
There are also three special properties in any context:
$this
- Refers to the current context data (see the{{first $this ? 'first'}}
example)$key
- Is the property name the current context came from (e.g. the index of the image in the array)$path
- The full path of the context. For exampleimages.0.src
If you want to prevent lookups up the context you can prefix the path with $this
which will make something like
{{$this.site.title}}
just output an empty string.
Attributes
Breezy implements a small number of custom HTML5 attributes that can be used to show/hide elements, iterate over arrays or switch the context.
for-each
Iterates over a list and renders the tag for each element.
Important: Currently for-each
only supports property lookups so you can not use the result of an expression.
show-if/show-if-not
Show the tag if an expression is truthy or falsy.
No imagesThere are {{images.length}} images.
If show-if
or show-if-not
does not currently apply to the element, it will be replaced with an invisible element (display: none;
) of the same type (we can't just skip it because missing elements will confuse the virtual-DOM). With images.length === 0
the example would render like this:
No images
with
Switches the within this tag to the given property.
Important: Currently with
only supports property lookups so you can not use the result of an expression.
API
context
In the Browser, breezy.context(node)
returns the context data a DOM node has been rendered with. This is a great way to retrieve the data you want to modify.
var node = document0;var image = breezy; console;// -> { src: 'http://placehold.it/350x150', description: 'The first image' }imagesrc = 'http://placehold.it/350x150';// -> view will update
render
breezy.render(content, data)
will render the given content. content
can be an HTML template string and in the browser also a DOM Node which will then be replaced with the rendered content. render
will return a string in NodeJS and in the Browser either a DocumentFragment
(if content
was a string) or a renderer function (if content
was a DOM node).
renderFile
breezy.render(path, file, [callback])
renders a given file calling an optional callback. This is mainly for compatibility with Express template engines. If you want to create templates with an extension other than .breezy
you can use this as the view engine:
var express = ;var breezy = ;var app = ; app;app;app;
compile
breezy.compile(content, options)
compiles a given template and returns a renderer(data)
function. content
can either be an HTML string or a DOM node. In Node, only strings are accepted and the renderer function will always return a string.
In the browser, if content
is a string, a live-updating DocumentFragment will be returned the first time you call the renderer with data. Subsequent calls to that renderer
are only possible with the same data or without any arguments and will update that DocumentFragment. If content
is a DOM node the string representation of that node (outerHTML
) will be used as the template and the node will be replaced with a live updating version.
var renderer = breezy; var data = message: 'World' ;var result = ;// `<div>Hello World</div> or DocumentFragment with div element documentbody; datamessage = 'Welt'; // In the browser this will update the DOM;// In Node, render it again;
Examples
The examples folder contains the Breezy TodoMVC implementation for both, the browser and Node with Express. To run them install Express and the TodoMVC common dependencies. In /examples
run:
npm install express cd todomvc bower install cd ..
You can run the Express application with
node app.js
Then visit http://localhost:3000/ to see the client side TodoMVC application with the full functionality.
At http://localhost:3000/all the same template will be used but in Node generating some random Todos. Currently the server side example can only filter Todos (/active, /complete) but it should demonstrate how to use the shared data model.
The application logic used on both sides is in /public/js/view-model.js
. The file either exposes window.ViewModel
on the Browser or exports the module for Node.