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.
