Properties

At the core of Gaffa is the ability to bind the properties of ViewItems to the model:

var textbox1 = new Textbox();
textbox1.value.binding = '[someBinding]';

var textbox2 = new Textbox();
textbox2.value.binding = '[someBinding]';

// The two textbox's values will be bound to the same value

This simple feature, combined with gel expressions is what makes gaffa so powerful.

To support this functionality, Gaffa has a Constructor called Property which can be assigned to ViewItems

Only instances of Property will be bound to the model.

In the above example, the value property on each Textbox is an instance of Property:

function Textbox(){}
...

Textbox.prototype.value = new Gaffa.Property(...);

This is how Gaffa knows what to keep track of on ViewItems.

The Property constructor

Gaffa.Property inherits from Bindable

Property properties...

value

The value of the property.

This can be set once when a ViewItem is created:

var label = new Label();
label.text.value = 'Hello World!';

Or it can be set by the Properties binding...

binding

An expression to run to get the Properties value

the binding can be any gedi expression, for example:

An expression that contains a model path:

label.text.binding = '[pathToAModelValue]';

An expression that results in a string:

label.text.binding = '"Hello World!"';

An expression that results in a number:

label.text.binding = '123';

An expression that does a calculation:

label.text.binding = '(/ 123 2)';

A combination of many things:

label.text.binding = '(join " " "Hello World!, half of" [someValue] "is" (/ [someValue] 2))';

If the model changes at any path referenced in a Properties binding, the Property will re-evalutate the expression, assign the new value to .value, and call the Properties update function

note: Property.value will ALWAYS be up to date,

but Property.update may not always be called, depending on what is set for .watchChanges...

watchChanges

A space-seperated string of change types. Uses what-changed

If any type in the list matches any change to the value, the property will update.

by default, Property.watchChanges is 'value keys structure reference type'

Example:

    var linkItems = new Link();

    linkItems.source.binding = '(filter [items] {item (< item.size 10)})';

    linkItems.source.watchChanges = 'keys'; 
    // The source property will only update if the result of its
    // binding has different keys to its previous result

    linkItems.target.binding = '[filteredItems]';

update

Note: the update function should NOT be changed while setting up a UI. It should be implemented by the ViewItem vendor (be that yourself or a third party)

A function that runs when the Properties value changes, if allowed by watchChanges

Example:

function SomeViewItem(){}

...normal ViewItem setup code...

SomeViewItem.prototype.text = new Gaffa.Property({
    value: //initial value
    update: function(viewItem, value){ ... },
    watchChanges: // default watchChanges types
});

A properties update function is what keeps a ViewItem in sync with the model, for example a simple label view:

function Label(){}

...normal view setup code...

Label.prototype.text = new Gaffa.Property({
    update: function(view, value){
        if(value == null){
            value = '';
        }
        view.renderedElement.textContent = value;
    }
});

The above is enough code to ensure that a views textContent is in sync with the model.

it could the be used in the normal way:

var label = new Label();
label.text.binding = '[something]';