Project Setup

Code Changes

RequireJS

Since WinJS apps need to be launched using the code that’s in the default.js file, we can’t use the traditional way to launch Durandal with the data-main=”/App/main”. Instead, we’ll have to do it a bit more manually.

Configuration

To make this easier, we’ll open up the main.js and extract the RequireJS configuration at the top of the file into its own file called require.config.js. The code looks like this in main.js:

requirejs.config({
  paths: {
    'text': '../Scripts/text',
    'durandal': '../Scripts/durandal',
    'plugins': '../Scripts/durandal/plugins',
    'transitions': '../Scripts/durandal/transitions'
  }
});

In order to extract it into a separate file, the object literal passed into the requirejs.config function needs to be assigned to the global require variable. So, the new file will set require = [object literal copied from above]. In addition, we need to set the base URL of the application to point to the “/App” folder, so we’ll add the “baseUrl” setting as well. The final version of require.config.js looks like this:

This file needs to be added in the default.html above the inclusion of require.js, since it needs to be set before require.js is loaded. So go add the following line:

Startup

Now, all we need to do is wire up RequireJS to load our Durandal app.

If you look in the default.js file, you will see a block of code that looks like this:

Notice the line that says “args.setPromise(WinJS.UI.processAll());”. This is what processes WinJS UI binding and basically kick starts the whole app. We need to leave this in there, but add something else onto the end, so we’ll add a .then() call to the processAll() method’s promise.

WARNING: If you are not intimately familiar with the concept of Promises in JavaScript, you should familiarize yourself with it. Almost everything in WinJS/WinRT is asynchronous, which means Promises in JavaScript.

OK, so if we replace that line with the following lines, we should be in good shape:

This call just explicitly requires the “main” module, just like the data-main=”/App/main” attribute does in a typical Durandal setup.

OK, this app will actually run and show you what you’re expecting. A full, running Durandal Project. If you run it in the Simulator, it looks like this:

Problems

Flickr               

Unfortunately, the Flickr tab will not work ever. You will see errors like:

APPHOST9601: Can’t load <http://api.flickr.com/...
An app can’t load remote web content in the local context.

This is a security issue. Remote content cannot be loaded and directly displayed in a WinJS application. If the application has permissions, it can download the content and display it, but it can’t pull it from the server directly (i.e. <img src=”http://some.internet.site/foo.png />)

Templates

Simple data binding works fine, but templates present a problem. Dynamically creating HTML and injecting it into an application is a potential security hole. Since we need to be able to do this occasionally, Microsoft provided a method to tell the runtime that it’s OK. This method is called MSApp.execUnsafeLocalFunction()

First, we’ll make it fail.

Making it Fail

We’ll replace the Flickr view with another dummy view with a simple template binding (actually copied from the knockout website). So, we’ll rename “flickr.*” to “dummy.*” and simplify it. Here are the contents of the files now:

Dummy.js:

define([], function () {
  return {
buyer: { name: 'Tom', credits: 250 },
seller: { name: 'Rob', credits: 5800 }
};
});

<script type="text/html" id="person-template">
  <h3 data-bind="text: name"></h3>
  <p>Credits: <span data-bind="text: credits"></span></p>
</script>
<section>
  <div margin="200px">
    <h2>Participants</h2>
    Here are the participants:
    <div data-bind="template: { name: 'person-template', data: buyer }"></div>
    <div data-bind="template: { name: 'person-template', data: seller }"></div>
  </div>
</section>

Remember to change the routing map in “shell.js” to this:

{ route: 'dummy', moduleId: 'viewmodels/dummy', nav: true }

Now, if you try to run this, the app will die with an error like the following:

HTML1701: Unable to add dynamic content '
<script type="text/html" id="person-template">
  <h3 data-bind="text: name"></h3>
  <p>Credits: <span data-bind="text: credits"></span></p>
</script>
<section>
  <div margin="200px">
    <h2>Participants</h2>
    Here are the participants:
    <div data-bind="template: { name: 'person-template', data: buyer }"></div>
    <div data-bind="template: { name: 'person-template', data: seller }"></div>
 </div>  �
</section>'. A script attempted to inject dynamic content, or elements previously modified dynamically, that might be unsafe. For example, using the innerHTML property to add script or malformed HTML will generate this exception. Use the toStaticHTML method to filter dynamic content, or explicitly create elements and attributes with a method such as createElement.  For more information, see http://go.microsoft.com/fwlink/?LinkID=247104.

You can see that it’s trying to render things, but it fails because the WinJS runtime does not allow arbitrary HTML injection.

Making it Work    

In Durandal, the code that parses the HTML for injection into Durandal is in the viewEngine object. Rob Eisenberg was kind enough to expose the parseMarkup() method so that Durandal can support WinJS.

So, we need to add the following code somewhere:

var parser = viewEngine.parseMarkup;
viewEngine.parseMarkup = function (markup) {
// wrap existing parser in an "unsafe" call
return MSApp.execUnsafeLocalFunction(function () {
return parser(markup);
});
};

Since this should happen at startup, it should most likely go into a durandal plugin, so we’ll make it a module and put in in a “startup” folder. Here are the contents of startup/htmlParsing.js:

define(['durandal/viewEngine'], function (viewEngine) {
'use strict';
return {
install: function() {
var parser = viewEngine.parseMarkup;
viewEngine.parseMarkup = function(markup) {
// wrap existing parser in an "unsafe" call
return MSApp.execUnsafeLocalFunction(function() {
return parser(markup);
});
};
    }
};
});

Now, in order to run this plugin, we need to tell Durandal about it. This means adding a second call to app.configurePlugins that points to our “startup” folder:

app.configurePlugins({
htmlParsing: true
}, "startup");

Now, it will load our new plugin. Let’s test it!

I have uploaded the code from this post to Github here:
https://github.com/tommck/DurandalWinJS

Where to go from here

One thing you’ll quickly realize is that you’ll want to take advantage of the built in controls in WinJS. They will give you all the fancy stuff, like touch integration, including scrolling with acceleration and other whiz bang stuff.

Look for my follow up articles on handling things like Extended Splash Screen, Integrating Knockout bindings into WinJS controls and working with AppBars and the Back Button.