Handlebind NPM

Handlebind.js

Handlebind.js is an extension of the Handlebars templating language that implements Knockout.js style data-binding.

Under Construction

Installing

Download the most recent version of Handlebind from GitHub and add it to your webpage along with its dependencies:

Underscore.js for collections and utilities,
Humble.js for building a class hierarchy,
jQuery (> 1.6) for DOM manipulation and event handling,
and of course Handlebars.js for template rendering

Getting Started

Handlebind uses handlebars templates to define its Views. A handlebars template looks like regular HTML with embedded {{ handlebars }} expressions.

<div class="entry">
	<h1>{{text title}}</h1>
	<div class="body">
		{{html body}}
	</div>
</div>

You can make the template available in the browser by including it in a <script> tag.

<script id="entry-template" type="text/x-handlebars-template">
	template content...
</script>

To render the view, instantiate a corresponding View Model and bind it to the template by with a View object. Append the bound view to the DOM using an element or CSS selector.

var entryViewModel = {
	title: 'These are a few of my favorite things...',
	body: '<ul><li>Raindrops on roses</li><li>whiskers on kittens</li><ul>'
};
var entryView = new Handlebind.View('entry-template', entryViewModel);
entryView.appendTo('#entry-container');

Usage

Handlebind.js is largely a re-implementation of the DOM based Knockout.js library created by Steve Sanderson.

Helpers - Text {{text}} - Unescaped HTML {{html}} - DOM Element Attributes {{attrs}} - {{class}} - DOM Element Properties {{props}} - {{enabled}} - {{disabled}} - Event Handling {{events}} - Value Binding {{value}} - Checkbox Binding {{checked}} - Focus Binding {{hasFocus}} - Selection Binding {{options}} - {{action}} - Using Templates {{template}}
Block Helpers - Context Definition {{#with}} - Iterative Rendering {{#each}} - Conditional Rendering {{#if}} - {{#unless}} - Deactivating Binding {{#unbound}}
Path Expressions

Helpers

The {{text}} helper

The {{text}} helper is used to display a value as text.

var template = "<p>{{text lastName}}, {{text firstName}}</p>";
var view = new Handlebind.View(template, { firstName: 'John', lastName: 'Smith' });
view.appendTo('#container');

results in

<p>Smith, John</p>

The text helper automatically converts all javascript primitives to strings before displaying them. If the argument is a function, it will call the function without any arguments and convert the return value to a string. The output of the text helper is HTML escaped, so all tags and markup will be rendered in plain text.

If the helper is bound to an observable, the page will automatically update whenever the value changes.

var hb = Handlebind; 
var viewModel = {
	firstName: hb.observable('John'),
	lastName: hb.observable('Smith')
};

would render as

<p>
	<script id="metamorph-0-start" type="text/x-placeholder"></script>
	Smith
	<script id="metamorph-0-end" type="text/x-placeholder"></script>
	, 
	<script id="metamorph-1-start" type="text/x-placeholder"></script>
	John
	<script id="metamorph-1-end" type="text/x-placeholder"></script>
</p>

Handlebind uses the paired metamorph <script> tags to identify the region of the DOM that will be replaced when rerendering. This technique is used throughout Handlebind to support robust, dynamic templating and data-binding. Because auto-updating values emits HTML when rendering, you cannot reliably use the text helper inside another tag. For example:

<div class="entry">
	{{! DON'T DO THIS }}
	<ul class="{{text listClass}}">
		<li>One</li>
		<li>Two</li>
	</ul>
</div>

may result in the clearly malformed:

<div class="entry">
	<ul class="
		<script metamorph-0-start type="text/x-placeholder"></script>
			num-list
		<script metamorph-0-end type="text/x-placeholder"></script>
	">
		<li>One</li>
		<li>Two</li>
	</ul>
</div>

In these situations you should use a task specific helper such as {{class}} or {{attrs}}. These helpers use unique IDs and custom attributes such as attr-bind="hb0" to mark the affected tag. The metamorph tags can also affect manual DOM traversal and CSS psuedo-selectors such as :first-child. Take care to ensure your techniques are compatible with the HTML generated by your Views with both bound and unbound values.

Handlebind.js

Installing

Getting Started

Usage

Table of Contents

Helpers

The {{text}} helper

The {{html}} helper

The {{attrs}} helper

The {{class}} helper

The {{props}} helper

The {{enabled}} helper

The {{disabled}} helper

The {{events}} helper

Event Bubbling

The {{value}} helper

The {{checked}} helper

The {{focused}} helper

The {{options}} helper

The {{action}} helper

The {{template}} helper

Block Helpers

The {{#with}} block helper

The {{#each}} block helper

The {{#if}} block helper

The {{#unless}} block helper

The {{#unbound}} block helper

Building