Documentation



Binding Syntax

Bindings are specified using a custom HTML attribute called data-jsBind. The syntax of a binding follows the this syntax:

 [bindingKind]:[param]=[expression]

There are four kinds of binding available with jsBind. The bindings are specified with one of the following bindingKind values:

  • prop
  • forEach
  • event
  • template

The value specified by the 'expression' parameter is any JavaScript expression. The expression can only contain one statement and cannot use any statement keywords (if, while, for, etc).

prop Bindings

A prop binding is a binding of an expression to the property value of an HTML element. The name of the property is provided in the param specifier.

For example, to bind the inner text of an element to a value from a model class you could use the following:

    data-jsBind="prop:innerText=$d.value"

In this example data-jsBind is the custom HTML attribute that jsBind uses for all binding specifiers. Prop means that this is a property binding and innerText is the property that will be bound. The expression $d.value means that the binding will be made on the value property of the model class.

The %d variable is one of several standard variables. These are the following:

Name Description
$d Data context. The current model object that is associated with the binding. The current data context can be changed by the forEach binding.
$p Parent context. The parent object that provided the reference to the current context. This is null at the top level and then is set when the context changes in forEach bindings.
$e The event context. For event bindings this is the event arguments. For other bindings this will be null.

Properties can be specified as a property path. The following example demonstrates how to bind to the css color property:

    data-jsBind="prop:style.color=$d.value < 0 ? 'red' : 'green'"

This binding will set the color to red if the value is negative and green otherwise.

forEach Bindings

Specifies a binding that provides a list of values to be repeately applied to the child nodes of the current node. For example, the following binding specifies that one row of the table should be generated for each object in the bound collection. Each row in the table will contain the value from each corresponding object in the collection.

    <table>
<tbody data-jsBind="forEach=$d.items">
    <tr>
        <td data-jsBind="prop:innerText=$d.value"></td>
    </tr>
</tbody>
</table>

This binding does not have any parameters.

event Bindings

Specifies a binding that should be evaluated when an event occurs. The param argument specifies the name of the event to attach.

Building on the previous two examples examples above this example adds a button that when clicked will invoke the method called 'handleClick' on the model object passing data item for the row as the parameter.

    <table>
<tbody data-jsBind="forEach=$d.items">
    <tr>
        <td data-jsBind="prop:innerText=$d.value, event:click=$p.handleClick($d)"></td>
    </tr>
</tbody>
</table>

Note how two bindings have been specified in the same data-jsBind attribute by seperating them with a ';' charater. The event binding makes use of the way the data context is changed by the forEach binding so that $d provides the reference to the row item and the $p parameter provides the reference to main model.

template Bindings

Template bindings specify a reference to another HTML element that should be included in the DOM at the current location.

The following parameters values are defined:

  1. id - The id of another DOM Element to use as a template.
  2. url - The url of another document to load and use as a template. (Note requires jQuery)

This example shows how the content of the row can be specified using a template binding.

    <table>
<tbody data-jsBind="forEach=$d.items; template:id='row'"></tbody>
</table>

<script id="row">
<tr>
    <td data-jsBind="prop:innerText=$d.value, event:click=$p.handleClick($d)"></td>
</tr>
</script>

Note that the ID or URL of the template is specified in quotes as a string. This allows the ID of the template to be defined as a more complicated expression included as a value bound from a model object.



Browser Compatibility

jsBind is designed to work across all modern browsers. It is tested on the following:

  1. Chrome 24+
  2. Firefox 19
  3. Safari 5.1
  4. Internet Explorer 9
  5. Opera 12+

jsBind automatically performs browser specific property translations when it is applying binding expressions. For CSS style properties it will apply the correct brower prefix automatically. So for example a property binding that specifies the style.translate property would translate to style.webkitTranslate in Chrome. The innerText/textContent properties are applied depending on the brower so for example on Firefox innerText is translated to textContent and in Chrome textContent is translated to innerText.



API

jsBind Provides class that make implementing observable models easy. This documentation applies to both JavaScript and the TypeScript language bindings. The interfaces section describes interfaces to implement in TypeScript. For JavaScript use just provide a prototype implementation of each method.

Interfaces

IObservable

Interface that defines the methods neccessary for a changes in the values of an objects members to be observed by another object.

The IObservable interface defines the following methods

addObserver(delegate)

Registers a function to call when a member value changes.

Name Type Description
delegate function(string): void Function that will be invoked when the value changes.

removeObserver(delegate)

Unregisters a previously registered change handler.

Name Type Description
delegate function(string): void Previously registered change handler function.

IObservableCollection

Interface that defines the methods neccessary for a changes in a list of values to be observed by another object.

The IObservableCollection interface defines the following methods

addCollectionObserver(delegate)

Registers a function to call when a member value changes.

Name Type Description
delegate function(any[], number, any[], number, any[] number): void Function that will be invoked when the value changes.

removeCollectionObserver(delegate)

Unregisters a previously registered change handler.

Name Type Description
delegate function(any[], number, any[], number, any[], number): void Previously registered change handler function.

Classes

Binder

The binder class provides an entry point to jsBind. Create and instance of this class with a reference to a HTML Element and a model class to bind the element to the model.

    new jsBind.Binder(element, model);

The Binder class has no methods.

Observable

Implementation of an object that can have changes in the values of its members observed by other objects. This object is intended to be used as a base class for MVVM model objects.

The Observable class has the following methods:

addObserver(delegate)

Registers a function to call when a member value changes.

Name Type Description
delegate function(string): void Function that will be invoked when the value changes.

removeObserver(delegate)

Unregisters a previously registered change handler.

Name Type Description
delegate function(string): void Previously registered change handler function.

ObservableString

Implementation of an object that can have changes in its string value observed by other objects. This class extends Observable.

The ObservableString class has the following additional methods:

get(): string

Gets the current string value.

set(value:string): void

Sets a new string value. If the new value is different to the current value then a change notification is raised.

ObservableNumber

Implementation of an object that can have changes in its numeric value observed by other objects. This class extends Observable.

The ObservableNumber class has the following additional methods:

get(): number

Gets the current numeric value.

set(value:number): void

Sets a new numeric value. If the new value is different to the current value then a change notification is raised.

ObservableBool

Implementation of an object that can have changes in its boolean value observed by other objects. This class extends Observable.

The ObservableBool class has the following additional methods:

get(): bool

Gets the current boolean value.

set(value:bool): void

Sets a new boolean value. If the new value is different to the current value then a change notification is raised.

ObservableValue

Implementation of an object that can have changes in its untyped value observed by other objects. This class extends Observable.

The ObservableValue class has the following additional methods:

get(): any

Gets the current value.

set(value:any): void

Sets a new value. If the new value is different to the current value then a change notification is raised.

ObservableCollection

Implementation of an object that maintains a list of values. The object raised change notifications whenever the list is changed. This class implements IObservableCollection and does not define any additional methods.

get(index):any

Gets the item stored at the specified index.

Name Type Description
index number Zero based index of the item in the collection to return.

set (index, item): void

Sets the specified item at the specified index into the collection.

Name Type Description
index number Zero based index of the location in the collection to set the item.
item any The item set at the index in the collection.

count(): number

Gets the number of items stored in the collection.

remove(item): bool

Removes the specified item from the collection.

Name Type Description
item any The item to remove from the collection.

forEach(callbackfn, thisArg): void

Executes a provided function once per collection element.

Name Type Description
callbackfn (value: any, index: number, array: any[]) => void The function to execute on each item in the collection.
thisArg any Reference to the object to use as 'this' while executing the callback function.

every(callbackfn, thisArg): bool

Returns true if every item in the collection satisfies the provided testing function.

Name Type Description
callbackfn (value: any, index: number, array: any[]) => bool The function to test on each item in the collection.
thisArg any Reference to the object to use as 'this' while executing the callback function.

filter(callbackfn, thisArg): any[]

Creates a new array with all the items of the collection for which the provided filtering function returns true.

Name Type Description
callbackfn (value: any, index: number, array: any[]) => bool The function to test on each item in the collection.
thisArg any Reference to the object to use as 'this' while executing the callback function.

map(callbackfn, thisArg): any[]

Creates a new array with the results of calling a provided function on each item in the collection.

Name Type Description
callbackfn (value: any, index: number, array: any[]) => any The function that returns an element on the new array based in an item in the collection.
thisArg any Reference to the object to use as 'this' while executing the callback function.

reduce(callbackfn, initialValue): any[]

Applies a function simultaneously against two items of the collection (from left-to-right) so as to reduce it to a single value.

Name Type Description
callbackfn (previousValue: any, currentValue: any, currentIndex: number, array: any[]) => any The function to execute on each item in the collection and the previous value to produce the reduce result.
initialValue any The first value to pass as the previousValue parameter to the callback function for the first item in the collection.

some(callbackfn, thisArg): bool

Returns true if at least one item in the collection satisfies the provided testing function.

Name Type Description
callbackfn (value: any, index: number, array: any[]) => any The function to test on each item in the collection.
thisArg any Reference to the object to use as 'this' while executing the callback function.

indexOf(item: any, fromIndex: number = 0): number

Search the collection for an element and returns it's position.

Name Type Description
item any The item to find in the collection.
fromIndex number The zero based index of the first location to start looking for the item.

join(seperator): string

Join the elements of the collection into a string.

Name Type Description
seperator string The string to place between the string representation of each item in the collection.

lastIndexOf(item: any): number

Search the collection for an element, starting at the end, and returns it's position.

Name Type Description
item any The item to find in the collection.
fromIndex number The zero based index of the first location to start looking for the item.

pop(): any

Removes the last element from the collection, and returns it.

push(...items): number

Adds new elements to the end of the collection, and returns the new length.

Name Type Description
items any[] The items to add to the end of the collection.

reverse(): void

Reverses the order of the elements in the collection.

shift(): any

Removes the first element of the collection, and returns it.

slice(number, end): any[]

Selects a part of a collection, and returns the items as a new array.

Name Type Description
number number The zero based index of the first item to return.
end number The zero based index of the last item to return.

sort(compareFn): void

Sorts the elements of the collection.

Name Type Description
compareFn (a: any, b: any) => number Compare function to apply to items in the collection.

splice(start, deleteCount, ...items): any[]

Adds and or removes elements from the collection.

Name Type Description
start number Zero based index of the location to start deleting and adding items in the collection.
deleteCount number The number of items to remove from the collection.
items any[] The items to add to the collection.

toString(): string

Converts the collection to a string, and returns the result.