comerc / meteor-template-two-way-binding

Two-Way Binding for Blaze templates

comerc:template-two-way-binding

Two-Way Binding for Blaze templates. Simple! It's used by the Template2 package, but you can use it by itself, too.

Key features:

• value-bind declared in HTML-source - important for debug of alien code
• customizing (reactive) data-store: Session variables, TemplateController state etc.
• extensible for external data validation: SimpleSchema, Astronomy etc.

Inspired by: Aurelia, Vue, ReactLink, manuel:viewmodel and nov1n:reactive-bind.

Installation

In a Meteor app directory, enter:

$ meteor add comerc:template-two-way-binding

Usage

Add value-bind="foo" to an input element to bind it to a Session variable named "foo".

Demo

Demo here!

Example

Binds the Session variable "exampleVariable1" to the input element in the DOM. Any changes to the text field will be reflected by the Session variable and vice versa.

<template name="hello">
  <input type="text" value-bind="exampleVariable1"/>
</template>

Template.hello.rendered = TemplateTwoWayBinding.rendered;
// or
Template.hello.onRendered(function() {
  TemplateTwoWayBinding.rendered(this);
});

Supported elements

Text

<input type="text" value-bind="exampleVariable2"/>

The value stored in the Session variable is the text as String.

Password

<input type="password" value-bind="exampleVariable3"/>

The value stored in the Session variable is the text as String.

Number

<input type="number" value-bind="exampleVariable4"/>

The value stored in the Session variable is number as Number.

Textarea

<textarea name="area" value-bind="exampleVariable5"></textarea>

The value stored in the Session variable is the text as tring.

Radio button(s)

<input type="radio" name="color" value="Red" value-bind="exampleVariable6"/> Red
<input type="radio" name="color" value="Blue" value-bind="exampleVariable6"/> Blue
<input type="radio" name="color" value="Green" value-bind="exampleVariable6"/> Green

The value stored in the Session variable is the input value as String.

Date

<input type="date" value-bind="exampleVariable7"/>

The value stored in the Session variable is a Date object.

Checkbox

<input type="checkbox" value-bind="exampleVariable8"/>

The value stored in the Session variable as Boolean.

Checkbox(es)

<input type="checkbox" name="vehicle" value="Bike" value-bind="exampleVariable9"/> Bike
<input type="checkbox" name="vehicle" value="Car" value-bind="exampleVariable9"/> Car
<input type="checkbox" name="vehicle" value="Plane" value-bind="exampleVariable9"/> Plane

The value stored in the Session variable is the input value as String. When more than one checkbox is checked, it becomes an array of Strings.

Range

<input type="range" value-bind="exampleVariable10"/>

The value stored in the Session variable is the text as Number.

Color picker

<input type="color" value-bind="exampleVariable11"/>

The value stored in the Session variable is the color as hex triplet String (e.g. "#FFFFFF").

[contenteditable]

<div contenteditable="true" value-bind="exampleVariable12"></div>

The value stored in the Session variable is the HTML-value as String.

XXX tested with yabwe/medium-editor

Select

<select value-bind="select-single">
  <option value="AL">Alabama</option>
  <option value="WY">Wyoming</option>
</select>
<select multiple="multiple" value-bind="select-multiple">
  <option value="AL">Alabama</option>
  <option value="WY">Wyoming</option>
</select>

Select2 tested too

Throttle

By default throttle will only allow updates every 200ms. You can customize the rate of course. Here are a few examples.

By default, throttle will execute the function as soon as you call it for the first time, and, if you call it again any number of times during the wait period, as soon as that period is over. If you'd like to disable the leading-edge call, pass "noLeading", and if you'd like to disable the execution on the trailing-edge, pass "noTrailing".

Updating a property, at most, every 200ms

<input type="text" value-bind="variable@throttle">

Updating a property, at most, every 850ms (and noLeading, and noTrailing)

<input type="text" value-bind="variable@throttle:850:noLeading:noTrailing">

Debounce

Debounce prevents the binding from being updated until a specified interval has passed without any changes.

A common use case is a search input that triggers searching automatically. You wouldn't want to make a search API on every change (every keystroke). It's more efficient to wait until the user has paused typing to invoke the search logic.

Pass param "immediate" to cause debounce to trigger the function on the leading instead of the trailing edge of the wait interval. Useful in circumstances like preventing accidental double-clicks on a "submit" button from firing a second time.

Update after typing stopped for 200ms

<input type="text" value-bind="variable@debounce">

Update after typing stopped for 850ms (and immediate)

<input type="text" value-bind="variable@debounce:850:immediate">

TODO

• throttle & debounce
• [contenteditable]
• modelMap & validation examples: one, two
• remove dependencies of Template.body.events & aldeed:template-extension
• custom decorator
• throttle:500:notLeading:notTrailing
• debounce:500:immediate
• custom binding events ("change" as example for <select>)
• w/o jQuery
• How to implement external wrapping of events (like throttle & debounce)? I want to give up the pseudo coding, may be.
• single ckeckbox as Boolean
• select-single & select-multiple & select2
• check https://github.com/remy/bind.js
• value-bind is evil, change to simple id

License

MIT