thoughts on coding

June 4, 2012

Binding extension functions (Part IV)

Filed under: Javascript, WWA — Frantisek @ 10:43 pm

Binding extension functions

WinJS binding declaration offers binding customization via a custom binding method. There are several possibilities how to specify binding extension method.

A background info

The steps required for binding functions are:

  1. write a function meeting the following method signature:
    function (source, sourceProperty, dest, destProperty)
    

    The parameter names are self-explainable.

  2. make it publicly available from the global window object (example bellow exposes a function accessible as MvvmJS.Binding.localize)
  3. the binding function has to be marked “supported for processing” (it’s a requirement introduced by Win8 RC build). It can be done i.e. calling WinJS.Utilities.markSupportedForProcessing(fn)

Example

   WinJS.Namespace.define("MvvmJS.Binding", {
        localize: function (source, sourceProperty, dest, destProperty) {
            ......
        },
        .....
    });

    var markSupportedForProcessing = WinJS.Utilities.markSupportedForProcessing;
    Object.keys(MvvmJS.Binding).forEach(function (key) {
        markSupportedForProcessing(MvvmJS.Binding[key]);
    });

Extensions in action

Sample JS object

Let’s have the following Javascript class which will be used throug all samples.

    WinJS.Namespace.define("BindingExtensions.ViewModels", {
        SampleViewModel: MvvmJS.Class.define(function () {
            this.color = "red";
        }, {
            generateColor: function () {
                var colors = ['red', 'green', 'yellow'];
                var index = Math.ceil(Math.random() * colors.length-1);
                this.color = colors[index];
            }
        }, {
            color: {
                get : function () {
                    return this._color;
                },
                set : function (value) {
                    this._color = value !== null && value !== undefined && value.length === 0 ? "empty" : value;
                    this.colorRes = "color." + this._color;
                    this.richDescription = "This is rich multiline <BR> text. Selected color is <b>" + this._color + "</b>";
                    this.isGreen = value === "green";
                }
            },
            isGreen: null,
            colorRes: null,
            richDescription: null
            
        })
    });

In other words, there is a class SampleViewModel defined on namespace BindingExtensions.ViewModels. The class has for properties:

  • color: it’s accessible property (with get/set methods) which sets the rest properties based on sample dummy logic.
  • isGreen: it’s value property returning true in case color is ‘green’
  • colorRes: it’s value property containing a calculated resource key in form ‘color.{colorname}’.
  • richDescription: it’s value property and contains a dummy rich description with a color name.

Binding extension: localize

Usage:

<div class="value" data-win-bind="innerText:colorRes MvvmJS.Binding.localize"></div>

Explanation:
It reads the key (string) from colorRes property, use WinJS.Resources to translate it to user’s language and sets innerText of DIV element. It also rerun in case colorRes changes automaticaly out of the box.

Binding extension: style

Usage:

<div class="value" data-win-bind="backgroundColor:color MvvmJS.Binding.style">background color set to selected color</div>

Explanation:
It reads the color from the property and sets its value to backgroundColor on DIV’s style object. It handles color property changes automatically out of the box and rerun the binding.

Binding extension: urlStyle

Usage:

<div class="value" data-win-bind="backgroundImage:colorUri MvvmJS.Binding.urlStyle">background color set as background image</div>

Explanation:
It reads the colorUri from the property and sets its formatted value (form ‘url(value)’) to backgroundImage on DIV’s style object. It’s just a specific version of previous ‘style’ extension. Of course, it handles colorUri property changes automatically out of the box and rerun the binding.

Binding extension: toggleClass

Usage:

<div class="value" data-win-bind="WARNING:isGreen MvvmJS.Binding.toggleClass">text is capitalized in case the entered color is green</div>

Explanation:
It reads the boolean property isGreen from the data context object and it adds/remove (based on boolean property) the class WARNING on DIV’s class attribute. Of course, it handles property changes automatically out of the box and rerun the binding.

Binding extension: twoway

Usage:

<input type="text" class="value" data-win-bind="value:color MvvmJS.Binding.twoway"></input>

Explanation:
It activates two-way databinding between a property of the UI element and a property of the datacontext object. By default, the element’s properties are not observable. The only way to be notified about the property change is to handle an appropriate event depending on the UI control. MvvmJS comes with the two-way binding support for the following elements:

  • textbox: event ‘input’
  • checkbox: event ‘change’
  • more elements come later

In the above example, the text entered into the textbox (name of the color) is copied to property ‘color’ on the datacontext object and vice versa (from the object’s property to the textbox value).

Binding extension: unsafeHTML

Usage:

<div class="value" data-win-bind="innerHTML:richDescription MvvmJS.Binding.unsafeHTML"></div>

Explanation:
It reads the property richDescription from the data context object and it sets innerHTML of DIV. This operation (setting HTML property) is threaten as unsafe and throws security exception. If the content of the property is safe and it’s necessary to preserve the markup then it’s necessary to set innnerHTML through window.execUnsafeLocalFunction method. Of course, if a datacontext property changes, it automatically reruns the binding.

Binding extension: event

Usage:

<div class="button" data-win-bind="click:generateColor MvvmJS.Binding.event">click to generate color</div>

Explanation:
It binds onclick event raised by DIV element to the datacontext’s method generateColor. In addition ‘this’ object of event handler method generateColor is preserved (‘this’ is set to the datacontext object).

Summary

All binding extensions are included in the sample project BindingExtensions downloaded from MvvmJS codeplex project.



About these ads

3 Comments »

  1. [...] Example: lets have a HTML element wich is “bound” to ViewModel (JS object). Changes done in ViewModel can be reflected on HTML element, i.e. it can change a style, color, change a text inside, etc. Full example can be checked here [...]

    Pingback by Template Selector control « thoughts on coding — June 20, 2012 @ 8:09 am

  2. ” isGreen: it’s value property returning true in case color is ‘red’ ”

    kill me…

    Comment by redIsGreen — April 10, 2013 @ 8:49 am

    • fixed .. sorry for confusion..

      Comment by Frantisek — April 10, 2013 @ 9:08 am


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

The Shocking Blue Green Theme. Create a free website or blog at WordPress.com.

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: