Nano Titanium

A simple two-way data-binding library for Appcelerator's Alloy framework for Titanium.

Install

From the root of your existing alloy project you can either.

Install using gitto

$ gittio install nano

or install using npm

$ npm install ti-nano

It will copy all the required libraries to your app/lib folder.

Setup

Add the following to the beginning of your controller:

var nano = require("nano");
nano.syntax(/\-\=(.+?)\=\-/gi);

For an explanation of the syntax command see the binding section.

Create an object you want to bind against, e.g.

var $model = {
  person: {
    first: "David",
    last: "Bankier"
  },
  field:"asdf"
};

Then add the following to the end of your controller.

nano($,$model);

The object can really be any POJO, e.g. you can use args

var args = arguments[0];
nano($,args);

N.B. using this is not really recommended.

Binding

Binding is two-way by default. So any changes in the view is reflected in the model and vice-versa.

The default syntax is {{ attribute }}. Currently there is a limitation in Alloy that prevents its usage. See this issue. The default syntax can be changed using the nano.syntax command.

For the examples below the follow command was used to change the syntax:

nano.syntax(/\-\=(.+?)\=\-/gi);

This changes the syntax -= attribute =-.

Simple Cases

That aside you can bind against view properties like this:

<Alloy>
	<Window class="container">
    <View top="100" layout="vertical">
      <TextField value="-=person.first=-"></TextField>
      <Label>-=person.first=-</Label>
    </View>
	</Window>
</Alloy>

You can also bind multiple values as follows.

<Alloy>
	<Window class="container">
    <View top="100" layout="vertical">
      <TextField value="-=person.first=-"></TextField>
      <TextField value="-=person.last=-"></TextField>
      <Label>Hello, -=person.first=- -=person.last=-</Label>
    </View>
	</Window>
</Alloy>

expression

Binding also be against expression.

<Alloy>
	<Window class="container">
    <View top="100" layout="vertical">
      <TextField value="-=person.first=-"></TextField>
      <TextField value="-=person.last=-"></TextField>
      <Label>Hello, -=person.first=- -=person.last=-, length: -=person.last.length=-</Label>

      <TextField value="-=field=-"></TextField>
      <Label>Length: -=field.length=-</Label>
    </View>
	</Window>
</Alloy>

You can bind with any js expression that can be evaluated and against any view property. Here is a validation example.

<Alloy>
	<Window class="container">
    <View top="100" layout="vertical">
      <TextField value="-=person.first=-"></TextField>
      <TextField value="-=person.first=-"></TextField>
      <TextField value="-=person.last=-" color="-= person.last.length < 4 ? 'red' : 'black' =-"></TextField>
      <Label text="-=person.last.length < 4 ? 'last name too short' : ''=-"></Label>
    </View>
	</Window>
</Alloy>

One-Way binding

You can use the oneway attribute if you want force one-way binding. This is part of the building nano-oneway plug-in.

<Alloy>
	<Window class="container">
    <View top="100" layout="vertical">
      <TextField value="-=person.first=-"></TextField>
      <TextField value="-=person.last=-" color="-= person.last.length < 4 ? 'red' : 'black' =-"></TextField>
      <TextField value="-=person.last=-" oneway></TextField>
    </View>
	</Window>
</Alloy>

Changes in the controller.

Until we have Object.observe support, if you make changes in the controller to the $model then you need to call the following command to trigger the updates to all bound views.

  nano.apply();

Plugins

Loading

Load your plug-ins once, in your alloy.js file. For example:

var nano = require("nano");
var debounce = require("nano-debounce");
nano.load(debounce());

Official Plugins (see #7)

nano-debounce - add a debounce delay so that changes in the view are only applied to the model after a timer expiry of inactivity
nano-class - bind the model to the class (style) of a view.
nano-bindon - change the view bind event from change to any other.

Wrting

See the src/plugins folder for some examples in order to create a plug-in.

You can hook into the following events:

model:bind - called prior to binding to a model property.
model:change - called when a model change is detected.
view:init - called prior to initialising the view with the bound model values.
view:bind - called prior to adding a listener to the change event of the bound view.
view:change - called when the change event of the view is called.

A hook is added in your plug by calling the hook command. For example, the one-way binding plug-in:

// Initialises and properties in template/expression that aren't in the $model
module.exports = function(options) {
  return function(nano) {
    nano.hook('model:bind', function(args, next) {
      if(!args.view.oneway) {
        next();
      }
    });
  };
};

The following arguments are passed when the hook is called:

args - this object contains the following properties:
- $ - $ from the controller
- $model - the bound model
- view - bound view raising the event, e.g. the Ti.UI.Label
- prop - the view's bound property raising the event, e.g. text (for model:bind this is the property of the model)
- expr - the bound expresion, e.g. if the value of text is Surname length: {{last.length}}, expr would be last.length
next - the hooks act like middle and are executed in the order they were loaded. next is a callback to continue.

Building from Source

Building the distributable is done using grunt

Enter the following:

$ npm install
$ grunt

The built library is found in at dist/nano.js

Under The Hood

It uses Polymer's object-js to fill in the gaps until we get Object.observe in Titanium.

Why

This was originally motivated by seeing this by @rblalock.

I rarely use backbone models built-in to Alloy. Also having been spoilt by the data-binding options for web-developers I find the data-binding built into Alloy limited and overly complicated.

dbankier/nano