Another week, another new technology to learn. This week I'll be using WinJS for the first time, also known as The Windows Library For JavaScript. It took me a while to figure out what WinJS was, as the definitions on the official site WinJS and GitHub are fancy sounding. But it's pretty much just an open source JavaScript framework with some pretty cool controls and data-binding features and can help with making apps for the Windows Store. It allows you to use Windows UI controls in your web applications, which is pretty cool. It's intended to give a consistent look and feel across Windows devices.
All that aside, let's see what we can make happen with WinJS. I'll be showing some controls that look pretty useful and that I'll be incorporating into my own websites.
Download/Install
You have several options with how you download/install the WinJS package. Windows recommends using any of the following package managers, but you can also just download the files directly and do with them what you wish.
And that's it pretty much, we can reference them like we do any other scripts in our web pages.
<link href="/WinJS/css/ui-dark.css" rel="stylesheet">
<link href="/WinJS/css/ui-light.css" rel="stylesheet">
<script src="/WinJS/js/WinJS.js"></script>
WinJs Controls
Adding new WinJS controls to a page is pretty straightforward. You can create a new div and use the data-win-control attribute specifying which control you want to render. For example if you want to render a Rating control you would do the following:
<body>
<div data-win-control="WinJS.UI.Rating"></div>
</body>
If you run that page, you'll see, nothing pretty much. We need to initialize our controls in our JavaScript and we can do that by calling the WinJS.UI.processAll() function once our application is ready.
<script>
WinJS.Application.onready = function () {
WinJS.UI.processAll();
};
</script>
Now if we run this, then we'll see..nothing again. Alright, because we forgot one thing. We need to start the application and we can do that after we call the processAll() function.
<script>
WinJS.Application.onready = function () {
WinJS.UI.processAll();
};
WinJS.Application.start();
</script>
And now if we run it, we should see the following:
That was actually more work that I wanted it to be. Particularly because the documentation have several different ways of doing it. I just picked the simplest route.
Control Properties
You can also add different properties to the many different WinJS controls and you can do that with a new attribute, the data-win-options, which takes the following format.
data-win-options="{propertyName: propertyValue, propertyName: propertyValue}"
In our Rating control above, if we wanted to increase the number of stars present, we could set the maxRating property to whatever number we wanted.
<div id="ratingControlHost" data-win-control="WinJS.UI.Rating"
data-win-options="{maxRating: 10}">
</div>
Of course these values aren't much use to us if we can't get to them, so we'll cover that next.
Programmin' The Control
In order to access our WinJS control we'll need to retrieve the parent element, in our case the div that houses the Rating control. We can then access the control using the winControl property as follows.
var control = document.getElementById("ratingControlHost").winControl;
Because the processAll() function call is asynchronous, we have to be careful where we access our control. If we do it right after and our page isn't done loading, then we'll have a race condition and our control won't be available. Lucky for us, the processAll() function returns a WinJS.Promise object that runs when the processAll function is finished. For example, we can set the value of our Rating control inside of this callback.
WinJS.UI.processAll().then(function () {
var control = document.getElementById("ratingControlHost").winControl;
control.averageRating = 3;
});
Adding Events
We can add events to our WinJS controls in the same way that we do to standard HTML controls, using the addEventListener function. In our case however, we'll be calling it using the winControl property of our host element. In our Rating control for example, we'll probably want to capture when the user selects a different value, and for that we can use the change event.
WinJS.UI.processAll().then(function () {
var control = document.getElementById("ratingControlHost").winControl;
control.maxRating= 10;
control.addEventListener("change", function() {
alert(this.winControl.userRating);
}, false);
});
WinJS.Application.start();
Every control has their own set of properties and methods that you can use and you can find documentation on all of those on MSDN.
So that was a quick intro into the world of WinJS. There's still plenty more to learn and to do, and in the following weeks I will be incorporating these controls and more into my own web pages and I'll document the process here for anyone that's interested. Happy Coding!