The goal of this blog post is to describe how declarative data binding works in
the WinJS library. In particular, you learn how to use both
the data-win-bind and data-win-bindsource attributes. You also learn how to use calculated properties and converters to format
the value of a property automatically when performing data binding.
By taking advantage of WinJS data binding, you can use
the Model-View-ViewModel (MVVM) pattern when building Metro style applications with JavaScript. By using
the MVVM pattern, you can prevent your JavaScript code from spinning into chaos.
The MVVM pattern provides you with a standard pattern for organizing your JavaScript code which results in a more maintainable application.
Using Declarative Bindings
You can use
the data-win-bind attribute with any HTML element in a page.
The data-win-bind attribute enables you to bind (associate) an attribute of an HTML element to
the value of a property.
Imagine, for example, that you want to create a product details page. You want to show a product object in a page.
In that case, you can create
the following HTML page to display
the product details:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Application1</title>
<!-- WinJS references -->
<link href="//Microsoft.WinJS.0.6/css/ui-dark.css" rel="stylesheet">
<script src="//Microsoft.WinJS.0.6/js/base.js"></script>
<script src="//Microsoft.WinJS.0.6/js/ui.js"></script>
<!-- Application1 references -->
<link href="/css/default.css" rel="stylesheet">
<script src="/js/default.js"></script>
</head>
<body>
<h1>Product Details</h1>
<div class="field">
Product Name:
<span data-win-bind="innerText:name"></span>
</div>
<div class="field">
Product Price:
<span data-win-bind="innerText:price"></span>
</div>
<div class="field">
Product Picture:
<br />
<img data-win-bind="src:photo;alt:name" />
</div>
</body>
</html>
The HTML page above contains three data-win-bind attributes – one attribute for each product property displayed. You use
the data-win-bind attribute to set properties of
the HTML element associated with
the data-win-attribute.
The data-win-bind attribute takes a semicolon delimited list of element property names and data source property names:
data-win-bind=”elementPropertyName:datasourcePropertyName; elementPropertyName:datasourcePropertyName;…”
In
the HTML page above,
the first two data-win-bind attributes are used to set
the values of
the innerText property of
the SPAN elements.
The last data-win-bind attribute is used to set
the values of
the IMG element’s src and alt attributes.
By
the way, using data-win-bind attributes is perfectly valid HTML5.
The HTML5 standard enables you to add custom attributes to an HTML document just as long as
the custom attributes start with
the prefix data-. So you can add custom attributes to an HTML5 document with names like data-stephen, data-funky, or data-rover-dog-is-hungry and your document will validate.
The product object displayed in
the page above with
the data-win-bind attributes is created in
the default.js file:
(function () {
"use strict";
var app = WinJS.Application;
app.onactivated = function (eventObject) {
if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
var product = {
name: "Tesla",
price: 80000,
photo: "/images/TeslaPhoto.png"
};
WinJS.Binding.processAll(null, product);
}
};
app.start();
})();
In
the code above, a product object is created with a name, price, and photo property.
The WinJS.Binding.processAll() method is called to perform
the actual binding (Don’t confuse WinJS.Binding.processAll() and WinJS.UI.processAll() – these are different methods).
The first parameter passed to
the processAll() method represents
the root element for
the binding. In other words, binding happens on this element and its child elements. If you provide
the value null, then binding happens on
the entire body of
the document (document.body).
The second parameter represents
the data context. This is
the object that has
the properties which are displayed with
the data-win-bind attributes. In
the code above,
the product object is passed as
the data context parameter. Another word for data context is view model.
Creating Complex View Models
In
the previous section, we used
the data-win-bind attribute to display
the properties of a simple object: a single product. However, you can use binding with more complex view models including view models which represent multiple objects.
For example,
the view model in
the following default.js file represents both a customer and a product object. Furthermore,
the customer object has a nested address object:
(function () {
"use strict";
var app = WinJS.Application;
app.onactivated = function (eventObject) {
if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
var viewModel = {
customer: {
firstName: "Fred",
lastName: "Flintstone",
address: {
street: "1 Rocky Way",
city: "Bedrock",
country: "USA"
}
},
product: {
name: "Bowling Ball",
price: 34.55
}
};
WinJS.Binding.processAll(null, viewModel);
}
};
app.start();
})();
The following page displays
the customer (including
the customer address) and
the product. Notice that you can use dot notation to refer to child objects in a view model such as customer.address.street.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Application1</title>
<!-- WinJS references -->
<link href="//Microsoft.WinJS.0.6/css/ui-dark.css" rel="stylesheet">
<script src="//Microsoft.WinJS.0.6/js/base.js"></script>
<script src="//Microsoft.WinJS.0.6/js/ui.js"></script>
<!-- Application1 references -->
<link href="/css/default.css" rel="stylesheet">
<script src="/js/default.js"></script>
</head>
<body>
<h1>Customer Details</h1>
<div class="field">
First Name:
<span data-win-bind="innerText:customer.firstName"></span>
</div>
<div class="field">
Last Name:
<span data-win-bind="innerText:customer.lastName"></span>
</div>
<div class="field">
Address:
<address>
<span data-win-bind="innerText:customer.address.street"></span>
<br />
<span data-win-bind="innerText:customer.address.city"></span>
<br />
<span data-win-bind="innerText:customer.address.country"></span>
</address>
</div>
<h1>Product</h1>
<div class="field">
Name:
<span data-win-bind="innerText:product.name"></span>
</div>
<div class="field">
Price:
<span data-win-bind="innerText:product.price"></span>
</div>
</body>
</html>
A view model can be as complicated as you need and you can bind
the view model to a view (an HTML document) by using declarative bindings.
Creating Calculated Properties
You might want to modify a property before displaying
the property.
For example, you might want to format
the product price property before displaying
the property. You don’t want to display
the raw product price “80000”. Instead, you want to display
the formatted price “$80,000”.
You also might need to combine multiple properties. For example, you might need to display
the customer full name by combining
the values of
the customer first and last name properties.
In these situations, it is tempting to call a function when performing binding. For example, you could create a function named fullName() which concatenates
the customer first and last name. Unfortunately,
the WinJS library does not support
the following syntax:
<span data-win-bind=”innerText:fullName()”></span>
Instead, in these situations, you should create a new property in your view model that has a getter. For example,
the customer object in
the following default.js file includes a property named fullName which combines
the values of
the firstName and lastName properties:
(function () {
"use strict";
var app = WinJS.Application;
app.onactivated = function (eventObject) {
if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
var customer = {
firstName: "Fred",
lastName: "Flintstone",
get fullName() {
return this.firstName + " " + this.lastName;
}
};
WinJS.Binding.processAll(null, customer);
}
};
app.start();
})();
The customer object has a firstName, lastName, and fullName property. Notice that
the fullName property is defined with a getter function. When you read
the fullName property,
the values of
the firstName and lastName properties are concatenated and returned.
The following HTML page displays
the fullName property in an H1 element. You can use
the fullName property in a data-win-bind attribute in exactly
the same way as any other property.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Application1</title>
<!-- WinJS references -->
<link href="//Microsoft.WinJS.0.6/css/ui-dark.css" rel="stylesheet">
<script src="//Microsoft.WinJS.0.6/js/base.js"></script>
<script src="//Microsoft.WinJS.0.6/js/ui.js"></script>
<!-- Application1 references -->
<link href="/css/default.css" rel="stylesheet">
<script src="/js/default.js"></script>
</head>
<body>
<h1 data-win-bind="innerText:fullName"></h1>
<div class="field">
First Name:
<span data-win-bind="innerText:firstName"></span>
</div>
<div class="field">
Last Name:
<span data-win-bind="innerText:lastName"></span>
</div>
</body>
</html>
Creating a Converter
In
the previous section, you learned how to format
the value of a property by creating a property with a getter. This approach makes sense when
the formatting logic is specific to a particular view model.
If, on
the other hand, you need to perform
the same type of formatting for multiple view models then it makes more sense to create a converter function. A converter function is a function which you can apply whenever you are using
the data-win-bind attribute.
Imagine, for example, that you want to create a general function for displaying dates. You always want to display dates using a short format such as 12/25/1988.
The following JavaScript file – named converters.js – contains a shortDate() converter:
(function (WinJS) {
var shortDate = WinJS.Binding.converter(function (date) {
return date.getMonth() + 1 +
"/" + date.getDate() +
"/" + date.getFullYear();
});
// Export shortDate
WinJS.Namespace.define("MyApp.Converters", {
shortDate: shortDate
});
})(WinJS);
The file above uses
the Module Pattern, a pattern which is used through
the WinJS library. To learn more about
the Module Pattern, see my blog entry on namespaces and modules:
http://stephenwalther.com/blog/archive/2012/02/22/windows-web-applications-namespaces-and-modules.aspx
The file contains
the definition for a converter function named shortDate(). This function converts a JavaScript date object into a short date string such as 12/1/1988.
The converter function is created with
the help of
the WinJS.Binding.converter() method. This method takes a normal function and converts it into a converter function.
Finally,
the shortDate() converter is added to
the MyApp.Converters namespace. You can call
the shortDate() function by calling MyApp.Converters.shortDate().
The default.js file contains
the customer object that we want to bind. Notice that
the customer object has a firstName, lastName, and birthday property. We will use our new shortDate() converter when displaying
the customer birthday property:
(function () {
"use strict";
var app = WinJS.Application;
app.onactivated = function (eventObject) {
if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
var customer = {
firstName: "Fred",
lastName: "Flintstone",
birthday: new Date("12/1/1988")
};
WinJS.Binding.processAll(null, customer);
}
};
app.start();
})();
We actually use our shortDate converter in
the HTML document.
The following HTML document displays all of
the customer properties:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Application1</title>
<!-- WinJS references -->
<link href="//Microsoft.WinJS.0.6/css/ui-dark.css" rel="stylesheet">
<script src="//Microsoft.WinJS.0.6/js/base.js"></script>
<script src="//Microsoft.WinJS.0.6/js/ui.js"></script>
<!-- Application1 references -->
<link href="/css/default.css" rel="stylesheet">
<script src="/js/default.js"></script>
<script type="text/javascript" src="js/converters.js"></script>
</head>
<body>
<h1>Customer Details</h1>
<div class="field">
First Name:
<span data-win-bind="innerText:firstName"></span>
</div>
<div class="field">
Last Name:
<span data-win-bind="innerText:lastName"></span>
</div>
<div class="field">
Birthday:
<span data-win-bind="innerText:birthday MyApp.Converters.shortDate"></span>
</div>
</body>
</html>
Notice
the data-win-bind attribute used to display
the birthday property. It looks like this:
<span data-win-bind="innerText:birthday MyApp.Converters.shortDate"></span>
The shortDate converter is applied to
the birthday property when
the birthday property is bound to
the SPAN element’s innerText property.
Using data-win-bindsource
Normally, you pass
the view model (the data context) which you want to use with
the data-win-bind attributes in a page by passing
the view model to
the WinJS.Binding.processAll() method like this:
WinJS.Binding.processAll(null, viewModel);
As an alternative, you can specify
the view model declaratively in your markup by using
the data-win-datasource attribute. For example,
the following default.js script exposes a view model with
the fully-qualified name of MyWinWebApp.viewModel:
(function () {
"use strict";
var app = WinJS.Application;
app.onactivated = function (eventObject) {
if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
// Create view model
var viewModel = {
customer: {
firstName: "Fred",
lastName: "Flintstone"
},
product: {
name: "Bowling Ball",
price: 12.99
}
};
// Export view model to be seen by universe
WinJS.Namespace.define("MyWinWebApp", {
viewModel: viewModel
});
// Process data-win-bind attributes
WinJS.Binding.processAll();
}
};
app.start();
})();
In
the code above, a view model which represents a customer and a product is exposed as MyWinWebApp.viewModel.
The following HTML page illustrates how you can use
the data-win-bindsource attribute to bind to this view model:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Application1</title>
<!-- WinJS references -->
<link href="//Microsoft.WinJS.0.6/css/ui-dark.css" rel="stylesheet">
<script src="//Microsoft.WinJS.0.6/js/base.js"></script>
<script src="//Microsoft.WinJS.0.6/js/ui.js"></script>
<!-- Application1 references -->
<link href="/css/default.css" rel="stylesheet">
<script src="/js/default.js"></script>
</head>
<body>
<h1>Customer Details</h1>
<div data-win-bindsource="MyWinWebApp.viewModel.customer">
<div class="field">
First Name:
<span data-win-bind="innerText:firstName"></span>
</div>
<div class="field">
Last Name:
<span data-win-bind="innerText:lastName"></span>
</div>
</div>
<h1>Product</h1>
<div data-win-bindsource="MyWinWebApp.viewModel.product">
<div class="field">
Name:
<span data-win-bind="innerText:name"></span>
</div>
<div class="field">
Price:
<span data-win-bind="innerText:price"></span>
</div>
</div>
</body>
</html>
The data-win-bindsource attribute is used twice in
the page above: it is used with
the DIV element which contains
the customer details and it is used with
the DIV element which contains
the product details.
If an element has a data-win-bindsource attribute then all of
the child elements of that element are affected.
The data-win-bind attributes of all of
the child elements are bound to
the data source represented by
the data-win-bindsource attribute.
Summary
The focus of this blog entry was data binding using
the WinJS library. You learned how to use
the data-win-bind attribute to bind
the properties of an HTML element to a view model. We also discussed several advanced features of data binding. We examined how to create calculated properties by including a property with a getter in your view model. We also discussed how you can create a converter function to format
the value of a view model property when binding
the property. Finally, you learned how to use
the data-win-bindsource attribute to specify a view model declaratively.
