The Anatomy of a HTML 5 Windows 8 Metro app

A few weeks ago we previewed a Windows 8 Metro BI app prototype. As we mentioned during that preview, we learned a lot about Windows 8 Metro app development. This post is the first of an in-depth series regarding what we learned developing on this new and exciting platform.
There are quite a few pieces/parts that go into the development of a HTML 5 Windows 8 Metro app. Some are created for us by Visual Studio 2011’s template, while others we have added during the building of our Windows 8 BI thought experiment, but we feel like the development model we came up with there has “legs” and so we are going to share it here.
When you first create your application you will (regardless of template) be presented with the following folders :
  • css: This folder holds all your CSS files for your project (you can reference them from your HTML or JavaScript with your absolute path of /css). Depending on the template you choose there could be several css files already in here. There should be at least default.css in here that is referenced by default.html
  • images: This folder holds all your images – ya that’s kind of obvious – like css\ you can reference files and folders in here via the absolute path of /images. there will be several images already in here that we will cover later.
  • js : This folder holds all of your custom JavaScript . Depending on the template you choose there could be several JS files already in here. There should be at least default.js which is referenced by default.html.
  • html : This folder holds all of the html that makes up your application except the default.html page. Also this folder does not get created in a blank project (though you should probably add it every time).
  • winjs : This folder holds the Microsoft WinJS framework libraries. While you “could” change these files to tweak the frameworks behavior we would advise against that model. You can extend or override anything in JavaScript , and that can be done in your own code.
To give you a quick idea why the default.html page is not stored in the html folder with the rest of your projects markup, a bit of background is good to have.. You see HTML 5 WinJS apps don’t use HTTP calls like "POST” or “GET” to navigate between pages, there is as JavaScript navigation service that Microsoft has baked into WinJS, and that service loads up HTML as fragments that it then inserts into the DOM of the default.html page. Its at your root because “technically” it’s the only html your app ever directly gets. Everything else is loaded via the framework.
Beyond those basic parts of a project you then build your solution. For us that meant including 3rd party JavaScript libraries, creating HTML 5 user controls, reusable html templates and utility libraries. Here is how we choose to break those down and structure them in our project :
  • js/[Library name] : We created a folder per 3rd party library we are using and placed it at the root of the js folder. we only included a few libraries so while it could have been “cleaner” to place everything in a js/libraries/[library name] structure we choose this route. Given how much WinJS provides, I am not sure you will really need to integrate very many libraries unless you choose to replicate WinJS functionality or ignore it.
  • js/Controls/ : We created a folder for our user controls, and then each user control got its own js file. To be completely honest, how things get “cut up” for reuse in the WinJS world, our controls were really made up of 5 or 10 separate User Controls, but for organizational since we logically treated everything to render a set functionality as a single “Control” and there for 1 file. For example the Dashboard in the BI app is one control even though its made up of a dashboardRepeater, dashboardPanel, kpiPanel, socialPanel, and so on and so forth.. but logically its one control (or control family if you like) and there for 1 file.. It just as easily could have been 1 file per actual user control object.. To that I would say best practice is what works for you regarding maintainability and organization.
  • js/Utils/ : Here we placed all of our utilities. In the end we really only had 1 utility file/object but it was good to have the organization in case we needed it.
  • templates/ : Creating a strategy for reuse was very important to us, by default the WinJS model is that each page has its own templates. This is great if you are not going to reuse a template between pages, but this strategy would fall apart quickly in very large projects. To that end, we created a separate folder for the HTML templates a user control needs and we created a pattern for how those controls access their templates.
All and all the structure of a HTML 5 Windows 8 Metro app is not all that different from a normal ASP.NET MVC app. Sadly that’s about where the similarities end. With this little reference we hope you will have at least a basic understanding of what Microsoft has given you when you create a new project in VS 2011. And we fully understand that this isn’t nearly enough to know what is really going on. In the coming weeks we will be writing very technical ( yummy source code level technical) articles about :
  • Page lifecycle
  • WinJS templates
  • How to build a Utilities library
  • How to build a user control
  • How to make reusable html templates for WinJS
  • How to use the WinJS Navigation service
  • CSS 3 animations and Transitions



  1. Mike May 1, 2012
  2. Russ August 28, 2012
  3. Kamlesh October 9, 2012
  4. Mike November 12, 2012

Leave a Reply to Mike Cancel reply