Custom Windows 8 HTML Controls

But even more powerful is the ability to create your own custom controls. Let’s do it. Create a new blank Windows 8 JavaScript project in VS2012. Create a new JavaScript file in the js folder. Name it DummyControl.js and fill it with this code:

[php lang=”JavaScript”]WinJS.Namespace.define(“bit101″, {
DummyControl: WinJS.Class.define(
function (element, options) {
// constructor
console.log(element);
console.log(options);
}, {
// instance members
}, {
// static members
})
}
);[/php]

Here we are defining a namespace called bit101. It will consist of an object with a single property called DummyControl. And bit101.DummyControl will be a pseudoclass defined with WinJS.Class.define. I know, I know. But that’s how it’s done and it’s pretty straightforward. The define method takes 3 arguments. The first is a function which becomes the class’s constructor. The next is an object containing instance members and then an object containing any static members. You can see that the constructor function gets passed the element that the control is instantiated in, and the options that are passed in in the data-win-options attribute.

You can now add the script reference and an instance of this control to your default.html file and run the app.

[php lang=”html”]

[/php]

I passed in an empty object to options just so we could see something traced out. You should see this in your output:

[php lang=”javascript”]
[object HTMLDivElement][object Object][/php]

Now we can start building out the control to actually do something. Instead of just logging them, we’ll save the parameters and call an init function. The init function will create a new h1 tag and append it to the control’s element:

[php lang=”javascript”]WinJS.Namespace.define(“bit101”, {
DummyControl: WinJS.Class.define(
function (element, options) {
// constructor
this.element = element;
this.options = options;
this.init();
}, {
// instance members
init: function () {
this.h1 = document.createElement(“h1”);
this.h1.innerText = this.options.message || “Hello world”;
this.element.appendChild(this.h1);
}
}, {
// static members
})
}
);[/php]

The h1 tag’s inner text is set to the message property of the options, if it exists, otherwise it defaults to “Hello World”. Running this now should result in a large “Hello world” being displayed in the app.

We can then set the message to whatever we want via the options:

[php lang=”html”]

[/php]

Additionally, you can create methods that can be called on the control itself from external scripts. Let’s make a new function that allows us to change the message:

[php lang=”javascript”]WinJS.Namespace.define(“bit101”, {
DummyControl: WinJS.Class.define(
function (element, options) {
// constructor
this.element = element;
this.options = options;
this.init();
}, {
// instance members
init: function () {
this.h1 = document.createElement(“h1”);
this.h1.innerText = this.options.message || “Hello world”;
this.element.appendChild(this.h1);
},

setMessage: function (message) {
this.h1.innerText = message;
}
}, {
// static members
})
}
);[/php]

But how do we access that? Well first, notice that I gave the div containing the control an id of “dummy”, so it’s easy enough to find the div by saying document.getElementById(“dummy”). But that just gives us the div that contains the control, not the control itself. For that we access the winControl property of that div, like so:

[php lang=”javascript”]var dummyControl = document.getElementById(“dummy”).winControl;[/php]

But, a very important thing to remember here: Earlier in the article I mentioned that calling WinJS.UI.processAll finds all the data-win-control divs and instantiates their controls. So you need to A. call this function, and B. wait for it to complete. The function uses the promises pattern, so all we have to do is something like this:

[php lang=”javascript”] args.setPromise(WinJS.UI.processAll().then(function () {
var dummyControl = document.getElementById(“dummy”).winControl;
dummyControl.setMessage(“It works!”);
}));[/php]

Of course, this is a rather simple example created for demonstration purposes. In a real control, you can add all the elements, event handlers, styles, and behavior you want in there and create some pretty complex components. As an example, I’ve built a pretty full featured control called FPSDisplay. This displays the current frame rate of a running app based on requestAnimationFrame and a running bar graph of how the frame rate has changed over the recent past. All you have to do is include the fpsDisplay.js file in your HTML and create an instance like so:

[php lang=”html”]

[/php]

Options include color, bgColor and position, which can be “tl”, “tr”, “bl”, “br” (top left, top right, etc.). Methods include start and stop which do the obvious.

Here’s the code in full for you to peruse though. I’m not going to comment on it though. Save it out and add it to your project and see how it goes.

[php lang=”javascript”]WinJS.Namespace.define(“bit101”, {
FPSDisplay: WinJS.Class.define(function (element, options) {
if (!element) {
throw “element must be provided”;
}
this.options = options || { position: “tl” };
this.element = element;
this.init();
}, {
init: function () {
this.child = document.createElement(“div”);
this.child.style.position = “absolute”;
this.setPosition(this.options.position);
this.element.appendChild(this.child);

var canvas = document.createElement(“canvas”);
canvas.width = 100;
canvas.height = 50;

this.context = canvas.getContext(“2d”);
this.context.fillStyle = “white”;
this.context.fillRect(0, 0, 100, 50);
this.context.font = “10px Arial”;

this.child.appendChild(canvas);

this.text = document.createElement(“div”);
this.text.style.font = “10px Arial”;
this.text.style.color = this.options.color || “black”;
this.text.style.backgroundColor = this.options.bgColor || “white”;
this.text.style.position = “absolute”;
this.text.style.top = “1px”;
this.text.style.left = “2px”;
this.child.appendChild(this.text);

this.onVisibilityChanged = this.onVisibilityChanged.bind(this);
document.addEventListener(“visibilitychange”, this.onVisibilityChanged, false);
this.history = [];
this.update = this.update.bind(this);
this.start();
},

onVisibilityChanged: function() {
if (document.visibilityState === “hidden”) {
this.lastTime = 0;
this.frames = 0;
this.elapsed = 0;
}
},

start: function () {
this.frames = 0;
this.isRunning = true;
this.elapsed = 0;
this.lastTime = 0;
this.animRequest = window.requestAnimationFrame(this.update);
},

stop: function () {
this.isRunning = false;
cancelAnimationFrame(this.animRequest);
},

update: function (time) {
if (!this.lastTime) {
this.lastTime = time;
this.animRequest = window.requestAnimationFrame(this.update);
return;
}

this.elapsed += time – this.lastTime;
this.frames += 1;
this.lastTime = time;
this.animRequest = window.requestAnimationFrame(this.update);
if (this.elapsed > 1000) {
this.frames = Math.round(this.frames * 1000 / this.elapsed);
this.elapsed = 0;
this.draw();
}
},

draw: function () {
var min = 1000;
var max = 0;
for (var i = Math.max(this.history.length – 10, 0); i < this.history.length; i += 1) { min = Math.min(min, this.history[i] - 2); max = Math.max(max, this.history[i] + 2); } var range = max - min; this.history.push(this.frames); if (this.history.length > 50) {
this.history.shift();
}
this.context.fillStyle = this.options.bgColor || “white”;
this.context.fillRect(0, 0, 100, 50);
this.context.fillStyle = this.options.color || “black”;
for (var i = 0; i < this.history.length; i += 1) { var value = this.history[i]; var h = (value - min) / range * 50; this.context.fillRect(i * 2, 50 - h, 1, h); } this.text.innerHTML = this.frames + " fps"; this.frames = 0; }, setPosition: function (pos) { // default tl this.child.style.left = "0px"; this.child.style.top = "0px"; if(pos.indexOf("r") != -1) { this.child.style.left = (window.innerWidth - 100) + "px"; } if(pos.indexOf("b") != -1) { this.child.style.top = (window.innerHeight - 50) + "px"; } } } ) });[/php]