Today is the last day of this series, and we’re going to focus on designing Windows 8 applications today.  You might be asking yourself:

I’m a developer…why would I want to read an article about design?

I’ll tell you why.  Because we developers have been making user interfaces that look like this for decades:

The point of this article is to get you to think differently about you user interface, not just the colors and shapes that are user, but the ENTIRE EXPERIENCE.  The way pages show content.  The navigation experience.  Even page transitions.  It all matters now. Here’s more proof, if you need it.  Think, for a moment, about what an app running in Windows 7 looks like.  Any app.  Picture it in your mind.  It probably looks like this:

If you take a closer look at this diagram, there’s no indication whatsoever about what this app does.  We’ve tended to focus on how we use the app, not what the content is.  Windows 8 fundamentally shifts that idea.  Now think about a Windows 8 application in your mind.  It probably looks more like this:

In this illustration, the ENTIRE image shows content.  This means that instead of remembering how to use your app, users are far more focused on the content of your app.  This is part of the conversation we’re going to have today.  This article will be divided into several sections, and each section talks about a different part of user interface creation.  Here’s the topics we’ll cover:

• Content Before Chrome
• Using The Windows 8 Silhouette
• Navigation Patterns
• Fluid Motion
• Make Touch a Priority

That’s a ton of topics, so let’s get right to it.

Content Before Chrome

In this section, I want to focus on one of the most important lessons in this entire article:

STOP MAKING BUTTONS.

The focus of every screen of your application should be about the content.  If you’re adding buttons, you’re likely doing it wrong.  Here’s a very common scenario:

We have several sections to our application, and we want to provide an interface for our users to get to each section.  In general, most people would say that there’s absolutely nothing wrong with this interface (except that maybe those giant gray boxes should have photos in them.)  The key lesson to remember is that the entire colored block IS the button.  There’s no reason to add the circled arrow icons.  Instead, consider this:

By removing the circled arrows, we’ve made the interface cleaner by removing the clutter, we’ve provided the user with a larger touch target for their fingers on touch devices, and given ourselves less to worry about on the page.  “One button to rule them all”,” if you will.

When you desperately feel the need to add a button to the screen, ask yourself:

Could this live in an application bar?

If it can, do it.  For more on the application bar, check out Day #4.  In short, let the user tap the content instead of creating another button for them to click.  If an action can be taken on more than one item at a time, use the App Bar to provide contextual actions when multiple items are selected.

Using the Windows 8 Silhouette

It would be a dreary, boring world if every app looked exactly the same.  That considered, it is also difficult for users to learn a new interface with every application that they use.  This is where the idea of a silhouette comes into play.  Take a look at the four different application examples below.  They all present very different content in very different ways, but there’s a uniform experience about them that makes it very obvious to the user where the important content lives.

There are many ways to utilize this familiar silhouette, here are just a few examples:

All of the previous images follow a familiar format, which makes it easy for the user to figure out how to use your application, while still looking diverse enough to make your app visually unique.  The reason for all of this is because there will be learned behaviors your users will acquire simply from using Windows 8.  They’ll start to rely on the Charms bar.  They’ll start to expect that right-clicking brings up an AppBar with more options.  They’ll try pinching the screen to zoom.  Taking advantage of these silhouettes is another example of the expectations users will have about your application.

Navigation Patterns

As developers, we have a tendency to try to accommodate our users’ needs, almost to a fault.  One example of this that is rampant in both desktop applications as well as the web is this idea:

We need to allow the user to get TO any page, FROM any page.

You do NOT need to do this.  When we provide this type of functionality, we limit the amount of space that can actually be used for the purpose of the app.  Here’s an example of an RSS reader app that practices the “everywhere navigation” pattern (click to enlarge).

As you can see, an app that is dedicated to reading only uses about 30% of the screen for actual content.  We need to think about our application in a navigational scheme that makes sense for our content, which will almost always be hierarchical or flat.

Hierarchical Navigation

In this style of navigation, we work in a hub-and-spokes model, where the users’ choices move them further and futher from the home page, and using the back button allows them to return backwards through their path before choosing another branch of the tree to travel down.  Like this:

We build pages with a master/detail structure so that navigation is intuitive and simple to use.  The user should always know where they are in the app, without having to lay an elaborate trail of breadcrumbs for them.  They should be diving into deeper and deeper detail about the original choice they made.  The default News application in Windows 8 is a great example of this hierarchy.

On the home page of the app, I can scroll to the right to see a few articles from each section (Entertainment and Sports are currently shown):

Using Semantic Zoom, the user can easily see all of the categories, and jump to the one they want to read more about.

If I tap on one of the section headers on the main page (like the word Entertainment above the large photo of the woman, Lynn Shelton), I am taken to a new page that contains only Entertainment news.

Finally, and this can be done from anywhere in the app that I see an article, when I tap on a specific article, I am taken to a detail page for that item.

In each instance, there is the presence of a back button which will take me back through my previous choices.  What you don’t see, however, is the ability to jump from an Entertainment news article over to a Sports article.  In fact, there’s not even a way to get to the Sports category without using the back button.  That is, until you take a look at the AppBar for this app.

There, you’ll see that they succumbed to the need to let the user navigate quickly between sections without cluttering up the screen with all of this navigation.  The AppBar is a great way to provide some of these navigation mechanisms without taking away from the visual appearance of your application.

This is a hierarchical navigation pattern.  Learn to use it.  It will be your friend, and clear your screen of all of the navigation elements you would need otherwise.

Flat Navigation

Flat navigation is something that you see every day in your web browser.  You also see it in instant messaging apps, and other places that have similarly formatted, but somewhat unrelated content.  A picture would look like this:

When we navigate a website, we’re using this flat navigation style.  We can move forwards and backwards, but there is really no concept of branches in this format.  Since you’re likely using a web browser to view this article, I’m going to assume you know what I’m talking about.

Fluid Motion

Motion is one of those things that we never think about as developers.  We tend to focus on the important topics, like data, and never really consider how much nicer our app would look if it incorporated a little animation.

When I talk about animation, however, I’m not talking about it for visual adornment.  It’s not a decoration that you slap on your page.  Animation should be purposeful.  If you can use animation to transition between screens of your app, your user will perceive load times to be shorter, and feel that your app is faster and more responsive than it actually is.

In addition, there are a bunch of animations available to you with minimal effort.  Check out this article on Animating Your UI from MSDN.

Make Touch A Priority

A “tap” and a “click” in Windows 8 are the same thing.  It requires no effort on your part to make touch happen.  Making your click targets big enough for a finger, however, does.  Always, always, always make anything on your page that is clickable larger than 48 x 48 pixels.

Incorporate gestures where possible.  Your users will expect them.  It requires minimal extra effort, and it lets your users interact with your app the way they expect to:

In addition, it’s important to remember that because your users will be touching the screen, this also means that there are optimal places to put your buttons and content.  Generally, a user will hold a tablet horizontally, with their thumbs hovering over the two sides of the tablet.  This means your primary buttons should probably live in these regions as well.  What shouldn’t live there is your content.  If the user’s thumbs are hovering over this region of the screen, this also means they can’t see what is happening on that region of the screen.  Here’s a good rule of thumb:

Summary

In this article, we covered some of the important things you should be thinking about when you start building, and more specifically designing, your Windows 8 applications.  There are tons of additional resources at

http://design.windows.com

and you should definitely make a trip over to the site to check them out.  There are additional design patterns, UX guidelines, Adobe Photoshop templates and much more.

This article also puts the finishing touches on this lengthy series, and we want to sincerely thank each of you that have taken the time to read our words.  There are many reasons to write an article series like this, but our primary reason is that it’s an amazing excuse to dive deep into a technology stack and really understand it.  My second reason, however, is you, the reader.  Jeff and I have made our best effort to understand each of these topics thoroughly, and explain them in a “no assumptions, start from the beginning” manner.  You, our readers, bring us comments and questions that we hadn’t anticipated, and for that, we truly are thankful.

Please leave comments and questions on our articles.  These will continue to live on as excellent learning resources for developers looking to build Windows 8 apps, and your contributions only make them that much better.

Thanks.

Wow, here we are finally talking about the Store. This is really our last step ( and a very exciting one no less ) in your development process. Today we’re going to share with you some of our steps and experience in not only helping others get their apps into the store, but also submitting our own.

If you’ve gotten to this point, then no doubt, these are exciting times. Whether you’re a few code slingers at Rovio making Angry Birds or someone like me who was building an app on the nights and weekends, it’s exciting. If you’ve have an app in the Store, I would also invite you to share in the comments the things that have worked well for you, and not so well.

Microsoft announced just a few short days ago, that they’ve sold 40 million licenses of Windows 8 in it’s first month of life. I don’t know about you, but that’s a pretty big audience for some indie developer like me. The Store is our new platform for us to ship our software to.

For purposes of today, we are only going to talk about the public facing Microsoft Store. If you feel you fall outside of that scenario, say you’re an enterprise developer and might like to deploy through group policy, I would suggest start by reading the Managing Client Access to the Windows Store.

To the Store

Now to get in the store, you have to have to first be signed up as a individual developer ($49 USD) or a company ($99 USD). Once signed up, you can then start reserving app names. Now I know this might sound a bit like duh, of course, but maybe you already have an idea but just haven’t started it. Nothing is stopping you from creating your account and reserving those application names now. Now unlike all of those domain names you’ve been buying over the years and just parking until you get time, you have 1 year from the time of reservation to shipping. If you don’t release anything, then that reserved name goes back into the pool. As someone who has a few apps reserved, it’s a pretty good incentive program for me.

Pre-Certification

If for some reason you’re new to this notion of a “store” or “marketplace” concept, as developers once we finish our app we have to go through a certification process before our application will be officially published. While this may seem somewhat cumbersome, this certification process is really there for everyone’s benefit. Having been through it, the first time you submit your app the minutes can feel like hours but in the end it’s the right thing.

Of course the certification process is both automated and manual. For the Microsoft Store you as the developer have access to the same automated tools (WACK) which are used once you’ve submitted to the store. This allows you to go through the process before you’ve ever submitted addressing any potential issues.

The Windows App Certification Kit or WACK is really two different kits; one kit for Intel based processors and another one for ARM based processors. These kits are tools that you would of course install on a test system which will run through the same automated process that the Microsoft Store would do from it’s servers. The beauty about these kits you can run them on yourself before you ever submit your application to the marketplace. As I said this really helps to ensure you’ve cut down any issues long before submitting to the store, ultimately cutting down your certification time if you we’re to have any issues.

After starting the Windows App Certification Kit you have 3 different categories of apps that you can select. For our apps we would select the validate Windows Store App option. Once selected, you’ll be asked as to what application you want to validate.

Once you pick out your application, the WACK tool will start running. It will start to run a variety of tests against your application and even do things like open it, to see how long wait times are. After it’s completed, you will get a detailed report as to what was validated. Of course just like in TDD, green is good and red is bad. Below is just a snip from a failed event report.

The WACK tool provides a very detailed report as to its findings. Having said you should run it across all of the platforms you expect to run on, as your load times on a low power ARM device might be a lot longer than that of a multicore Intel machine. It’s also not a replacement for hard core testing, both manual and automated. Just saying…

It’s also true, when you submit there is still a potential for failing the certification. Now Microsoft has released a pretty good document which details a number of the most common certification failures but make sure you have read through the certification requirements such that you’re not surprised.

One of the biggest reason apps fail is certification requirement 4.1. 4.1 states that an app with the Internet Access capability checked must provide a policy policy to the Store. Of course this means you might have to setup a simple website just to contain the privacy policy required. If you’re not using the internet, just uncheck it.

TIP

All of the Visual Studio templates for the Windows Store create the shell of an app but with the internet capability.enabled. If you’re *not* using the internet – uncheck it and save yourself the hassle.

App Images

Like it or not, the first thing your potential customer will see is an image of your application  in the store. In fact, there are a number of different images your user might see depending on where the store app has placed your application. Now mind you, this is all before your potential customer has even installed it, so make sure you have some great store appeal is a good thing.

During day 1 when we talked about the blank application, we discussed a number of different images you needed to include in your application. These were things like the store logo, small tile, wide tile and so on.

As it turns out, when you try and submit your application, you’re not done with the image creation process. At the time of submission you will be asked for a number of new logos that will be used by the store specifically. They are not part of your app’s package, they are images uploaded directly to the store. Specifically these images are your billboard images as well as screenshots of your application.

Making logos is clearly an art form. To help make things a bit easier, a friend of mine build a number of Photoshop templates around these Store submission graphics. I would encourage you to check them out as they could save you a number of hours.

Whatever you do, please, please, PLEASE replace all of the default images. Now I do not know who wrote Backgammon Gold nor am I not trying to place a dig on all the hard work they’ve done. But, I would never spend $4.99 on something where someone hasn’t even taken the time to replace the default Visual Studio images. I’m not saying, but I’m saying. Clearly their rating proves my point.

Making Money

Your monetization model is clearly something that only you can determine. While charging outright for the application is one way, there are many creative ways as well. The minimum price someone can charge for an application is $1.49 USD with increments starting at .50 USD.

While charging upfront is a clearly an easy way to make some coin, it’s not the only and it might not be the best depending on your scenario. What about offering the user a time-limited trial, or a feature-limited trial? Remember the goal is to make money and getting user to test drive your app isn’t a bad thing. There are a number of studies written about how trials have a much higher conversion rate that ones without trials. You don’t buy a car without driving it first, why not test drive an app?

Another very popular mechanism for making money is an ad supported model. This is nothing more than putting some ad container in your applications such that you’re displaying ads to your customers. While you can use any ad platform you wish (assuming they adhere to Microsoft’s certification requirements ) Microsoft offers an ad sdk from Microsoft Advertising which will get you easily up and running on Microsoft’s platform.

Lastly offering the ability for an in app purchase shouldn’t be out of your reach either. Using a game app example, one could offer more levels once the user got to a particular point in their journey just for a bit more money. I personally think this is a pretty interesting scenario as it gives you the ability to get people using your app, but offers them the ability to purchase something more full featured.

Now when you’re making most of the money, the Microsoft Store is doing all of this legwork for you, hosting the bits, transitions, currency conversions etc.  As you might expect there is a cut that Microsoft needs to take just to offer such support. For your first $25k Microsoft will charge you a 30% fee, but after your app makes $25k, that fee will drop to 20%. These are just a few of the items you will find in the app developer agreement.

Creating the package(s)

Creating the packages for the store is a painless process. There is basically two reasons to create a package, sideloading or WACK testing OR to upload to the store. The difference between the two different packages is really one is signed with your developer account whereas the other isn’t.

To get started, Project –> Store –> Create App Packages… As you can see, the first dialog box you’re presented with is in fact the two different options we just mentioned.

If we’re building a package for the Store. Then our next step is to select what our app name was in the store such that we can associate things correctly.

Regardless of what direction we choose first the next step in the process is picking what platform we want to build for. These will be the packages we will later either sideload or upload to the store.

And once created all of your glory should look something like:

For more information about sideloading please see this article: http://technet.microsoft.com/en-us/library/hh852635.aspx

Ready to submit

Submitting your application is mostly just a one page web form you’re required to fill out. These are things like, description, search keywords, release date and so on. The Windows Store team has done an excellent job of documenting everything, so I won’t rehash that here but rather ask you to please read their article.

App Update(s)

You’ve pushed and now you need to fix up a bug. Well, thankfully you’ve already been through the entire process already. Now it’s just a matter of creating a new release and changing anything that might be now applicable. Oh yea, of course you would need to update the new package too.

Summary

Honestly submitting your app into the store is the easy part. All of the planning and development that’s been done to this point has really been the hard part. While you have a plan in mind about how you may make money, don’t be afraid to think outside of the box and try a few different things. You never know what will net you the best results.

Tomorrow, we’re going to talk about our last day in this series which is focused on design.

After 29 days, we’re finally going to talk about the Application Lifecycle or Process Lifecycle management ( aka PLM ). Now before you close the browser thinking I will just skip this one, please don’t. We’re going to talk about how your application will run, when it runs, and what events are there for us to plug into. Ultimately we’re looking at the management of the different states our application can be in on a user’s device.  Here’s an illustration (image from MSDN):

As web developers this process lifecycle thing might feel a bit foreign to us. Of course our web applications and\or sites have a lifecycle but our word is a pretty stateless world. Now having said that, we’ve always had to deal with bouncing between servers, network volatility and overall session management. The same principals are somewhat true in our native app. Windows makes the call as to when we should live, and we should be ready for that.

The reason that this is important to us as developers of Windows 8 applications is because we want to provide a seamless user experience in our apps.  When a user presses the Windows key on their machine, and leaves your app, you want to make sure you save or preserve their data in some way, so that when they come back, it’s all still there.

I Thought Windows Handled This Automatically??

Yes and no.  By default, if you run a Windows 8 application, leave it, and come back, it will automatically be exactly where you left it.  However, if you leave it, and then open 6 or 7 more applications, it’s likely that the operating system is going to suspend your application, or even terminate it.  Thankfully, there’s a couple of great mechanisms we can use to manage this.

Recognizing Your App Has Been Suspended

According to Microsoft, “an app can be suspended when the user switches away from it, *or* when Windows enters a low power state.  Most app stop running when the user switches away from them.”  There’s a few things you need to know about how your app will end up in a suspended state:

• Your app “might” be suspended.  For the simple app I’ve built for this article, I’ve never seen it enter a suspended state on its own.
• Generally, when the system runs out of resources, this is the time your app will enter a suspended state.
• When you leave an app to use another, Windows will wait a few seconds before suspending it, just in case you were planning to return to it quickly.

So, if you’re anything like me, you’re probably wondering how we are going to write and test some code that only occurs when Windows feels like making it happen. Thankfully, there’s some tools for that.

Now to talk about this whole lifecycle thing, I’m purposefully going through things somewhat backwards, this will make more sense when we turn to talking about what happens when our application launches. Most likely you’d started your application development from one of the Visual Studio templates. Assuming so, then will see a bunch of boilerplate code in your default.js file. This boilerplate code is basically some of the simple hooks for PLM as well as getting your app started up.

Before our application transitions into another state and event called oncheckpoint will get called. This *an* opportunity ( not the only one, you can always save too ) for you to do something like possibly save the users session state or something like their navigation history

app.oncheckpoint = function (args) {
    args.setPromise(finishOff());
};

function finishOff() {
    return new WinJS.Promise(function (complete, cancel, progress) {
        WinJS.log && WinJS.log("app.oncheckpoint called.", "31 days", "status");
        complete();
    });
}

Looking at the code above, you can see I we have created a function that will in turn get executed when the checkpoint event is fired. In our code we are  creating a promise that will in turn tell Windows there is some async activity occurring and things shouldn’t end until complete has been called. Having said that, Windows isn’t going to wait around forever either. Windows will wait a few seconds ( 5 seconds I believe ) before it says, “sorry dude, I am outty you’re just taking to long”.

In WinJS there is an object called sessionState. This sessionState object is a great place for you to keep some of your users session data like navigation history ( as the Navigation template in fact already does ). The beauty of this sessionState object is Windows will in fact manage the persistence and recreation of that object and its associated data. While less work for us, we will still have to take the data from that object and re-create our own objects if necessary.

Checkpoint is called when you application is going to be suspended. If  you app is suspended there are no more notifications that you’ll receive, so this is the place to take care of business while you still have a chance.

Recognizing That Your App Is Resuming

In this case, we’re going to simply add an event handler that will execute when the resuming event is fired.

var webUI = Windows.UI.WebUI.WebUIApplication;

webUI.addEventListener("resuming", onResume, false);

function onResume() {
    WinJS.log && WinJS.log("app resuming", "31 days", "status");
}

On Launch

This is where things can get a bit more complicated. In the code below, I have listed out all of the different execution states and I am logging that to the console window. Just like we did with the blank app on day one, this gives us some history as to when these things will get fired and whatnot. This is our place where we can do things like reconstitute objects depending on the state the applications was in before ( if we care of course ).

var app = WinJS.Application;

app.onactivated = function (args) {
    WinJS.log && WinJS.log("app.onactivated", "31 days", "status");

    if (args.detail.kind === activation.ActivationKind.launch) {
        WinJS.log && WinJS.log("Activation Kind === Launch.", "31 days", "status");

        switch (args.detail.previousExecutionState) {

            case activation.ApplicationExecutionState.terminated:
                WinJS.log && WinJS.log("previousExecutionState terminated", "31 days", "status");
                break;

            case activation.ApplicationExecutionState.running:
                WinJS.log && WinJS.log("previousExecutionState running", "31 days", "status");
                break;

            case activation.ApplicationExecutionState.suspended:
                WinJS.log && WinJS.log("previousExecutionState suspended", "31 days", "status");
                break;

            case activation.ApplicationExecutionState.closedByUser:
                WinJS.log && WinJS.log("previousExecutionState closedByUser", "31 days", "status");
                break;

            case activation.ApplicationExecutionState.notRunning:
                WinJS.log && WinJS.log("previousExecutionState notRunning", "31 days", "status");
                break;
        }

        args.setPromise(WinJS.UI.processAll());
    }
};

To look at a concrete example of this. We can look no further than the Navigation App template found inside of Visual Studio. Here we will see no only are we saving our navigation history on checkpoint to the sessionState object but when our application launches we are making sure we 1. reconstitute it as well as navigate them back to the place they had left off.

app.addEventListener("activated", function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
        } else {
        }

        if (app.sessionState.history) {
            nav.history = app.sessionState.history;
        }
        args.setPromise(WinJS.UI.processAll().then(function () {
            if (nav.location) {
                nav.history.current.initialPlaceholder = true;
                return nav.navigate(nav.location, nav.state);
            } else {
                return nav.navigate(Application.navigator.home);
            }
        }));
    }
});

app.oncheckpoint = function (args) {
    app.sessionState.history = nav.history;
};

Now how in the world do I test this PLM stuff?

Because this is a tough scenario to make happen automatically, there are tools inside Visual Studio that allow us to simulate these states in our application.  First, make sure that you’ve opened the Debug Location toolbar in Visual Studio.

Once you’ve added that toolbar, it’s as simple as choosing one of these three options:

• Suspendwill immediately put your application in a suspended state.  This will also fire your suspended event handler before it stops running.
• Resumewill obviously resume your app from a suspended state.  If your app is not suspended, nothing will happen.
• Suspend and shutdown will simulate what happens when Windows terminates your application.  The suspended state will happen first, followed by a complete shutdown of your app.

Summary

In short, we want to provide a seamless experience for our users, so keep the lessons in this article in mind.  Don’t overdo it, though.  Saving unsaved data for a user is a convenience, so unless you think it will be important, don’t exhaust yourself trying to anticipate everything the user might need. Also be mindful of performance, I don’t think we want to persist to disk ever single time a character changes in a textbox.

In games, if the user leaves, and they have to replay a level, so be it.  You don’t have to remember that they were jumping over that block to make it a great experience.  Remember which level they were on is probably enough.

If you’d like to download my working sample that uses the code from this article, click the icon below:

Tomorrow, it’s time to ship your awesome to the store.  See you then!

Today we’re going to dive pretty deep into the world of Push Notifications. In short, push notifications is a mechanism for some external thing to send a notification to the user in a variety of different forms. Now, this isn’t anything new to us. On Day 9 we introduced Live Tiles, Day 10 – Toast Notifications and Day 11 Lock Screen Applications. These were all methods in which we could notify the user and allow them to take action if they so desired. When we explored each of these methods we we’re sending notification from within our application or some background process. Push notifications is really the last piece in that notification puzzle and maybe one we should have ordered a bit different in our series. Hindsight is always 20/20 right?

Before we dive into Push Notifications I want to set the stage a bit. I am going to assume a web like connected scenario. I am going to create a simple website. This website will be the thing that we ultimately send notifications to our apps on the different clients. The server will determine Who, What, When will get those notifications. Of course for demonstration purposes we’re going to cut out some of that “business logic” such that we can just exercise the ole internet pipes. At a 50k foot level this all looks something like this:

What is?

Now, what really is Push Notifications? Well Push Notifications is really some cloud infrastructure to manage and facilitate the sending of notification for applications who subscribed to receive them. These notification can be a tile, toast, badge and raw notifications ( any or or all of them ). They are actually determined from the server and then sent through to the WNS server which will then send it along to the appropriate client. The notification work the same way as we saw in our previous articles but are just sent from a outside source, such as the little website we will build.

These notifications are managed through what is called the Windows Push Notification Services or WNS. This is the piece of cloud architecture that resides in the middle of everything. The WNS server is the thing in which our client and server interact with to send and receive notifications. Having said that our client *will still have* to send its endpoint to the website, such that it knows who would like to receive a notification.

The basic steps are such:

• Before we can do anything we need to be registered with the store. This will gives us our keys such that we can authenticate with the WNS server.
• Our app needs to register a channel with the WNS server. The result of a successful registration is a URI. It will look something like:
  • https://bn1.notify.windows.com/?token=AgYAAAAe%2buFwf2o%2fz1nJdCAMwzf4bO9u3QXmrW4L73WAPNpsP8DpbfSmHIuRpoOIJKusNKxTvkXo4tposjhTPkbLNnsvXXzCh8eIMpyTPXOFNStcZ0FR7kQZHf86MwL4Ga5f7vg%3d
• Once we have the URI we need to give it to our cloud service so it knows which clients want communication
• Our cloud service ( in our case our website ) will have to have some knowledge about our secret WNS keys. These keys are what our site will use to authenticate to the WNS server. Once authenticated it can then post notification to that URI the client gave him.

Image curiosity of MSDN: http://msdn.microsoft.com/en-us/library/windows/apps/hh913756.aspx. For more information on the Push Notifications process, please see the Push Notification Overview on MSDN.

The Setup

To start, we need to get our app registered. Now at the time of writing this there seems used to be two different methods.

• Windows Store ( dashboard )
• Live Connect Developer Center

Now the Windows Store is the official way that you will want to register your application. The Windows team has put together a nice set of documentation on how to get registered so I won’t rehash that here. Just check out the article How to authenticate with the Windows Push Notification Service (WNS). The first part of the article walks through in great detail just how to register your application in the store and so forth.

The Live Connect Developer Center used to be a place where you could also register an application and get all all of the goods but that seems to have recently changed. I tell you this because there are a number of blog posts out there with outdated information ( as one day this will be too ). Yes, you can still create an application there but you will be missing some essential pieces of information ( like the SID ) needed to do the proper authentication. Having said all this, any application you create in the Windows Store will appear listed here and with some of that information.

Why do we need to register anything to do Push Notifications? Security. This registration process does two things for us. 1. It will identify our application to not only the Store so we can submit our wonderful app but also identify itself to the WNS servers correctly. 2. Provides us an  identity to use outside our of our application ( aka server side ) which can authenticate via OAuth with our WNS servers, this is our SID and the Secret. If your secret was to ever get compromised, you can always regenerate it from either the Store ( which really takes you to Live ) or the Live Connect Developer Center. Below the top image is our results from the Store while the bottom image is the Live Connect portal page.

Ok, now you have your app registered in the store, the next thing to do is associate the solution with the Store. What that really means is changing all of that great information that we haven’t talked about in the Packaging tab of our appxmanifest. But rather than just entering it all by hand we can just go to Project –> Store –> Associate App with the Store. This will do all the nasty for us.

- tip -

One thing that has caught me once or twice, was the generation of our certificate. Every application has a unique certificate associated with it. When you create a new blank template Visual Studio will actually create a temporary certificate for you, something like App29_TemporaryKey.pfx. This certificate will be associated to your app in the packaging tab of the appxmanifest file. Now when you associate your app with the store, not only will it update that Packaging tab with new information but you should *also* get a new certificate that will be associated with the store.

Now I have personally seen this not happen and no matter how many times I tried to associate my application, I couldn’t seem to get the Store certificate.  As it turns out there was an easy fix. Make sure you somehow didn’t mess up your own temporary certificate. If you’re actually missing your pfx file ( say you deleted it or excluded it from source control ) you can recreate a temporary one from that Packaging tab in the appxmanifest. Once you have your certificate correctly associated, then re-associate with the store and you should in fact get your official key.

The Client

Now that our app is registered, and we have the keys ( SID and Secret ) to our castle, the first thing our application will need to do is register a channel with the WNS server. Our application *has* to be the thing that will tells the WNS servers that we in fact want notifications. In return our WNS server will tell our application what our actual Push Notification URI will be. Once we have that endpoint we can pass it along to our cloud services such that we can start receiving notifications.

Ironically, the client part is the easy part. The only thing we need to do in our application is register ourselves with the WNS server and pass along our URI. As we saw from our conversations on tile, toast, badge notifications we really didn’t have any work to do to receive notifications. Meaning we didn’t need to setup OS level events to catch and pop dialog boxes, unlike our devices conversation where we did ( at least have to register ourselves ).

When our application launches, we can register ourselves with the WNS servers.

var notify = Windows.UI.Notifications;
var push = Windows.Networking.PushNotifications;
var net = Windows.Networking.Connectivity;

notify.TileUpdateManager.createTileUpdaterForApplication().clear();
notify.BadgeUpdateManager.createBadgeUpdaterForApplication().clear();

var profile = net.NetworkInformation.getInternetConnectionProfile();

if (profile.getNetworkConnectivityLevel() === net.NetworkConnectivityLevel.internetAccess) {
    push.PushNotificationChannelManager.createPushNotificationChannelForApplicationAsync()
        .then(function (channel) {
            document.querySelector("#uri").innerText = channel.uri;

            /* 
            this would be the place to post your uri to your cloud service.
            */
        })
}

Above, I am just clearing all notifications ( it’s a demo after all ), then I will check for internet access. If so, we can then register for Push Notifications and pass along our URI. In our case I am just going to put the URI on the screen for us to see.

- another tip -

Internet Access. By default, the Visual Studio template has the Internet Access Capability already checked. This is in fact a capability we need for Push Notifications, so no immediate work is required by us.

Having said that, if we have Internet Access Checked then when we try to publish our app to the store we will also be required to provide a privacy policy. See section 4.1.1 for more information. Without that you will be rejected.

You’ve been warned.

The Server

Our server is where all the magic will happen. To send a notification it really just takes a few simple steps. Authenticate with the WNS servers, create your notifications and then send them along. Since we’ve already covered how to create tile, toast, and badge notifications I will not cover that but rather I would like to introduce a library which will make all of this pretty dead simple. It’s called WNS Recipe. While I could walk you through the OAuth Authentication process with the WNS servers, why?

WNS Recipe, makes all of this very simple. As a fun little experiment, I created a simple webpage on 31 Days to test Push Notifications. you plug in your information and it will send you a tile and toast notification. Sure I could go a lot further but for now, it will at least test the pipes. Below is the majority of that code.

var sid = Request["sid"];
var secret = Request["secret"];
var uri = Request["uri"];
var message = Request["message"];

WnsAccessTokenProvider tokenProvider = new WnsAccessTokenProvider(sid, secret);

var title = "31 Days";
var subText = message;

var tileNotification = TileContentFactory.CreateTileWideText01();

tileNotification.RequireSquareContent = false;
                        
tileNotification.TextHeading.Text = "31 days";
tileNotification.TextBody1.Text = message;
    
var tileResult = tileNotification.Send(new Uri(uri), tokenProvider).ErrorDescription;

if (!string.IsNullOrEmpty(tileResult) ){
    <h1>tile result: @tileResult</h1>
}

var toastNotification = ToastContentFactory.CreateToastText02();
toastNotification.TextHeading.Text = "31 Days";
toastNotification.TextBodyWrap.Text = message;

var toastResult = toastNotification.Send(new Uri(uri), tokenProvider ).ErrorDescription;
            
if (!string.IsNullOrEmpty(toastResult) ){
    <h1>toast result: @toastResult</h1>
}

The first major step is creating an instance of what is called the token provider. To create it, we need that SID and Secret that we received when we registered our application. They will look something like this:

• SID: ms-app://s-1-15-2-1368837720-1402593261-3975316331-362590900-1199389545-3359712884-900627795
• Secret: 7PQ5upGa7rrYHM+fKe60Am81lU+mca/7

Once we have our token provider in place, then we just need to create the notifications we would like to send. WNS Recipe makes this easy, as it’s wrapped all of the types of notifications in some nice factories. If you remember there are a number of different templates for each category of notification. WNS Recipe makes dealing with those templates a breeze.

Then when we’re ready to send, we just send to that URI our app gave us, using our token.

Sounds t0 easy

Sounds to easy Clark, I call BS. Ok, well, maybe you got me. Push Notifications is actually really easy. Here is what can be a pain.  Managing those URIs the hundreds of millions of customers will be sending you.

Yes, your services in the cloud will need to have some endpoint that your app can post it’s URI to. Then it will need to manage if that URI has expired ( yes they can change and expire ), who do you send to and when, and so forth. So yes, sending the notification is easy. Just how you leverage them is a different story.

But wait, there is more. Today I talked through the raw details of sending Push Notifications. At the time of writing this Microsoft has recently released something called Azure Mobile Services. Azure Mobile Services is a great utility for application developers. Azure Mobile Services will actually setup and host a great deal of this plumbing that I just mentioned. Now Jeff spent his day 28 working through that approach. This is something I would highly suggest taking a read through as well.

Hopefully between the two of us, you have a more than complete picture on how you can leverage Push Notification in your application.

Summary

Push Notifications is very cool. There have been some recent studies done where applications are claiming push notification driving over 60% of interaction with its application. Regardless, having a facility to entice the users to come back is always a good thing.

If you’d like to download my working sample that uses the code from this article, click the icon below:

Tomorrow, we’re finally going to talk about Process Lifecycle Management.  See you then!

As someone who’s never written a game, or even an app which required such physics like heuristics, it’s become clear to me that getting the data from the sensor is really the easy part. I think it’s also pretty clear that no one sensor might ever be used alone but rather in partnership with the others. All of the devices really complement each other in someway and depending on what you’re building, while simple to work with they are essential to the overall experience you’re trying to create for your customer.

Today, finishes off our series of device sensor conversations that you might find in your new Windows 8 device. Today we’re going to take a very brief look at a device called the inclinometer. So what really is the inclinometer? Well, chances are you’ve probably been taken somewhere in a plane. When a plane turns, it actually exhibits all three axis to accomplish it’s turn. To make the plane turn in a nice smooth manor, we have three simple steps ( at least for the pilot that is ):

• Pitch the plan in the direction of travel, by adjusting the aileron’s ( assumed in opposite directions to pitch the plane ). This is our Y axis or the Pitch.
• Adjust the elevator either up ( or down ). This helps pull the nose of the plane up ( or down ) helping to point the noise in the direction of the desired turn. This is our X axis or the Roll.
• Adjust the rudder. With the rudder we can make the play turn side to side. If you have ever landed in a windy situation and the plan felt sideways, it’s because it was, and they we’re using the rudder to cock the rear of the plan sideways. This is our Z axis or the Yaw.

Image courtesy of MSDN: http://msdn.microsoft.com/en-us/library/windows/apps/jj155767.aspx

While the physical example is nice, how does that translate to our computers in hand?

Image courtesy of MSDN: http://msdn.microsoft.com/en-us/library/windows/apps/jj155767.aspx

As you can guess, working with the inclinometer is just like working with our other sensors.  Just a few simple steps and we’re getting data:

• Initialize the Sensor.
• If it’s available,
  • create a readingchanged event handler.
  • In the event handlers, grab the data from the sensor and write it to the screen.

Here’s my the entirety of my code and it looks well super duper scary similar to that of the other sensors.

    var _pitch, _yaw, _roll, _timestamp;

    function onReadingChanged(e) {
        _pitch.innerText = e.reading.pitchDegrees.toFixed(2);
        _yaw.innerText = e.reading.yawDegrees.toFixed(2);
        _roll.innerText = e.reading.rollDegrees.toFixed(2);
        _timestamp.innerText = e.reading.timestamp;
    }

    function getDomElements() {
        _pitch = document.querySelector("#pitch");
        _yaw = document.querySelector("#yaw");
        _roll = document.querySelector("#roll");
        _timestamp = document.querySelector("#timestamp");
    }

    function startInclinometer() {
        var inclinometer = Windows.Devices.Sensors.Inclinometer.getDefault()

        if (inclinometer) {
            var minimumReportInterval = inclinometer.minimumReportInterval;
            var reportInterval = minimumReportInterval > 16 ? minimumReportInterval : 16;
            inclinometer.reportInterval = reportInterval;

            inclinometer.addEventListener("readingchanged", onReadingChanged);
        }
    }

    app.onloaded = function () {
        getDomElements();
        startInclinometer();
    }

Once again, no real surprises here. We get to our data in the same basic was as we did with the other sensors. Wire up to an event, which will fires on an desired interval giving us the X, Y, Z values. No real magic here other than the software you’re building to consume it.

Summary

Today we briefly looked at getting data from our inclinometer. Working with each of these sensors is pretty much the same but what you do with them is entirely up to you.

If you’d like to download my working sample that uses the code from this article, click the icon below:

Tomorrow, we’re going to look at the Inclinometer.  See you then!

As a kid I was always amazed at a gyroscope. I would find anything I could to balance that thing on. I always though physics was very interesting but like anything if you don’t constantly use it, you start to forget bit’s and pieces of it. As we’ve seen over the past few days, the machines of today have started to become an interesting physics experiment. Rather than just some toy of days past we can leverage these sensors to accomplish some very interesting features.

Today, we are taking a look at yet another sensor that we might find in a Windows 8 device: the gyrometer.  The gyrometer measures the angular velocity or rotational motion. The gyrometer can easily compliment the accelerometer to create one very advanced game controller. When used together, the accelerometer measuring the linear motion and the gyrometer measuring the rotational force, you can make things like a pretty wicked game controller.

Working with the gyrometer is the same as working with our other sensors. Just a few simple steps and we’re getting data:

• Initialize the Sensor.
• If it’s available,
• create a readingchanged event handler.
• In the event handlers, grab the data from the sensor and write it to the screen.

Here’s my the entirety of my code and it looks scary similar to that of the other sensors.

    var _x, _y, _z;

    function onReadingChanged(e) {
        _x.innerText = e.reading.angularVelocityX.toFixed(2);
        _y.innerText = e.reading.angularVelocityY.toFixed(2);
        _z.innerText = e.reading.angularVelocityZ.toFixed(2);
    }

    function onShaken(e) {
        _wasShaken.innerText = e.timestamp;
    }

    function getDomElements() {
        _x = document.querySelector("#x");
        _y = document.querySelector("#y");
        _z = document.querySelector("#z");
    }

    function startAccelerometer() {
        var gyro = Windows.Devices.Sensors.Gyrometer.getDefault()

        if (gyro) {
            var minimumReportInterval = gyro.minimumReportInterval;
            var reportInterval = minimumReportInterval > 16 ? minimumReportInterval : 25;
            gyro.reportInterval = reportInterval;

            gyro.addEventListener("readingchanged", onReadingChanged);
        }

    }

Once again, no real surprises here. We get to our data in the same basic was as we did with the other sensors. The real magic is your software that leverages the data it’s measuring.

Summary

Today we briefly looked at getting data from our gyrometer. Working with each of these sensors is pretty much the same but what you do with them is entirely up to you.

If you’d like to download my working sample that uses the code from this article, click the icon below:

Tomorrow, we’re going to look at the Inclinometer.  See you then!

Today, we are taking a look at another sensor that we might find in a Windows 8 device: the accelerometer.  With the accelerometer, we can measure the movement of the user’s machine. If you’re looking for more information about what exactly an accelerometer is check out this. With an accelerometer we can do things like detect the orientation of the device and even sense if a device is falling.

The X axis runs horizontally across the device.  The Y axis runs vertically across the device.  The Z axis runs immediately through the device, from front to back.  Here’s an image to help illustrate, using a Windows Phone as the example (courtesy of http://www.andybeaulieu.com/):

In simpler terms, we’re measuring the g-forces applied to those three axes.  Because of this, when we lay a Windows 8 tablet flat on a table, we get a Z axis value of –1, because there is one “g” (one unit of gravity) exerting itself on the negative size of the Z axis.  In the same way, if we propped our device up (similar to the phone in the photo) so that the bottom of the device is sitting on the table, we would get a Y axis value of –1.

Working with the accelerometer is very similar to working with the other sensors. Just a few simple steps and we’re getting data.

• Initialize the Sensor.
• If it’s available,
  • create a readingchanged event handler.
  • create a shaken event handler
• In the event handlers, grab the data from the sensor and write it to the screen.

Here’s my the entirety of my code and it looks scary similar to that of the other sensors.

var _x, _y, _z, _wasShaken;

    function onReadingChanged(e) {
        _x.innerText = e.reading.accelerationX;
        _y.innerText = e.reading.accelerationY;
        _z.innerText = e.reading.accelerationZ;
    }

    function onShaken(e) {
        _wasShaken.innerText = e.timestamp;
    }

    function getDomElements() {
        _x = document.querySelector("#x");
        _y = document.querySelector("#y");
        _z = document.querySelector("#z");
        _wasShaken = document.querySelector("#shaken");
    }

    function startAccelerometer() {
        var acc = Windows.Devices.Sensors.Accelerometer.getDefault()

        if (acc) {
            var minimumReportInterval = acc.minimumReportInterval;
            var reportInterval = minimumReportInterval > 16 ? minimumReportInterval : 25;
            acc.reportInterval = reportInterval;

            acc.addEventListener("readingchanged", onReadingChanged);
            acc.addEventListener("shaken", onShaken)
        }
    }

    app.onloaded = function () {
        getDomElements();
        startAccelerometer();
    }

Again, no real surprises here. We get to our data in the same basic was as we did with the other sensors.  Now the accelerometer sensor did introduce a new event called shaken. This event fires when a user shakes their machine In writing this article I was using the original build tablet for testing. I shook the machine but sadly couldn’t seem to get the event to fire. Just when I started to think I didn’t have a sensor which supported that event, I’d tossed down the machine down onto the couch and all of the sudden it fired. Turns out, I just wasn’t holding it right.

Summary

Today we briefly looked at getting data from our accelerometer. Working with each of the different sensors is all very similar.  Ultimately, how you use this data is where your real creativity comes in and I’m looking forward to hearing how you’ll use it in your app.

If you’d like to download my working sample that uses the code from this article, click the icon below:

Tomorrow, we’re going to look at the Gyrometer.  See you then!

Today, we are taking a look another one of the sensors we might find in a Windows 8 device: the Light Sensor.  With the Light Sensor, we can determine the brightness of the light around the user’s machine, and help to accommodate things like contrast, brightness, and other values that would make our app easier to read in high and low light.

I let Jeff put together yet another horribly produced video to show you how a light sensor works, and what kinds of values we can expect. To make this application work, we’re going to follow a very similar pattern to the one we used yesterday for the Compass sensor.

• Initialize the Light Sensor.
• If it’s available, create a ReadingChangedevent handler.
• In the event handler, grab the data from the sensor and write it to the screen.

Here’s my the entirety of my code and it looks scary similar to that of the compass.

var _light;

function onReadingChanged(e) {
    _light.innerText = e.reading.illuminanceInLux.toFixed(2);
}

function startLightSensor() {
    var lightSensor = Windows.Devices.Sensors.LightSensor.getDefault();

    if (lightSensor) {
        var minimumReportInterval = lightSensor.minimumReportInterval;
        var reportInterval = minimumReportInterval > 16 ? minimumReportInterval : 16;
        lightSensor.reportInterval = reportInterval;

        lightSensor.addEventListener("readingchanged", onReadingChanged);
    }
}

function getDomElements() {
    _light = document.querySelector("#light");
}

app.onready = function () {
    getDomElements();
    startLightSensor();
}

There’s nothing surprising about getting this data, but I was surprised to see how diverse the values on different machines (that were sitting next to each other) could be.  For instance, my Qualcomm ARM device (the one featured in the video above) generally rated the room I’m currently sitting in around 59 lux.  My Samsung tablet, however, which is a Windows 8 Pro device, rates this room around 42 lux.  Finally, my Surface RT device says this place is about 115 lux.

This is likely due to the accuracy and quality of the light sensor in each device, but in general, they’re really not that far apart on the scale of lux values.  Here’s an example from the Wikipedia article on Lux.

As you can see, even 100 lux is still a pretty dim value.  Just flipping the lightswitch on in my office jumped my sensor values up closer to 175.  Using the chart above, however, you should be able to create “ranges” of values that behave differently depending on the brightness of the light available.

For example, if you recognize that the user is in a low-light environment, you might switch their display to show a dark background and white text, because that is easier to read in that kind of light.  In a bright room, you might want to switch to black text on a white background.

In either case, you now know how to recognize the data from the light sensor, and use it effectively in your app.

Summary

Today we talked about the Light Sensor, and how it can be used to alter a user’s interface to make it more readable.  Ultimately, there are dozens of creative ways to leverage the lux data in your applications, and I’m looking forward to hearing how you’ll use it in your app.

If you’d like to download my working sample that uses the code from this article, click the icon below:

Tomorrow, we’re going to get involved with a more robust sensor, the Accelerometer.  We can use this data to determine the rotation of the user’s device.  See you then!

Today, we’re going to talk about the compass. While we’ve talked about one sensor in the past (Orientation Sensor), this is the first article of many to come focused just on the supported sensors. As a web developer this is really something completely new for me as it’s really outside the bounds of what we might typically do. Having said our web world is changing ever so fast.

Now if you’ve ever done any phone development then this isn’t anything new as our phones ( especially the ones on the shelf today ) have had these capabilities. If you have done any Windows Phone development previously, you might have read Jeff’s article on the Windows Phone compass, which provides magnetic and true north headings, as well as X, Y, and Z rotation data.

In Windows 8 this is different and provides significantly less data from the compass sensor.  In fact, we only get the values related to our heading, with no consideration for rotation data.  In addition, you’re going to find that since we’re building apps for Windows 8, there’s going to be a wide variety of sensors we’ll encounter. Now having said that, we can get rotation from the orientation sensor which we’ve already talked about on day #2. I would also check out this quick start on retrieving the quaternion and rotation matrix if you’re interested more in rotation.

Ok, on with the show.

Writing Some Code to Access the Compass

The compass, like many of the sensors we will cover over over the next few days, the compass is actually very accessible and easy to use.  With a few lines of code, and one event handler, we can gather rich data from our user’s device very quickly.  Here’s is all the code I needed to to start getting real-time data from my simple compass app:

    var _trueNorth, _magNorth, _timestamp;

    function onReadingChanged(e) {
        var newReading = e.reading;
        _timestamp.innerText = newReading.timestamp;
        _magNorth.innerText = newReading.headingMagneticNorth.toFixed(2);
        
        if (newReading.headingTrueNorth != null) {
            _trueNorth.innerText = reading.headingTrueNorth.toFixed(2);
        }
    }

    function startCompass() {
        var compass = Windows.Devices.Sensors.Compass.getDefault();

        if (compass) {
            var minimumReportInterval = compass.minimumReportInterval;
            var reportInterval = minimumReportInterval > 16 ? minimumReportInterval : 16;
            compass.reportInterval = reportInterval;

            compass.addEventListener("readingchanged", onReadingChanged);
        }
    }

    function getDomElements() {
        _trueNorth = document.querySelector("#trueNorth");
        _magNorth = document.querySelector("#magNorth");
        _timestamp = document.querySelector("#timestamp");
    }

    app.onloaded = function () {
        getDomElements();
        startCompass();
    }

To explain the code above, in my startCompass() method, I try to initialize my Compass object, and if it’s not null ( meaning there is a compass sensor on the machine ), I create an event handler for each time that the reading of the compass changes.  (Unless the user’s device is sitting completely still, it’s likely you’ll consistently get new readings.)  In the onReadingChanged event handler, I then assign our three values, HeadingMagneticNorth, HeadingTrueNorth, and Timestamp to an element I declared in our markup.

That’s it.  As you probably saw, however, most of the sensors you’re going to encounter will not provide ( as mine didn’t either ) a HeadingTrueNorth value, so relying on the HeadingMagneticNorth is going to be a more reliable value for you.

Finally, both of the Heading values are measured in degrees relative to their associated heading.  This means that you’ll see a range of values from 0 to 360, with zero being the value headed directly north.

Summary

This was a quick but exhaustive look at the Compass in Windows 8.  We saw that you can easily access the Compass data by using an event handler, but that we receive a limited amount of data from this sensor, and your mileage will vary from device to device.

If you would like to download the sample app featured in this article, click the icon below:

Tomorrow, we’re going to look at the light sensor, and how we can manipulate our application to take advantage of knowing if the user is sitting in a light or dark room.

It’s day Day 22. We’ve crawled all around Windows 8 but today we get to talk about a feature that seems to lack any press; Play To. I said yesterday that today we would talk about how to send the pictures and videos to another machine and this is exactly what we’re going to do; with Play To.

Let’s set this up some. I am an unusual customer. I have many many computers, smartphones, internet connected TVs, XBOXs and so on. I’ve even been in the long process of home automation. Basically if it needs electricity, I probably want it. But I am also a family man, who takes a lot of pictures, videos and whatnot. When you have all this great tech why not use it to its fullest potential?

And then there is software. I love software. I love the fact that we can make something that solves the needs for us to do something else. I love that I can just sit down and create something simple like On Time and hopefully make a presenters life just a little bit easier.

The place that’s always fallen down for me was the integration between the two. If’ you’ve ever tried to dip your toe into the home automation space then you know exactly where I am coming from. It’s like someone threw up electronic parts in a room and left you a flat head screwdriver to try and get them all to work together.

Now Play To isn’t the savior, but it’s  a great start. It brings together a very important gap we’ve today, media sharing.  By media, I mean, images, audio, and video. Media today is a mess, from the makers, to the providers to just my own organization of my music and pictures. I can say we’re not going to fix that here but maybe we can send that mess around to your different devices AND applications.

This is the first article where we’re going to need multiple devices to effectively test this. Today I am just going to use two different machines, the one I am doing development on and the Samsung Build Tablet. That doesn’t mean there isn’t an array of hardware out there that you could use to test. Microsoft has a great little site that will list the different compatible devices.

Before we get into the coding, I want to make sure you have a way to test this functionality.  In Windows 8, open the Windows Media Player app.  (You know, the app that you haven’t opened on a Windows machine in 10 years?  Yeah, that one.)

Select the “Allow remote control of my Player…” option.  You’ll be asked to confirm your choice, just to make sure this is actually what you want to do.

Once you’ve confirmed this choice, your machine will be registered on your network as a device available for Play To content.  OK, let’s get to coding, so that we can see what this really means.

Send To

The easiest way to think about Play To is just as another device. If you remember back to how we interfaced with the printers in Devices Charm, this is more of the same. The first thing we need to do is create our Play To Manager.

var _playToMgr = Windows.Media.PlayTo.PlayToManager.getForCurrentView();

Once we have that, then we need to registered for the sourcerequested event. This is the magic sauce that registers your app with Windows telling it we have some content that we can send along.

_playToMgr.addEventListener("sourcerequested", sourceRequestHandler, false);

With our event registered we just need to implement that handler. This will get fired when the user activates the Devices Charm. When our event fires we have to tell it what element we want to send along.

function sourceRequestHandler(e) {
    if (e)
        e.sourceRequest.setSource(_audioElement.msPlayToSource);
}

Ironically, that’s it. Here is the majority of the JS file I wrote to demonstrate the send. Clearly happy path, error free scenarios.

var _audioElement,
        _playToMgr = Windows.Media.PlayTo.PlayToManager.getForCurrentView();

function sourceRequestHandler(e) {
    if (e)
        e.sourceRequest.setSource(_audioElement.msPlayToSource);
}

function getDomElements() {
    _audioElement = document.querySelector("#audioTag");
}

function wireEventHandlers() {
    _playToMgr.addEventListener("sourcerequested", sourceRequestHandler, false);
}

app.onloaded = function () {
    getDomElements();
    wireEventHandlers();
}

Let’s Play

My UX is simple, it’s one audio element wired to my podcast, Developer Smackdown.

When I select the Devices Charm you will now see my tablet shown below.

After selecting that. my tablet will start playing the audio.

And, if that isn’t trippy enough. Hit pause on your Played To device. You will see the pause change on your source machine. So you have full fidelity controls between the two devices.

- play to tip -

If you switch networks, say you go to a McDonalds to work for a while, maybe even write an article. You have to go through that brief setup we did at the start of this article ( at least for Windows Media Player ).

Receiving Content

Ok, now for the other way around. I honestly don’t know what is more exciting, the fact that you can send stuff or receive stuff. Believe me, the app ideas are rolling.

Receiving content is for the most part just as easy. We can break up the steps into 5 different parts:

• create the receiver
• set some properties on the receiver
• wire the event handlers for the receiver
• wire the event handlers for the element ( in our case an audio control )
• start

To create the receiver we just need an instance of of the PlayToReceiver.

var _receiver = new Windows.Media.PlayTo.PlayToReceiver();

Next we have some properties we can set. I think the properties are self explanatory.

_receiver.friendlyName = "31 Days Play To Receiver";
_receiver.supportsAudio = true;
_receiver.supportsVideo = false;
_receiver.supportsImage = false;

With the properties set the next step is the most tedious, creating all of the event handlers. These event handlers are the things that map the events from both sides and your code is basically just a pass through. For example. If a user hits pause on the destination device, you need to map pause from that element back to the receiver so you can actually pause your element. The same is true the other way. Pause on the source, we hit pause on the destination and so on.

_receiver.addEventListener("sourcechangerequested", receiver_SourceChangeRequested);
_receiver.addEventListener("pauserequested", receiver_PauseRequested);
_receiver.addEventListener("currenttimechangerequested", _receiver_CurrentTimeChangeRequested);
_receiver.addEventListener("mutechangerequested", receiver_MuteChangeRequested);
_receiver.addEventListener("playbackratechangerequested", _receiver_PlaybackRateChangeRequested);
_receiver.addEventListener("playrequested", receiver_PlayRequested);
_receiver.addEventListener("stoprequested", receiver_StopRequested);
_receiver.addEventListener("timeupdaterequested", receiver_TimeUpdateRequested);
_receiver.addEventListener("volumechangerequested", receiver_VolumeChangeRequested);

_audioReceive.addEventListener("durationchange", audioPlayer_DurationChange);
_audioReceive.addEventListener("ended", audioPlayer_Ended);
_audioReceive.addEventListener("error", audioPlayer_Error);
_audioReceive.addEventListener("loadedmetadata", audioPlayer_LoadedMetadata);
_audioReceive.addEventListener("pause", audioPlayer_Pause);
_audioReceive.addEventListener("playing", audioPlayer_Playing);
_audioReceive.addEventListener("ratechange", audioPlayer_RateChange);
_audioReceive.addEventListener("seeked", audioPlayer_Seeked);
_audioReceive.addEventListener("seeking", audioPlayer_Seeking);
_audioReceive.addEventListener("volumechange", audioPlayer_VolumeChange);

I’m going to spare you the detail of the functions, just go look at the sample code. It’s just mapping code, a line or two each.  Now we just need to hit start the receiver so we can broadcast on the network.

_receiver.startAsync().done(function () {
    // good place to think about locking the display on.
});

And just like that, you’re now streaming back and forth between devices on your network. Seriously cool stuff that I would encourage you to play around with.

Summary

I’m really excited about the potential that Play To has. It open a unique scenario for media between devices and applications. Now what we do with it, is a different story. I could go on, but why? You should just start playing with it.

If you would like to download the sample code that was discussed in this article, click the icon below:

Tomorrow, it’s off to more devices.

Today, it’s all about devices, ok well really just one device; the camera. As web developers media has been one thing which has taken us on a wild rollercoaster. From browser plugins to native specs in the browser, hang on cause it hasn’t come to the station. It also shows just how awesome, and yet how ever changing some if the individual specs contained within HTML5 really are. Regardless, we need our media!!!

For those who have been playing the HTML5 game at home, you may remember that the Device API was killed this past February. This was the standard put in place to do things like capture audio and video from our things like our webcam as well as a number of other items. This is a complicated space no doubt but have no fear, we have a new spec focused just on media, called Media Capture and Streams or navigator.getUserMedia(). Unfortunately it’s one of those specs which is very early in it’s life and isn’t very adopted across all of the browsers. If you would like to know more about it check out a great article on getUserMedia on HTML5 Rocks.

Now, let’s talk about Windows 8. On day 14, we talked about geolocation.  We had two different implementation options; use WinRT or use the standard html5 spec. Both were similar, achieving the same goal. But getUserMedia is different, it’s not supported yet in the browser, so we have to turn to WinRT.

This clearly poses some interesting questions, at least for me. Things like feature detection and polyfills have long been the preferred way to to make sure the browser the client was using something that we knew how to adapt to. Now in Windows 8, do we need to think about feature detection and polyfills across hardware? Maybe not, if you just writing for Windows, but what if you’re writing code for both the browser and Windows? Time will tell, patterns will develop, and like anything the context of what your doing has the greatest impact.

Now that I have gotten off topic, let’s get back on. Media Capture. WinRT. Let’s GO.

Start

This shouldn’t come as a surprise to you, but where do you think we’re going to start. RIGHT-O the appxmanifest. We need to check Webcam.

Now that we have declared we’re going to use the Webcam, let’s start snapping some pictures. Like in days past, I’ve just created the simple blank template with a couple of elements; specifically a button and a div to dump our results into. Let’s look at the button handler.

var _capture = Windows.Media.Capture;
var captureUI = new _capture.CameraCaptureUI();
captureUI.captureFileAsync(_capture.CameraCaptureUIMode.photo)
    .then(function (capturedItem) {
        // now what ?
    }
);

We start by creating a new instance of the WinRT CameraCaptureUI. In Windows 8, we actually get to leverage the built in Camera UI to do all of the hard work and we just interface with that. Similar to how printing worked yesterday. Once we have created the instance then we just need to pop the UI and add a promise to our statement that will execute when the user has finished taking a picture. You should also notice we’ve passed in what “mode” we would like our camera in. For now we’ve selected photo. We could have selected any of the following; photo, video or photoOrVideo. Once we run it, we’re presented with a dialog box asking the user if we can in fact use the webcam.

Once we allow that, we will be presented with the Camera Capture UI.

Yes I am sitting in a restaurant while writing this part and the camera has appeared to have added another chin. Let’s change mode to video just to contrast a bit. I’ve cut some of code just for display purposes.

captureUI.captureFileAsync(_capture.CameraCaptureUIMode.video)
    .then();

By just changing that and rerunning you will notice we seem to no longer have the required access. Why, what happened? By looking in the settings of the application and looking at it’s permissions we get some insight.

Since we switched to video, we now have access ( or lack thereof ) to the microphone. Because of that we need to go back to our package.appxmanifest and declare we will use the microphone as well.

Declaring the Microphone and rerunning we get prompted again. This time for both, webcam and microphone access:

And now if we look at our permission of the application.

You will notice we have both permissions. I went through this in detail for a few different reasons. 1. I hope you don’t sit there beating your head against the wall late at night trying to figure out why your video isn’t working when it’s just a declaration in the app. 2. Access is an all or none here. The access isn’t webcam and\or microphone.

Back to the code.

.then()

Ok so up until this point we’ve fire the Camera UI but that’s really it. Once the user takes a picture, what happens. Well our promise will fire.

captureUI.captureFileAsync(_capture.CameraCaptureUIMode.photo)
    .then(function (capturedItem) {
        if (capturedItem) {
            /* Storage Item */       
        }
        else {
            /* user cancelled */
        }
    }
);

When our promise fires we’re given a StorageFile. This pictured captured is actually automatically save to the application temporary storage. You can see this from my watch window here.

Since what we’re given was a StorageFile we can just work with it from there. Below I am just going to create a url for the StorageFile, create a new img element and start appending it to my less than awesome app.

var photoBlobUrl = URL.createObjectURL(
                      capturedItem,
                      { oneTimeOnly: true });

var imageElement = document.createElement("img");
imageElement.setAttribute("src", photoBlobUrl);

document.querySelector("#result").appendChild(imageElement);

Just like in printing, we also have the ability to influence some of our settings both seen in the Camera UI as well as the the output. This is done by setting the CameraCaptureUIPhotoCaptureSettings ( no that wasn’t a bad joke ) found on your instance of the CameraCaptureUI class. By default jpegs were saved let’s change that to pngs.

captureUI.photoSettings.format = _capture.CameraCaptureUIPhotoFormat.png;

We can also influence how Camera UI works. Below I am going to change the aspect ratio of the crop window to force it to 4:3

captureUI.photoSettings.croppedAspectRatio = { height: 4, width: 3 };

I think you get the point.

Motion Pictures

Ok enough of my terrible pictures which will end up getting indexed and used somehow when I’m least expecting it. Let’s move onto motion pictures. Thankfully we’ve really already seen this because it’s pretty much exactly more of the same. Let’s go all in and capture some video.

var captureUI = new _capture.CameraCaptureUI();

captureUI.videoSettings.format
    = _capture.CameraCaptureUIVideoFormat.mp4;

captureUI.videoSettings.allowTrimming = true;

captureUI.videoSettings.maxDurationInSeconds = 15;

captureUI.videoSettings.maxResolution =
    _capture.CameraCaptureUIMaxVideoResolution.highestAvailable;

captureUI.captureFileAsync(_capture.CameraCaptureUIMode.video)
    .then(function (capturedItem) {
        if (capturedItem) {

            var url = URL.createObjectURL(
                capturedItem,
                { oneTimeOnly: true });

            var imageElement = document.createElement("video");
            imageElement.setAttribute("src", url);
            imageElement.setAttribute("autoplay");
            imageElement.setAttribute("controls");

            document.querySelector("#result").appendChild(imageElement);
        }
        else {
            document.querySelector("#result").innerText = "User Cancelled"
        }
    }
);

I have bolded the items above that we’re different and honestly nothing much. Given that I’m not going to spend much time on it. We pop the same Camera UI but with a different mode. We can set things like we did before but this time they are related to video. Can you guess what class that’s on? CameraCaptureUIVideoCaptureSettings

Let’s look at a few of the settings. First, we can specify between MP4 video or WMV.  You won’t see a difference between the two formats until you try to share that video with other systems and platforms.  MP4 is far more widely used than WMV, but it’s also a larger format, so that’s worth considering.

Second, I’ve turned on “AllowTrimming” which allows the user to select the segment of their recorded video that they would like to use.  They’ll get a user interface similar to this, where they can drag either end of the video using the white crop circles:

Third, I’ve specified a MaxDurationInSeconds, which limits the maximum length of video a user can provide.  If they record more than that duration, they’ll be able to select which 30 seconds (or the duration you specify) that they’d like to use.  I can see this being useful for businesses like Match.com where people make profile videos, but they don’t want them to run on forever.

Finally, I’ve also specified a MaxResolution.  This allows us to manage the resolution that the user can record with, which can also help with the final file size we end up with.  You have four choices:

Otherwise, we end up with a very similar result to our camera efforts.  This time I created a video element and set a few attributes on it. The results? Well I will save that for Hollywood.

Summary

In short, capturing photos and videos from your user’s camera is very easy, as well as customizable.  Most of the complicated UI is handled directly by Windows 8, so we don’t have to worry about most of the interaction with the user.  I’ve provided screenshots and a video in this article, but the best way to get a feel for this process is to work with a real application.

Jeff also put together a nice little video of him showing off how the Camera UI in action.

If you would like to download the sample code that was discussed in this article, click the icon below:

Tomorrow, we’re going to take a look at how to send these pictures somewhere with PlayTo.

Today, it’s all about creating paper. Yes folks, the joys of printing. I know for some this might feel very 1999 but as it turns out, people are still using paper. There is not doubt that over the past 10 years we’ve seen this landscape change with things like the cloud and tools like OneNote or Evernote, but I think it’s safe to say we’re still printing.

For me, printing from the applications we’ve built has been nothing short of a royal pain. It’s always been that feature which was expected but never planned for and if it was, there was never really any “real” thought put into it. Sad I know, I hope you’re not in that boat too.

While I was thinking out how to write this article, it dawned on me. Print should really be thought of like any UX screen you might design for your application. This may be obvious for some but I had a few ah-ha moments here. Print is really just another medium. It’s paper with a different resolution. Sure we have to walk over to the printer and physically grab it, but unlike our mobile and tablet industries we can at least predict the resolution we plan to support. Because of that, treat it no different than you would any other UX screen you might design.

Our purpose for today isn’t to help you design what your print screens could look like but rather how can we take data and prepare of for print. Warning now, ugly UX for both paper and screen.

Now, no real paper was used in the making of this article, as it turned out I ran out of ink.

Start

Printing is simple. I won’t lie, that statement was one I never thought I would make. I’ve been on { cough: wpf projects of yesteryear } where printing, while possible was an just a nightmare. Thankfully that was yesteryear and we can all move on.

To start exploring this, I created the same simple Blank App project we’ve done for the past 20 days. Fire up your app and open the charms menu. From there, select the Devices Charm.

As you might expect the the Devices Charm is our contract into the physical devices we can interact with. At this point ( and we haven’t done anything yet ) you can see all we really can’t do anything. Let’s register for printing.

var _printManager = Windows.Graphics.Printing.PrintManager,
    _printView = _printManager.getForCurrentView();

_printView.onprinttaskrequested = function (eventArgs) {
    eventArgs.request.createPrintTask("31 Days", function (args) {
        args.setSource(MSApp.getHtmlPrintDocumentSource(document));
    });
};

Now let’s re-run and select the Devices Charm again.

Now, our devices charm is stacked full of options that I can print to. Let’s select Microsoft XPS Document Writer and my actual printer just to see what we get.

While my print view is the same, my options for the devices are clearly different based upon the capabilities of that device. Regardless, we’ve printed! Now my current layout is really nothing close to special, so what if I had 90 paragraphs of Bacon Ipsum?

You can see above, our layout automatically adapted. The 90 paragraphs that I added was actually just the content of one <p> element. This translated into 10 pages of content with even margins on the bottom, or did it?

For those who’ve worked with printing in the past, know that’s pretty cool. And while this is all fine and dandy, chances are my screen layout isn’t really what I want to print.

Layout

So far our print has been a direct representation of our screen. And while our app is nothing more than a centered header and a paragraph it’s a terrible usage of paper. For now let’s continue to assume this app is awesome and the UX has been designed by the greatest of greats.

But we can safely say this layout just doesn’t work on paper. What we really want to do is reformat things so they are better suited to the medium of which they would be displayed on, in this case our paper. it would be much better here if we moved the title to at least the top of the page. Well guess what, CSS to the rescue.

<link href="/css/print.css" rel="stylesheet" type="text/css" media="print" />

There is nothing special about adding another stylesheet except here we’re going to leverage the media attribute: media=”print”. With this new CSS stylesheet in place, when the user selects to print Windows will use that stylesheet for the view. Now all I did in my stylesheet is readjust my CSS Grid and the text alignment. The result:

Clearly that works so much better for a piece of paper. But couldn’t I just use a media query because that seems so much more HTML5-ish? Yes, you can do the same. This works exactly like things do in the browser.

@media print {
    body {

        width: 100%;
        height: 100%;

        display: -ms-grid;
        -ms-grid-columns: 1fr;
        -ms-grid-rows: 1fr;
    }

    #content {
        -ms-grid-column: 1;
        -ms-grid-row: 1;

        text-align: left;
    }

}

Of course this is nothing more than what we’ve already done in our Websites today.

Adding Print Button

So far we’ve used the built in Devices Charms to send something to a device that claims it can print. While it’s recommended to always use the Devices Charm there might be a scenario in which your application needs to have it’s own print button. If this is in fact the case, we can easily do so by showing the same print UI that the Devices Charm would.

To do so, I’ve added a button to my screen which will fire the handler you will see below.

_printThis.addEventListener("click", function () {
    Windows.Graphics.Printing.PrintManager.showPrintUIAsync();
}, false);

Now to show the PrintUI your screen will still need to register with the Print Manager, like we did at the start of this article. After adding our print button this lead to an unfortunate byproduct. We now have that button element displayed on our screen. meh..

In designing our UX we’re really going to want to think about our screens, the content and how we plan to transform it. Thankfully the movement to a more responsive web has been leading us down this path for sometime now.  But let’s get rid of that button for our print view. We can simply update our media query or our separate stylesheet to remove that element.

@media print {
    /* .... */ 

    button {
        display: none;
    }
}

Options

You have options!! Let’s start by looking at what’s called the standard options. These are the options that are display to the right hand side of the preview of your document. You can see I have highlighted them in red below.

By default the same three properties are always presented ( unless you clear them out ); Copies, Orientation and Color Mode. Now we have the ability to change that. Let’s assume we only want to present the Color Mode option. I simply clear out my list and add back in the ones I want.

_printView.onprinttaskrequested = function (eventArgs) {
    var printTask = eventArgs.request.createPrintTask("31 Days", function (args) {

        printTask.options.displayedOptions.clear();
        printTask.options.displayedOptions
            .append(_printing.StandardPrintTaskOptions.colorMode);

        args.setSource(MSApp.getHtmlPrintDocumentSource(document));
    });
};

Now, regardless of what I have chosen to display on the standards settings menu when the user chooses the detailed settings menu they will be presented with it regardless.

We can also choose what we feel the default setting should be. Maybe we really wanted the Color Mode to be set to grayscale rather than color.

printTask.options.colorMode = _printing.PrintColorMode.grayscale;

Of course we can also add to the standard list as well. Let’s say you want the default options + duplex printing. Rather than clearing out the default list you would just add to it.

printTask.options.displayedOptions
    .append(_printing.StandardPrintTaskOptions.duplex);

Now with all of this, the only option supported by your device are the ones which will get shown. A great way to see this in action is to select the XPS Document Writer rather than you printer. Regardless of what you may have just set, it’s not there for XPS.

What about custom printing features? Well that currently isn’t supported by HTML5\JavaScript like it is in XAML\C#.

Other Events

As with any page, it’s important to understand our navigation model and when we should be loading and unloading our events. The same applies with printing as well. There are 4 events as part of the PrintTask; Completed, Previewing, Progressing and Submitting.

I am not going to go through all of the events but I do want to look at completed since it’s the one place we can see if we were actually able to print.

_printView.onprinttaskrequested = function (eventArgs){
    var printTask = eventArgs.request.createPrintTask("31 Days", function (args) {

        printTask.oncompleted = printCompleted;

        /* .... */
    });

function printCompleted(eventArgs) {

    switch (eventArgs.completion) {
        case _printing.PrintTaskCompletion.failed:
            break;
        case _printing.PrintTaskCompletion.submitted:
            break;
        case _printing.PrintTaskCompletion.abandoned:
            break;
        case _printing.PrintTaskCompletion.canceled:
            break;
        default:
            break;
    }    
}

As you can see we register for the event once our Print Task is created. Then we can just switch over the result and react as we see fit. Honestly it should be as you would expect. That’s a good thing.

Summary

Today, we stepped into the devices contract, specifically our ability to print. I’ve tried to break down printing in such a way that it was simple knowing full well, the complexity of printing comes from our use cases. Transforming the pixels on the screen, to a piece of paper is no easy task and it takes a thoughtful design to be effective. That isn’t a simple feat and it should be treated just like any other feature on your development project. Unfortunately that isn’t something we can help you with.

If you would like to download the sample code that was discussed in this article, click the icon below:

Tomorrow, we’re going to take a look at capturing images from your Camera. See you then!

Today, we are going to look at another invaluable tool in Windows 8 development, the File Picker.  There are millions of ways to use the File Picker, but when you boil it down, you’re going to need to get files from the user’s computer for something.  This article will show you how to do it.

Start: package.appxmanifest

As with all of the different mechanisms we’ve used to interact with the user’s system, we need to start with updating our package.appxmanifest file.  Since we are going to be both opening files AND saving files in this article, we need to add both of those Declarations to our file.

For the File Open Picker, you’ll start with a form that looks like this:

You’re expected to make one of two choices:

• Supports any file type.  By checking this box, you are declaring that you could access any file type from your application.
• Supported file type.  You can also specify which file types you want to open, so if your app only opens Excel files, for example, you could list “.xls” as your file type.

For this demo, you can just select “Supports any file type.” I want to do so, so you can see all the files on your system regardless.  The same process can be done for the File Save Picker, which offers you the same choices, like this:

Getting a File from Your User’s Machine

This article is going to build a progressively more complex app for selecting files from a user’s machine.  We’ll start getting just one file, then multiple files, and then multiple files of only a specific file type (.png).  Most of the code for each example is identical, so we’ll focus on what is the “new” code in each step.

For selecting a single file from the user’s hard drive, we are going to start with the FileOpenPicker object.  This is the object that will open the File Picker dialog for the user, help them select one or many files, and return them to us.  It has many options, and we’ll work our way through all of them.  For selecting a single file, of any type, the code starts quite simply:

var _pickers = Windows.Storage.Pickers,
    openPicker = new _pickers.FileOpenPicker();

openPicker.fileTypeFilter.append(".png");
openPicker.suggestedStartLocation = _pickers.PickerLocationId.picturesLibrary

openPicker.pickSingleFileAsync().then(function (file) {
    //do something awesome here
});

You’ll notice that we have to set a fileTypeFilter when we create a FileOpenPicker.  You are not allowed to provide a wildcard, or just ignore the filter.  You have to provide at least one, but you can also provide several, which means you can list 8-10 common file types (especially when you’re looking for images on the user’s device, because they could be PNG, JPG, JPEG, GIF, BMP, etc.) To do so, rather than appending just one fileType we can just replace all of them like so:

openPicker.fileTypeFilter.replaceAll([".png", ".jpg"])

When you run this, your user will see an interface that looks like this:

This is the File Picker interface, and once the user selects a file, it will be returned to your application as a StorageFile, which we have worked with in several of the previous articles in this series.

Next, we might have a good idea as to where the user should start looking for the files they would want to open in your app.  Maybe it’s their Photos collection, or Music.  We can specify one of 8 locations on their computer:

So, to get the File Picker to open in one of these locations, you need to add one line of code to your method, so that it looks like this:

openPicker.suggestedStartLocation = _pickers.PickerLocationId.picturesLibrary;

This time the File Picker will launch directly to the location you’ve specified (in my example, it is the Pictures Library):

The last option we can manipulate relates to how the File Picker will display the files.  Simply use the ViewMode property of the FileOpenPicker object, like this:

openPicker.viewMode = _pickers.PickerViewMode.list;

Your options are limited to List or Thumbnail, but they look distinctly different.  Thumbnail ONLY shows a square image representing the file.  List shows an icon as well, but also shows some of the metadata for the files.  Here’s a look at the same folder with each view (click to enlarge):

List

Thumbnail

Retrieving Multiple Files From Your User’s Computer

Sometimes, we want to grab more than one file at a time.  In this case, we can use a different method call on our FileOpenPicker object.  This time, we’ll use the pickMultipleFilesAsync() method.

var _pickers = Windows.Storage.Pickers,
    openPicker = new _pickers.FileOpenPicker();

openPicker.fileTypeFilter.replaceAll([".png", ".jpg"])

openPicker.pickMultipleFilesAsync().then(function (file) {
    //do something awesome here
});

So, more or less, there’s very little difference between selecting one or multiple files from a code perspective.  We do receive a collection of StorageFile objects rather than just one, but that should be expected when we’re enabling multiple files to be selected.

What is different, at least from what I can tell, is HOW the user can select multiple files.

As you can see from the image above (click to enlarge), not only can we select multiple files, but we can also see that there is a “basket” of sorts at the bottom of the File Picker interface.  This shows a list of the files that the user has selected.  What it also enables, however, is a way for a user to select multiple files at once, from completely different folders.  Your users will be able to select a few files from one folder, and a few files from another, and they’ll all be provided to your application at once, without your user having to make multiple trips to those folders.  This is an absolutely awesome feature that should not be overlooked.

In our final section of this article, let’s look at how we can use the File Picker to also save files to a user’s machine.

Saving a File To Your User’s Hard Drive

One of the related operations we may want to use is to save a file to your user’s machine.  This is different from what we talked about on Day #8 of this series, where we were saving files internal to our application.  In this instance, we are saving a permanent file that will continue to live on the user’s machine, even if our app is uninstalled.  If your files are unusable by other apps, this is likely NOT the way you’d want to store your files.  I generally recommend saving files like this for file types that could be opened by a variety of applications.  To do this, it looks very similar to our FileOpenPicker, but it’s now a FileSavePicker.

The other difference with this situation is that we are writing data to the user’s hard drive.  This means we have all of the other hassles that come with it.  Files can be open already, they can be edited by other apps, or even deleted as we’re working with them.  So we will first launch the File Save Picker to determine where the user wants to save their file (as well as what file type and name they want to give it.  This looks like this:

And here’s what the code looks like to make this entire process happen:

var savePicker = new _pickers.FileSavePicker(),
    _pickers = Windows.Storage.Pickers;

var savePicker = new _pickers.FileSavePicker();

savePicker.fileTypeChoices.insert("Plain Text", [".txt"]);
savePicker.fileTypeChoices.insert("31 Days", [".31"]);
savePicker.fileTypeChoices.insert("Excel", [".xlsx"]);

savePicker.suggestedFileName = "31DaysOfWindows8";
savePicker.suggestedStartLocation = _pickers.PickerLocationId.picturesLibrary;

savePicker.pickSaveFileAsync().then(function (file) {
    //yea do awesome here
})

In this case, you can see that the beginning of our code sample doesn’t look that different.  Instead of filters, we can add FileTypeChoices which function as the different formats our user might want to save their file.  The choices I’ve included don’t really make much sense together, but it helps to illustrate that you can specify any file types (or types) in this list. I also added a suggestedFileName to help guide the user as to what we think the file should be called.  This is all at your full control.

In addition, once the user has selected a location and name for their file, we’re not done.  If they actually returned those values to use, our next step is to actually write the file to the drive itself.  Let’s crawl into the promise and see just how we would save it off.

var _pickers = Windows.Storage.Pickers,
    _fileManager = Windows.Storage.CachedFileManager,
    _fileIO = Windows.Storage.FileIO,
    _updateStatus = Windows.Storage.Provider.FileUpdateStatus;

savePicker.pickSaveFileAsync().then(function (file) {
    if (file) {
        _fileManager.deferUpdates(file);
        _fileIO.writeTextAsync(file, "file contents").done(function () {
            _fileManager.completeUpdatesAsync(file).done(function (updateStatus) {
                if (updateStatus === _updateStatus.complete) {
                    //saved
                } else {
                    //opps
                }
            });
        });
    } else {
        //user cancelled
    }
});

Inside our if statement, we first check to make sure we actually received a file. We then use the deferUpdates() method to prevent any additional edits to the file that we’re working with.  They will be “deferred” until after our operation is complete.  Next, we write the contents of our file.  Finally, we commit those changes using the completeUpdatesAsync() method.  This is where all of the work is actually completed.

You’ll find that if the file already exists, you’ll also get prompted with a “Replace the existing file?” dialog box.

Ultimately, that’s all it takes to save a simple file to the user’s system.  For more complex operations and file types, you’re going to want to explore the FileIO class.  You can read more about that on MSDN.

Selecting a Folder on the User’s Machine

The last topic I want to cover in this article is also very related to the others: selecting a folder from the user’s machine instead of a specific file.  This is great for allowing the user to choose a default save location for the future, or perhaps a place for you to look for files in the future.  What’s great about this process is that once the user has selected a folder, we can save it as our default folder, and we are granted explicit rights to read and write to/from this folder in the future without having to request future access.  Here’s how we do it.

var _pickers = Windows.Storage.Pickers,
    _fileManager = Windows.Storage.CachedFileManager,
    _fileIO = Windows.Storage.FileIO,
    _updateStatus = Windows.Storage.Provider.FileUpdateStatus;

var folderPicker = new _pickers.FolderPicker(),
    accessCache = Windows.Storage.AccessCache;

folderPicker.fileTypeFilter.replaceAll([".txt", ".31"]);

folderPicker.pickSingleFolderAsync().then(function (folder) {
    if (folder) {
        accessCache.StorageApplicationPermissions.futureAccessList.addOrReplace
            ("PickedFolderToken", folder);
    }
});

As you can see, all of this code look very familiar.  However, if we confirm that an actual folder was returned to us, we can save this to the StorageApplicationPermissions.futureAccessList as a place we have been granted permission to use.  Saving it this way, and referring to it in the future will limit the number of times you have to ask your user for permission to save a file to their system.

Summary

Today, we looked at several different ways to help our users interact with the files that live on their machine.  We saw how to open single and multiple files, save files back to the hard drive, and even select default save locations for future use.  You’ll likely find yourself using these methods over and over in your apps, so this is an important lesson to learn.

If you would like to download the sample code that was discussed in this article, click the icon below:

Tomorrow, we’re going to take a look at another common feature you’re likely to run into: Printing.  We’ll look at how to communicate with a user’s printers, as well as how we register with the system to make printing even easier.  See you then!

Today, we are going to look at a couple of cool features in Windows 8: File Associations and App Contracts.  With file associations, we’ll look at both sides of this Windows 8 feature:

• Registering our app with Windows 8 as an app that opens files of a certain type, like .png, or a custom extension, .31days.
• Empowering our app to suggest a list of compatible applications when our user tries to open a file that our app doesn’t support, like an .xls file.

Finally, we’ll also discuss some of the other ways our application can register with the user’s system, including things like AutoPlay.

Registering to Open Certain File Types

There’s going to be times that we want to have our user open files of a certain type in our application.  Maybe we are creating an image editor, so no matter what type of image format the user’s files are in, if they’re a common image type, we should be able to open it.  Perhaps we’re building an XML editor that consumes .xml files.  Maybe you just created a new extension like I did for On Time and you want to have it registered. Regardless, we want to register our app with the user’s system, so that when they get a prompt like this:

We want to make sure that our app is in this list when a user opens files appropriate for our application.  To do this, it’s as simple as making some simple changes to our package.appxmanifest file.  Open the file, and choose the declarations tab.  From the “Available Declarations” selection list, choose “File Type Associations,” and click Add.

You will see that it fills the screen with a new form for specifying the file associations you would like to register your app with.  By default, it has a few red Xs that you will need to address.

For this sample, I am only going to pick one file type, and one we will make up.  We shall call it 31, it seems fitting.

The first is Display Name. This is the name that shows up as the type. Next I associated the logo that I also want to show up as well. You can use any icon you’d like, but they do have a square aspect ratio, so I chose my smallLogo.png file which has the same ratio. Simple enough, see below.

The last property value that we need to set it Name. Name is just a name for the set of extensions you are listing here.  The reason that we can have different sets of extensions is because you might want your app to act differently depending on the file type.  At the bottom of the form, you can specify the entry point for your application for this set of files.  If it’s an JSON file, that you want to pre-load information.  If it’s an image, perhaps you’d rather take them to an image editing page, or just attach it to an email.  That’s up to you.

Once you’ve done that, you’re basically done. 

Run the application once, to install it on your system. At this point thing are registered and you’re ready to roll. If you notice above our custom file is now associated and if we click on it it will open up our application. Of course our application has no clue what to do with it, but nonetheless our application is open open.

Now Do Something

Ok our app opened, now what? First let’s just quickly look at the contents of my .31 file so we know what we’re working with.

{"days": [
    {"day":"1",     "title":"asdf"},
    {"day":"2",     "title":"asdf"},
    {"day":"3",     "title":"asdf"},
    {"day":"4",     "title":"asdf"},
    {"day":"5",     "title":"asdf"},
    {"day":"6",     "title":"asdf"},
    {"day":"7",     "title":"asdf"},
    {"day":"8",     "title":"asdf"},
    {"day":"9",     "title":"asdf"},
    {"day":"10",    "title":"asdf"}
]}

I am cheating a bit and just using some JSON that I want to later bind using Knockout.js. To hook into our app getting called we want to tie into our app’s activation. The Visual Studio templates already have a number of things shelled out for us around the Application Lifecycle. We simply need to extend it checking to see if the activation was a file rather than something else.

args.detail.kind === activation.ActivationKind.file

We will do that with a simple if statement. If it’s true, then in our case here all I want to do is grab the file, read it’s content and then bind the data to the screen. The important part here isn’t that I am using Knockout.js and dumping something on the screen but rather us getting activated and getting to the necessary data.

var app = WinJS.Application;
var activation = Windows.ApplicationModel.Activation;

app.onactivated = function (args) {

    if (args.detail.kind === activation.ActivationKind.launch) {

        /* ... */

        args.setPromise(WinJS.UI.processAll());
    }

    if (args.detail.kind === activation.ActivationKind.file) {
        Windows.Storage.FileIO.readTextAsync(args.detail.files[0])
            .then(function (contents) {
                var myObject = JSON.parse(contents);
                ko.applyBindings(myObject);
        });
    }

};

You can take a further deeper look at how this works in my sample.

Opening a File In Another App

Sometimes, your application just can’t open every single file type.  For example, Microsoft Outlook is really good at accepting images, text, and files, but if you’ve ever tried to open an Excel file attached to an email, you’ve probably noticed (and come to expect) that the file gets opened in Excel, not Outlook.  We want to provide that same functionality to our users.  To do this, we are going to explore the Windows.System.Launcher class.

In our first simple example, we’re just going to launch an Excel file without any options or settings.  The system will use the default app to launch our file, without any choice or warning.

var _launcher = Windows.System.Launcher,
    _current = Windows.ApplicationModel.Package.current;

var excelFile = "data\\sampleData.xlsx";
_current.installedLocation.getFileAsync(excelFile)
    .then(function (file) {
        _launcher.launchFileAsync(file)
            .then(function (isSuccess) {
                if (isSuccess) { /* Rock on Garth! */ }
                else { /* failWail */ }
            });
    });

As you can see in this first example, it’s pretty simple.  We call _launcher.kaunchFileAsync(), and pass it a StorageFile object.  Sometimes, however, you might want to warn your user that you are going to be launching another piece of software, so that they get to decide if that’s really what they want to do.  In this case, we can create a LauncherOptions object, and provided that as part of our launchFileAsync() call.  Like this:

var _launcher = Windows.System.Launcher,
    _current = Windows.ApplicationModel.Package.current;

var excelFile = "data\\sampleData.xlsx";
_current.installedLocation.getFileAsync(excelFile)
    .then(function (file) {

        var launchOptions = new Windows.System.LauncherOptions();
        launchOptions.treatAsUntrusted = true;

        _launcher.launchFileAsync(file, launchOptions)
            .then (function (isSuccess) {
                if ( isSuccess ) { /* Rock on Garth! */ }
                else { /* failWail */ }
            });
    });

When we do this, an alert pops up on the screen letting the user know that another application is being opened.

Finally, there may be a time where you want your user to be able to select the app that they will open a file with.  In this case, we want to bring up the same box that appears when a user selected “Open With…” in the previous section.  To do this, we just set another option: displayApplicationPicker.  If you want to modify the position of this dialog box you can do that as well with a little more work, but it’s very similar to what we did on Day #16 with context menus. If you don’t specify a location, however, it will launch the dialog box centered on the user’s screen.  Personally, I prefer how this looks to having it closer to the control the user clicked, but I understand what the Windows team is trying to do. 

So there you have it.  How to launch a file in a separate application from your own.  In the final section of this article, we’re going to briefly look at App Contracts, and how we can make our apps available in other lists for our users.

Using App Contracts for Good

When reading this article, some developers will think that it’s a good idea to register their app for every possible file extension, because it will keep their app and logo in front of their users as often as possible.

PLEASE DON’T DO THAT.

That rule applies to App Contracts as well.  Don’t abuse them, especially if you aren’t actually providing the functionality required.  This will be reviewed when you submit your application to the store, so it will be discovered.

Account Picture Provider

You can declare this functionality if you can provide the ability for the user to create a new Account Picture in Windows 8.  You get to the menu on the Start Screen, like this:

And when your app is registered, the options will look like this, with your app listed:

To do this, just add the Account Picture Provider to your declarations tab in your package.appxmanifest file, like this:

I told you this appxmanifest file is going to become your best friend. By default, it will just launch your app, but you can also provide custom entry points, just like we did for background tasks in day #12  and things like the file association that we discussed today. This just ensures your users ends up on the right section of your app automatically.

AutoPlay and Protocols

There are three other App Contracts we can subscribe to, and each of them only really requires another entry in the Declarations.

“AutoPlay Content” recognizes when new media is inserted into the device, like a USB drive or DVD.  If the content type you register for is present, your app will appear in the AutoPlay list that is displayed.  There is an excellent article on MSDN about AutoPlay, and the different values you can use.

“AutoPlay Device” is basically the same idea, but you’re registering for specific types of devices, like cameras, printers, or USB drives.  The same article above applies to this as well.

“Protocol” is a little different.  This allows us to register for URI schemes, like “mailto:” or even use our own custom URI schemes like “31days:.”  It’s another way to register our application with the system to be used at the appropriate times.  Microsoft has an excellent article about protocols as well.

Summary

Today, we looked at some of the extensible points we can access to make our app more prominent and useful to our users.  If they expect to be able to open images with our application, then we should show up in their list of apps when they try to open an image.

If you would like to see the full working solution for the code covered in this article, click the download icon below:

Tomorrow, we’re going to look at another powerful mechanism in Windows 8: the File Picker.  This empowers our user to grab files from their hard drive, and provide them to our applications.  See you then!

Today, we’re going to focus on the Windows 8 clipboard exclusively. More specifically, we’re going to look at how we can save and retrieve data from this system-wide and heavily used mechanism.  There are generally four types of data that we are going to see a user want to copy and paste:

• Text
• HTML
• Images
• Files

These are called the Standard Clipboard Formats. We’ll write some code in this article that shows not only how to copy and paste these values, but also how to detect which type of data the clipboard currently contains. There are 4 other categories of Clipboard Formats:

• Registered
• Private
• Multiple
• Synthesized

We will leave those for another day but get ready to do some copying!

Saving Data to the Clipboard

As we saw briefly in yesterday’s article on context menus, we took a very quick look at saving some text to the clipboard.  This time, we’ll cover that in more depth, and include saving images and files to the clipboard as well.  It’s important to note that some controls like the paragraph that we made selectable yesterday can copy by default. An input element of type=”text” can read from the clipboard. The point of today is to learn how to interact with the clipboard outside of those default scenarios.

To get started, we should talk about the DataPackage object. A DataPackage is what we are going to use to transport our data.  We will create a DataPackage when we save data to the clipboard, and we will use the Clipboard object to get the content ( actually calling a method called getContent() ) method to retrieve the data when we’re pasting it.

In my sample project (which you can download from GitHub), you will see that I’ve created a button with an event handler for each data type.  We’ll spend the rest of this section looking at how we store these different types of data to the Clipboard.

It is important to note that the clipboard is actually divided into several sections, one for each data type.  You can save data to one or many of these sections, and the target for pasting will make the determination as to what type of data it will display when pasted.  This might sound very similar to how the Share Contract works, and for the most part, it is.

It’s also likely that you’ve encountered this in the past: you copy content from one app, and try to paste it in another, only to have it paste something else.  This is a direct artifact of the “sections” of the clipboard.  Let’s take a look at how to save each data type:

Text

Certainly the simplest example, text can be stored to the Clipboard in just a few lines of code. First let’s just grab some selected text:

var selectedText = window.getSelection();

Certainly the text of which you decide to grab is up to you. With some text in hand now we need to create our DataPackage and set the text on it.

var _clipboard = Windows.ApplicationModel.DataTransfer.Clipboard,
    _dataTransfer = Windows.ApplicationModel.DataTransfer;

var dataPackage = new _dataTransfer.DataPackage();
dataPackage.setText(selectedText);

_clipboard.setContent(dataPackage);

You will see a pattern form as we move through the other examples, but this is about as basic as they come.  We create a new DataPackage object, call the setText() method with the text we want to save, and then set the content of the Clipboard to that DataPackage.

HTML

HTML, while similar to text, has its own quirks and formatting, and because of this, requires slightly different treatment when adding it to a DataPackage.  In this example, I am just grabbing the innerHtml of an element on our default.html page and using that as my DataPackage contents. Let’s that a first pass at things.

var htmlContent = document.querySelector("#content").innerHTML;
var dataPackage = new _dataTransfer.DataPackage();
dataPackage.setHtmlFormat(htmlContent);

_clipboard.setContent(dataPackage);

It looks very much in line with what we had done previously. Now if you we’re to run that and try to paste into something like Notepad++ or Visual Studio you in fact wouldn’t see anything. As I briefly mentioned before, HTML requires some slightly different formatting. Let’s modify.

var htmlContent = document.querySelector("#content").innerHTML;
var htmlContentFormated =
    _dataTransfer.HtmlFormatHelper.createHtmlFormat(htmlContent);

var dataPackage = new _dataTransfer.DataPackage();
dataPackage.setHtmlFormat(htmlContentFormated);

_clipboard.setContent(dataPackage);

Now that format helper will take our html and create some special sauce around it, transforming it to something like this:

Version:1.0
StartHTML:00000097
EndHTML:00000806
StartFragment:00000153
EndFragment:00000773
<!DOCTYPE><HTML><HEAD></HEAD><BODY><!--StartFragment -->
        <h1>Day #17 - The Clipboard</h1>

        <br>
        <div>
            <button id="btnCopyText">copy text</button>
            <button id="btnCopyHtml">copy html</button>
            <button id="btnCopyImage">copy image</button>
            <button id="btnCopyFile">copy file</button>
            <br>
            <p class="selectable" id="myText">Bacon ipsum dolor sit amet pig jowl filet mignon sirloin ribeye tenderloin. Sausage cow shank jerky pancetta pig biltong corned beef short loin.</p>
            <input id="inputBox">
            <img id="myImage" src="images/smalllogo.png">
        </div>

    <!--EndFragment --></BODY></HTML>

Interesting. If we run that code again we can in fact copy and paste into an HTML based file in something like Visual Studio but if I go back and try that same thing in Notepad++ I get nothing. Windows is smart enough to only allow you to paste the types content which are applicable for the destination. To fix that we need multiple types I guess. All we need to do is just call SetText() value of this DataPackage, with the original unformatted string. Here is the completed function:

var _clipboard = Windows.ApplicationModel.DataTransfer.Clipboard,
    _dataTransfer = Windows.ApplicationModel.DataTransfer;

function copyHtmlToClipboard() {
    var htmlContent = document.querySelector("#content").innerHTML;
    var htmlContentFormated =
        _dataTransfer.HtmlFormatHelper.createHtmlFormat(htmlContent);

    var dataPackage = new _dataTransfer.DataPackage();
    dataPackage.setHtmlFormat(htmlContentFormated);
    dataPackage.setText(htmlContent);

    _clipboard.setContent(dataPackage);
}

As you can see above, we can set multiple values at the same time, and as you get deeper into this example, you’ll start to notice that most of your favorite apps store data in multiple formats “just in case.”

Images

Our next example is images, and I want to be really clear on this one.  We’re not talking about a file that happens to be an image.  We’re talking about copying an image from a website, for example, and then pasting it into a OneNote file or Windows Live Writer.  In my example, I grabbing an image from the HTML DOM and putting that on the clipboard.

var imageSrc = document.getElementById("myImage").src;
var imageUri = new Windows.Foundation.Uri(imageSrc);
var streamRef = Windows.Storage.Streams.RandomAccessStreamReference.createFromUri(imageUri);

var dataPackage = new _dataTransfer.DataPackage();
dataPackage.setBitmap(streamRef);

_clipboard.setContent(dataPackage);

Above we get the source of an image in the DOM and create a URI from it. Once we have the URI we can create a stream reference to it and pass it along to our DataPackage calling SetBitmap(). As with all of the examples in this article, we end our code with actually setting the Clipboard with our DataPackage to actually complete the action.

Files

Files are treated very similarly to images, but there’s one major difference: we can copy multiple files to the clipboard at once and getting files is async.  You’ve done this before, highlight and grab some of the files cluttering up your desktop before dragging them as a group to the Recycle Bin.  Instead of throwing them away, you could cut/copy them, and paste them to another location.  Files are always passed as a collection of files, even if there is only one. To the code!

var _clipboard = Windows.ApplicationModel.DataTransfer.Clipboard,
    _dataTransfer = Windows.ApplicationModel.DataTransfer,
    _storageFile = Windows.Storage.StorageFile;

var imageSrc = document.getElementById("myImage").src,
    imageUri = new Windows.Foundation.Uri(imageSrc);

var splashScreenSource = document.getElementById("splashScreen").src,
    splashUri = new Windows.Foundation.Uri(splashScreenSource);

var files = [],
    promises = [];

promises.push(_storageFile.getFileFromApplicationUriAsync(imageUri)
    .then(function (file) {
        files.push(file);
    }));

promises.push(_storageFile.getFileFromApplicationUriAsync(splashUri)
        .then(function (file) {
            files.push(file);
        }));

WinJS.Promise.join(promises)
    .then(function () {
        var dataPackage = new _dataTransfer.DataPackage();
        dataPackage.setStorageItems(files);
        _clipboard.setContent(dataPackage);
    });

A bit different from the image but really only because of the WinJS Promise ( of which we will cover another day ). The core of this code is really the same except for the fact that we’re going to create an array of files aka StorageItems and then add them to the dataPackage calling setStorageItems

So, as far as saving content to the Clipboard, that’s just about it!  Our next step is going to be retrieving it from the Clipboard when the user chooses to paste it.

Detecting the Contents of the Clipboard

When it comes to “getting pasted” as I’ve started saying, I tend to do this all in one method that gets the content, determines which data type is available, and displays the content correctly based on that determination.

I had hoped, when writing this article, that there was going to be some amazing event handler, like OnPastedTo() or something, that would recognize when the user is attempting to paste some content to the app, so that we can take action on it.  (I personally live and die with Ctrl + X, Ctrl + C, and Ctrl + V).  I have not found that event yet, other than mapping the keyboard command directly.For now, I’ve created my own event handler that fires when you click a button.

You’ll see, in the example below, that I call the getContent() method on the Clipboard, and then use a series of if statements to act on the content appropriately.

var dataPackage = _clipboard.getContent(),
    sdFormats = _dataTransfer.StandardDataFormats;

if (dataPackage.contains(sdFormats.text)) {
    dataPackage.getTextAsync().then(function (text) {
        document.querySelector("#pasteResults").innerText = text;
    });
}

if (dataPackage.contains(sdFormats.html)) {
}

if (dataPackage.contains(sdFormats.bitmap)) {
}

if (dataPackage.contains(sdFormats.storageItems)) {
}

Let me quickly discuss each of the if statements.  For text, which is the only one I displayed I am going to just grab the text with a promise and set it as the innerText of a label that I have on my page.  Just like when we put items on the clipboard we will now need to do the reverse. Depending on the data format we will have to do the appropriate thing for what that data type requires. If it’s a collection of files we would need to loop through that collection of files and do something with them.

In all it’s pretty simple, but I was delighted the first time that I copied content from a webpage directly into my app, and it just worked!  The same is true for images, text, and files.  I highly recommend grabbing the source of this project and playing with it.  It will really help you to understand exactly how the clipboard is being used by your other applications.

Summary

Today, we took a deep look at the Clipboard, and how we can save and retrieve data as needed.  It supports several different file types, and I think you’ll be surprised just how redundant most of your favorite applications are when they save data to the Clipboard.

To download the entire code solution for the project discussed in this article, click the icon below:

Tomorrow, we’re going to add another useful tool to our Windows 8 development tool belt: the FilePicker.  We’ll look at retrieving files from the user’s device, and even filtering them so that we only get our preferred file types.  See you then!

Today, our focus is on context menus aka PopupMenu.  These are those small little popup commands that appear from time to time in your application when you right click on something. Microsoft offers some very specific guidance on when to use these context menus vs. when to use the AppBar control instead, so we will be following those rules in this article. 

What Is a Context Menu?

If you’ve used Windows 8 at all, you’ve likely encountered these before.  Often they result from a right-click on something you couldn’t select, or on text you wanted to interact with.  Here’s a quick sample of a context menu:

(image from http://msdn.microsoft.com/library/windows/apps/Hh465308)

You could also launch a context menu from an element on your page that is unselectable, like this image in my sample app:

Right-clicking the image launches the context menu center right above it.  (I will show you how to make this happen next.)  Each of the command items will have an action assigned to it, which is executed when the item is clicked.

Creating the Context Menu

Creating the Context Menu that you see above is pretty straight forward. To start with, we will wire up a handler  to our image element such that anytime someone right clicks on the object they will get our context menu. This looks like any other event listener, and we will listen on ‘contextmenu’ like such.

document.getElementById("myImage").addEventListener("contextmenu",
    imageContentHandler, false);

Next, we need to create our handler, which I have managed to call imageContentHandler, I know pretty awesome naming there. In our function we will simply start out by creating our PopupMenu object and adding the items we want to be shown. Each item can have its on event handler as well and in the example below I am just giving them all the same event handler of somethingHandler ( I know more awesome naming ).

var contextMenu = Windows.UI.Popups.PopupMenu();

contextMenu.commands.append(
    new Windows.UI.Popups.UICommand("Clark Sell", somethingHandler));

contextMenu.commands.append(
    new Windows.UI.Popups.UICommandSeparator());

contextMenu.commands.append(
    new Windows.UI.Popups.UICommand("Jeff Blankenburg", somethingHandler));

contextMenu.commands.append(
    new Windows.UI.Popups.UICommand("31 Days of Windows 8", somethingHandler));

contextMenu.commands.append(
    new Windows.UI.Popups.UICommand("Edit", somethingHandler));

contextMenu.commands.append(
    new Windows.UI.Popups.UICommand("Delete", somethingHandler));

With our PopupMenu defined, now we just need to show it. We can do that by calling showAsync and passing it some x,y coordinates like you see below.

contextMenu.showAsync({ x: [someCoords], y: [someCoords] });

Now how do we figure out where exactly to put it?

Determining The Location

You may have noticed that context menus appear directly above and centered to the element that has been selected.  This doesn’t happen by magic.  We’ll actually have to determine the position of the clicked element by ourselves (as well as any applicable offsets), and pass that along when we show the menu. Time to sharpen some pencils.

When a user click on our image, our contextmenu event is going to fire, calling our handler, imageContentHandler. It’s going to pass some arguments that we need to kick off our fact finding. There are three critical pieces of data we’re looking for here. 1. the x and y of the click and 2. the offset of the element that was its target and 3. the width of the target object. ( target object here is the image ) . Let’s see the code, and then come back to it.

function showWhereAbove(clickArgs) {
    var zoomFactor = document.documentElement.msContentZoomFactor;
    var position = {
        x: (clickArgs.pageX - clickArgs.offsetX - window.pageXOffset + (clickArgs.target.width / 2)) * zoomFactor,
        y: (clickArgs.pageY - clickArgs.offsetY - window.pageYOffset) * zoomFactor
    }

    return position;
}

So I have created this simple function called showWhereAbove taking something called the clickArgs. clickArgs is nothing more than the args that was passed into our contextmenu handler. To figure out both x and y are actually pretty much the same.

x = ( where x click was – offset to top of target – windows x offset + ( target width /2 )) * window zoom factor

Let’s continue to break that down

• where x click was = the x position of the mouse at the time of click
• offset to top of target = how much to the right of the elements left edge are we
• window x offset = where are we in relation to the window being scrolled
• target width / 2 = we need to move the PopupMenu to the middle of the object so we’re going to take the width and get middle
• window zoom factor = if the screen is zoomed in put it in apply that factor

Now the y axis is the same in principal as x, except we don’t have to worry about the height of the target. Since we’re working with the bottom center of the context menu, just getting our y offset is enough to put the bottom of the PopupMenu in the right position.

Again remember  – we’re trying to position the the bottom middle of the Popup Menu. Now that we know our position, we just need to show it.

contextMenu.showAsync(showWhereAbove(args));

Here is the finished function:

function imageContentHandler(args) {
    var contextMenu = Windows.UI.Popups.PopupMenu();

    contextMenu.commands.append(
        new Windows.UI.Popups.UICommand("Clark Sell", somethingHandler));
    contextMenu.commands.append(
        new Windows.UI.Popups.UICommandSeparator());
    contextMenu.commands.append(
        new Windows.UI.Popups.UICommand("Jeff Blankenburg", somethingHandler));
    contextMenu.commands.append(
        new Windows.UI.Popups.UICommand("31 Days of Windows 8", somethingHandler));
    contextMenu.commands.append(
        new Windows.UI.Popups.UICommand("Edit", somethingHandler));
    contextMenu.commands.append(
        new Windows.UI.Popups.UICommand("Delete", somethingHandler));

    contextMenu.showAsync(showWhereAbove(args));
}

Launching a Context Menu From Selected Text

Actually, nearly everything about this process is the same, except for the math on where to pop the box from.  Initially when setting out to solve this problem, I was hoping to add on to the existing context menu that already appears when you right-click on text:

As it turns out, you can’t ( at least that we’re aware of ).  So, for our example, let’s say that we want to keep all of those options, but also add a new one titled “Delete” at the bottom.  To do this, we’re going to have to create our own. While we know how to do so already there are two differences:

• We need to place our PopupMenu at the top of our selected text and in the middle.
• Stop the default behavior.

Like wire up an event handler to the contextmenu event of something like a <p> element.

document.getElementById("myInputBox").addEventListener(
            "contextmenu", inputHandler, false);

- tip – I am using a paragraph element here for demonstration. Because of that I need to make my element selectable. I did so in CSS like so

p {
    -ms-user-select: element;
}

Now we need to create our handler in this case inputHandler. Remember I said that we needed to prevent the default and do our own thing. To do so, we’re going to call preventDefault AND we’re going to see if some text was in fact selected. At that point, we can then crate our PopupMenu and show it.

function inputHandler(args) {

    args.preventDefault();

    if (isTextSelected()) {
        //create the PopupMenu and its items
     
    }
}

function isTextSelected() {
    return (document.getSelection().toString().length > 0);
}

After your PopupMeu is created we need to show it, but unlike before when we called showAsync() this time we need to call showForSectinoAsync. Since we’re going to show above the selection we need to understand what exactly was selected rather than just the element itself.

contextMenu.showForSelectionAsync(
    showForSelectionWhere(
        document.selection.createRange().getBoundingClientRect()));

You can see I have created again a helper function called showForSelectionWhere to take care of that math. We’re going to pass into it the bounding rectangle of our selection. Lets look at the code and then come back to it.

function showForSelectionWhere(boundingRect) {
    var zoomFactor = document.documentElement.msContentZoomFactor;

    var position = {
        x: (boundingRect.left +
            document.documentElement.scrollLeft -
            window.pageXOffset) * zoomFactor,

        y: (boundingRect.top +
            document.documentElement.scrollTop -
            window.pageYOffset) * zoomFactor,

        width: boundingRect.width * zoomFactor,
        height: boundingRect.height * zoomFactor
    }

    return position;
}

showForSelectionAsync takes an object with 4 properties; x, y, width, height. Let’s look at x quickly.

• x = left edge of the bounding rect + any pixels scrolled within the container element – the window scroll  offset * zoom factor
• y is basically the same as x, different axis.

Very similar to when we were working with the image element other than we have to figure out our position from within the element we we’re part of. The results should be as you would expect.

Summary

Today we looked at the art of creating inline context menus for our users.  They are an excellent way to provide interactions with elements that aren’t selectable, or for commands that make more sense directly adjacent to the element being interacted with.

If you would like to see the entire code sample from this article, click the icon below:

Tomorrow, we will venture further into the Clipboard functionality available to us in Windows 8 development.  See you then!

Today we are going to take a look at the on-screen keyboard in Windows 8.  Microsoft does not seem to make a distinction in naming between the keyboard that appears when you tap your finger on a input control and the one that can be found in the Ease of Access Center.  We are going to focus today on the keyboard that looks like this:

The Ease of Access On-Screen Keyboard, on the other hand, is a tool designed for making a computer easier to use for those that may not be able to use a keyboard at all.  It can be found by opening the Ease of Access center on your machine…

And clicking the “Start On-Screen Keyboard” option.  You will discover a keyboard that looks like this, instead:

The primary focus of this keyboard is to allow a user to completely use Windows without having a keyboard attached to their computer.  It’s not customizable, and doesn’t respond to any of the code we are going to write in this article.  This keyboard is also one of the only windows that can be placed over the Start Screen.  Check this out:

OK, so I’ve spent the first few paragraphs of this article talking about a keyboard that is NOT the focus of this article.  Why?  There are two reasons:

• If you are using a non-touch device when you work through this article (or on your own app and want to use the features of the regular touch keyboard), you’ll find that mouse clicks don’t launch the touch keyboard on your machine.  So you’ll search the web looking for a solution to make it show up.
• As you search around the web looking for more information about manipulating the on-screen keyboard in Windows 8, you’re going to get plenty of articles on the Ease of Access one, which is likely not what you wanted. If you do find an appropriate article about how to turn on the touch keyboard, it’s likely this one, because I wasn’t able to find any way to make this work.

The primary reason for this is because this is one of the few times that Windows 8 makes a distinction between a mouse click and and finger tap.  If you mouse click on a input box, Windows 8 assumes you are using a real keyboard, even if you’re using a touch-enabled machine.  A finger-tap, however, will produce that keyboard we’re going to talk about today.

To save you some frustration, when developing your application that will take advantage of the on-screen keyboard, use the simulator if you’re not working on a touch machine.  It allows you to simulate “taps” with your mouse.  Here’s where you set it:

OK, now that we’ve gotten all that out of the way, let’s get this actual article started.

Using the On-Screen Keyboard

First, let’s take a look at the default states of the on-screen keyboard that the user can navigate to any time the keyboard is open.  We saw the standard QWERTY view earlier:

But there are several more.  When we build an application, our primary focus, above all else, should be to make the tasks a user needs to accomplish as easy as possible.  (That IS on the top of your mind, right?)  To that end, the on-screen keyboard can be manipulated to make that happen. Our input element has had this notion of a type now for some time. With HTML5 we had a number of new types introduced such as datetime, email and more. This type attribute will activate the the appropriate keyboard for the task at hand.  If type is not specified, the normal keyboard will be displayed.  Here’s what the code looks like:

<input type="number" value="1234" />

You will find, as you start playing with the type attribute, that there are a large number of types, actually 23. Now these of these 23 input types they are not all applicable in changing the keyboard. For example a datetime type isn’t going to provide you a different keyboard other than the standards keyboard. Let’s look at how these input types might change the keyboard layout.

Standard Keyboard Layout

<input type="color" value="color"/>
<input type="date" value="date"/>
<input type="datetime" value="datetime"/>
<input type="datetime-local" value="datetime-local"/>
<input type="month" value="month"/>
<input type="text" value="text"/>
<input type="time" value="time"/>
<input type="week" value="week"/>

Search Keyboard

<input type="search" value="search"/>

Enter key changes to Search.

Email

<input type="email" value="email"/>

Added “@” and “.com” buttons, smaller space bar

URL

<input type="url" value="url"/>

Added “/” and “.com” buttons, smaller space bar, Go key ( as enter )

Numeric keypad

<input type="number" value="1234567890"/>
<input type="tel" value="111-111-1111"/>

Password

<input type="password" value="password"/>

Added the Hide keypress button

Others

• type=”file” brings up the file picker
• type=”hidden” hides it, what else
• type= [“radio”] or [“range”] or [“reset”] or [“submit”] brings up a native looking control

In addition to our types, it’s important to understand the other options our users can navigate to at any time when the keyboard is on the user’s screen.  Here they are:

Capital Letters

Emoji (there’s actually 30 PAGES of emoji, click here to see all of them)

Symbols (a second set of symbols after the set shown with the Number keyboard)

Split Keyboard (a user choice, this keyboard is optimized for thumb typing)

Inking Keyboard (this keyboard does handwriting recognition)

Obviously, this is a huge set of input points for us as developers, and by providing the right keyboard for the job will make your app more useful to your users.

On last point, you can’t launch the on-screen keyboard via code at all.  In fact, setting the focus on a input control won’t do anything but make the cursor blink.  It specifically requires a tap event (not a mouse click) to occur on the input box before the on-screen keyboard will appear.  (This is the same reason why you should use the Simulator when debugging this type of functionality in your apps.)

Summary

Today, we’ve covered off on the variety of keyboards that are available to our users.  We can leverage input types to show the right keyboard at the right time.  In addition, we learned that there are 30 entire pages of Emoji characters to use as well.  (If it’s not obvious, we benefit greatly from writing these articles as well!)

If you would like to see a working application that uses all of the input types, click the download icon below:

Tomorrow, we are going to dive into using Context Menus to gather data, both in our application, as well as from buttons in our AppBar control.  See you then!

Here’s that huge list of Emoji, in case you forgot to click on it.

Did you miss //build? Well there is another show in town, DevIntersection. I have always been a huge supporter of community and the power that exists in it. When we started That Conference we always said we would help out our fellow communities to the best of our ability. Today I am happy to share $50 off at DevIntersection using my promo code, SELL.

December 9th – 12th at the MGM Grand in Las Vegas you can see a pretty stellar lineup. Scott Hanselman, Scott Guthrie, Kate Gregory, Tim Huckaby and many more.

• Register by November 15th and you will get a free Windows 8 Tablet.
• Use registration code SELL and you will get another $50 off.

~ Enjoy

Today, we get to talk about geolocation.  Having knowledge about the user’s location (or more specifically, the device) makes every app and its user experience better.  Here’s some examples of how:

Line of Business Apps

Know which plant your field manager is visiting today, so that he has all of the appropriate documentation for the machinery in that facility.  In addition, your app could surface the photos and names of the employees in that facility, so that they are more prepared and personable when they arrive.

Games

Identify other nearby players, and make an opportunity to match them up in game.  It will not only potentially improve network latency for them, but you might also form a guild out of nothing.  Create a global game of tag, based solely on proximity, not touching.

Maps

Duh.  We’ll do this as part of the sample code today.

Travel

Recognize the user’s distance and potential travel time from the airport, and alert them to the impending urgency to leave before missing their flight.  In addition, once you’ve established they can’t make it on time, help them find the next available flight without the user having to find it on their own.

Exercise

There are tons of apps available to track your exercise route.  Think running, cycling, etc.  The obvious application of geolocation to these apps is the ability to map the route you took during your travels.  A more important one, however, and I think this responsibility probably falls to the mobile OS manufacturers themselves, is the ability to recognize an accident.  On average, 4500 cyclists a year are victims of hit-and-run situations, where they are left injured (or worse) on the side of the road.  In today’s world, nearly everyone has their phone with them, even when running or cycling.  Imagine that your phone is capable of recognizing a large impact (using accelerometer or gyroscope data), followed by no movement at all.  After 30 seconds of no movement, your phone prompts you to call 911 and send text messages to a pre-selected list of contacts with an SOS message and your location.  After 30 more seconds, it immediately sends that information and dials 911.  This functionality could save lives, as many of these cyclists die needlessly only because nobody knows where they are.  Sorry for being so morbid, but it’s an important thing to think about.

As you can see there is always a way to take location data and make your app even better.  In addition, if you love my ideas above, you are completely welcome to steal them outright.  I will likely never build any of those apps, specifically.  There needs to be 48 hours in every day to make that happen.

Geolocation and the Browser

Geolocation is a fairly new spec in our Web world but an exciting one nonetheless. Of course when you think about geolocation in the browser on our laptop the scenarios are slightly  different. I mean after all we’re not going to strap a 1k dollar ultrabook to our sleeve and going running. So we typically think of someone using it at their desk, wherever that is.

But that doesn’t mean geolocation wasn’t a needed feature. If you’re Yelp and your users are looking for a restaurant within 25 miles why on earth would you ask them for their location? Ok, maybe there is a scenario where they are at work and they want to find a place 25 miles from their home, but you get my point.

This is all fine and dandy but we’re also getting into a new world of new form factors, awesome hardware and so on. So if that ultrabook was actually some cool convertible , then maybe things like geolocation in the browser become something more than just behind a desk.

Regardless, this is all important and as we’ve seen throughout this series as web developers we have this unique skillset that is applicable in both the app world” and the “web world”. So, lets get started.

Updating our Manifest

Thankfully, getting our geolocation data is pretty easy, and as usual, we have to declare that Location is one of our capabilities in order to use it.  To do this, open the Capabilities section of your package.appxmanifest file, and check the Location box.

If you skip this step, and just try implementing the code in the rest of the article, you won’t get any errors, but you also won’t get any data.

Getting our Geolocation Data

In this example, I have constructed an application that constantly tracks the device’s location.  The first thing that got me confused in this process was how to ask the user for permission to start tracking their location in the app.  If you’ll recall, in Day #11 Lock Screen Apps, we had to explicitly prompt the user for permission to access their lock screen.  With Location, however, we don’t.  The simple act of trying to access the data will prompt the user on your behalf.  To get access to the users position, we will need to create the Geolocator object from WinRT and then ask for the user position. I have just wrapped this in a function that I will assign to a button for demonstration purposes.

function getlocation() {

    if (_geolocator == null) {
        _geolocator = new Windows.Devices.Geolocation.Geolocator();
    }

    if (_geolocator != null) {
        //this call will also ask the user for permission to their location
        _geolocator.getGeopositionAsync().then(getPosition);
    }
}

As you can see we’re getting access to the Geolocator in WinRT is easy. We can then ask for the users position and pass it the function to execute once it has it. As you can see from our comment when we ask for the users position, Windows will ask the user ( the first time ) for access to get their location.

Now this isn’t a permanent thing. The user can go into the settings of the application and turn off permission to the location. You should in fact guard for that scenario.

Once the position has been acquired our function will be called at which time we can get at the raw data. Below I am going to take the Geocoordinate class and grab a few of it’s data values, presenting them on the screen.

function getPosition(position) {
    _lat.innerText = position.coordinate.latitude;
    _long.innerText = position.coordinate.longitude;
    _accuracy.innerText = position.coordinate.accuracy;
}

Wait, but that HTML5 thing…

So wait a minute, we already have geolocation in HTML5 doesn’t that work? Is Microsoft cooking up it’s own thing here? Nope. Let’s quickly look at the HTML5 way. Quite honestly it’s just like what we did with WinRT, just different APIs. Key difference being we’re going to our navigation object from window rather than WinRT.

function getHtml5Location() {
    if (navigator == null)
        navigator = window.navigator;

    var geolocation = navigator.geolocation;
    if (geolocation != null)
        //this call with prompt for access.
        geolocation.getCurrentPosition(positionCallback);
}

We will of course get prompted again when we ask for the users location. Then our callback will get executed, passing the users position.

function positionCallback(position) {
    _lat.innerText = position.coords.latitude;
    _long.innerText = position.coords.longitude;
    _accuracy.innerText = position.coords.accuracy;
}

So the million dollar question is why are there two and which one do you use? Well there are two simply because WinRT is projected to all of the languages including JavaScript and since those API’s have to be there for the other languages then JavaScript get’s it too. So which one? Well at this point I am not sure it really matters. If you want cross platform JavaScript code, then I would stick with the HTML5 way. If you want the native API used across all languages, then maybe WinRT is your answer. I honestly don’t know if it matters. For the rest of this article I am just going to

but I’m moving…

At this point we’ve successfully asked for our location data and retrieved it but what if we we’re moving and the position changes or better yet the status of our GPS changes.

At this point I feed the need to put out a disclaimer.

Please do not try to test and drive your code at the same time without another geek actually driving.

As you might have guessed the answer here is events. There are two different events we can register for; positionChanged and statusChanged. Let’s look at each.

positionChanged event

Before we called getGeppositionAsync to get our location data like such:

_geolocator.getGeopositionAsync().then(getPosition);

This was a one time call that returned to us some coordinate data ( the same coordinate data that we’re about to talk about in greater detail ). But that was a one time async call. What if we want it as the users position changed? Well rather than calling to get the coordinate data we will just wired up and event to it like so:

_geolocator.addEventListener("positionchanged", onPositionChanged)

Just like any event handler you’ve wired in the past the same is true here. when positionchanged is fired it will call my function onPositionChanged. Now this time when my function is called a slightly different object is passed through. it’s an argument object with a position on it rather than just the position being passed through. So let’s modify the code slightly to easily account for both scenarios.

//called by my event handler that we wired
function onPositionChanged(args) {
    displayPosition(args.position);
}

//called by a button who called getGeopositionAsync()
function getPosition(position) {
    displayPosition(position);
}

//displays on screen
function displayPosition(position) {
    _lat.innerText = position.coordinate.latitude;
    _long.innerText = position.coordinate.longitude;
    _accuracy.innerText = position.coordinate.accuracy;
}

You will notice that I have modified my functions such that I can reuse some of the logic a bit better.

Now this object passed through has is where all this location data will come from such as Longitude, Latitude, and Accuracy, as you’ve already seen.  If you look a little closer at this Geocoordinate class you will see there is actually much more data on it such as:

• Accuracy is the measurement, in meters, of the radius of a circle that has our latitude and longitude value as the centerpoint.  Like this:

• Timestamp is the actual time that the Location value was read.  This includes timezone information, so you’ll have to convert the times to store everything in UTC.
• Altitude is the elevation of the device, in meters.  This is likely only to be found in devices with a barometer (we will cover sensors later in this series), but it’s a valuable piece of information if you can get it.
• AltitudeAccuracy is just like our other Accuracy value, except that it is simple the margin of error for the Altitude value.  It means you are + or – this many meters.
• Heading will also only be displayed with the appropriate sensor, the compass.  This is measures in degrees relative to true north.
• Speed can technically be calculated by tracking the lat/long values over time, but they’ve made it incredibly easy for us.  It is measured in meters/second, but is an optional value that the device’s GPS sensor can provide.  This means that not all devices will return a value.

statusChanged event

So we’ve gathered our location data, but there’s still this other event called “statusChanged”.  This is not something we would generally give our user direct access to, as it’s more administrative data for us, but it’s an interesting set of data nonetheless.  It can have six different values:

• notInitialized is returned when your application has not yet requested permission to access the location data.
• disabled is the value you will get when the user declines your request to access their location information.
• notAvailable is returned if the user’s device does not support location data.
• noData is returned if the user’s device supports location, but can’t acquire any.  This could happen in a scenario where the device is not connected to wi-fi, and is inside a buiding, for example.
• initializing is the status value you’ll receive between the time the user grants access to location data, and the time you actually start receiving that data.  In future uses of your app, this will also be sent when your app is waiting to access location data for the first time.
• ready is the golden response, and lets you know that data is available for your use.

It works much the same as the positionChanged event. We will register for it:

_geolocator.removeEventListener("statuschanged", onStatusChanged);

And then when something interesting happens we can react to it with out callback.

function getStatusString(locationStatus) {
    var posStatus = Windows.Devices.Geolocation.PositionStatus;

    switch (locationStatus) {
        case posStatus.ready:
            return "ready";
            break;

        case posStatus.initializing:
            return "initializing";
            break;

        case posStatus.noData:
            return "noData";
            break;

        case posStatus.disabled:
            return "disabled";
            break;

        case posStatus.notInitialized:
            return "notInitialized";
            break;

        case posStatus.notAvailable:
            return "notAvailable";
            break;

        default:
            return "Unknown status.";
    }
}

When your done….

Stop listening, not to me but your gps:

function stopGetPosition() {
    if (_geolocator) {
        _geolocator.removeEventListener("positionChanged", onPositionChanged);
        _geolocator.removeEventListener("statuschanged", onStatusChanged);
    }
}

Debugging

Now what if your in a some locked away in some super secret government bunker with no access to the outside world ( yet you can read this blog ) or you’re just sitting still and you would like to see positionChanged fire. How might we test this? Well, we turn to our friend the simulator.

In the simulator there is a set location button ( as you can see below ). Here we can set our geolocation parameters and then go back to our applications as normal therefore fooling it to think it’s somewhere it’s really not. In fact we can even move that input window off to the side and enter values hitting set and watch our application react to the change. This might be a good way to manually test the positionChanged event.

If you want to see the statuschanged event fire, the easiest way is to just turn off your wireless network and unplug the wired network. My laptop doesn’t have a GPS in it so it will triangulate from my wifi and wired network to stalk me. Turn it off, and you will see the event fire.

Summary

Today, we talked about geolocation data, and how important it can be to any application in the market.  We looked at tracking a user’s location, as well as getting their location once, for applications that just need the specific location “right now,” but not all the time. I would highly suggest looking through the article Guidelines for location-aware Apps.

I am going to save working with something like the Bing Maps SDK for another time but you should feel free to explore it. If you would like to download a sample application that includes all of the code from this article, click the icon below:

Tomorrow, we are going to look at the on-screen keyboard.  See you then!

We’ve spent the last few days getting pretty technical around updating the system with information to the let our users know what’s going on.  In fact, in the first 12 days of this series, we’ve spent very little time talking about how to do one of the most common activities we’ll encounter in Windows 8 development: navigation. Now you might be sitting there saying, anchor tags, query strings and JavaScript gymnastics, right? You might even be thinking I can skip this it’s web 101 and while that is somewhat true you need to understand where WinJS fits into things and just what to do when your application gets terminated.

I am pretty sure we’ve all done some kind of navigation in our websites but let’s level set a bit see how today’s web practices fit into an “app”.  After all the web is all about navigation right? We can link to anything on the web with a simple anchor tag.

<a href="http://31DaysOfWindows8.com">31 Days of Windows 8</a>

And when that wasn’t enough we added a query string so we could get some data:

<a href="http://31DaysOfWindows8.com/?days=13">Navigation</a>

And when AJAX came a overnight internet sensation, we started using hashs (#) and hashbangs (#!) and creating these awesome web applications:

<a href="http://31DaysOfWindows8.com/#day12">Day 12</a>

But you knew all this already. So why did I even bother spewing that? Well over time there has been a subtle evolution of what we might consider a Website. Today Websites have become more of a application than what we have typically considered a Website. HTML5 has been a great catalyst in all of this but it was going to happen regardless.

Regardless, there are really two major “patters” which have emerged. The multiple page site ( http://thatConference.com ) and the single page site ( http://twitter.com or http://OneDay.ThatConference.com ) . While they really don’t sound all that different their implementations are drastically different. Let’s gently break down each:

Multiple Page Site:

• Everything starts over on each page navigation, aka full page lifecycle. 
• New resources are loaded for each page request ( again full page lifecycle ), this means JavaScript pages, CSS and whatnot.

• Session state is most likely managed on the server assuming there is session.
• Interaction between pages is minimal.

Single Page Site:

• Everything runs in the container that it was loaded  as a “control or section” ( if you will )
• In the image below we’re going to load pages within the context of the parent page. In our case the default.html page
• Resources are usually only loaded once ( at least in the simplest of methods )
• Usually heavily dependent on a lot of AJAX to pull in data when needed
• Loves JavaScript ( I do to actually )

Which one do you pick? Is there a right answer? Maybe, but your context is critical to making that decision. Take a moment here, ok. Are you a multiple page site or a single page site? Furthermore are you a multiple page app or a single page app or are you both? Or are you doing something greenfield looking for guidance. And BTW how does all of this fit into Windows 8? Getting there..

Well not to fear, Windows 8 supports both just like your Website. With one major difference. We do not have any navigation buttons or address bar functionality inside our app like we do in a browser. Today, we’re going to dive into the single page site model. This is the Microsoft recommended approach for a Windows 8 Store App and there are a few reason for that:

• Page Transitions
• The way scripts are loaded and unloaded
• Page and State Management

There are a few specific scenarios that I want cover in this article:

• The simple act of navigation from Page A to Page B in either model we describe above.  What happens when, and what information is available to us?
• Passing data from one page to another.  This doesn’t just include strings and integers, we can also pass entire objects between pages.
• Page State

New Navigation App

Today we’re going to start a bit differently and rather that kick things off with the blank template we’re going to start from a new project template, one called the Navigation App. Why what’s the difference? Mainly just a few minor things:

• A new JavaScript file called navigator.js. This is the framework which helps you do navigation.
• Some new goo in our default.js file to to manage save and load our applications navigation state.
• Slightly different app folder structure. There is now a pages folder with folders of pages.
• The markup has changed in our pages to leverage the navigator.js framework.

To better see this in action let’s just walk the stack and see what our template is doing when we hit run.

When our app first fires up you will notice that our default page has the same standard references to our WinJS scripts and style. Of course we also have our own supporting style and scripts file. New to this template is the addition of the navigator framework:

<script src="/js/navigator.js"></script>

When default.js kicks off, it looks very similar as it has in the past except now we have some new code to deal with the saving and loading our navigation state.

app.addEventListener("activated", function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {

        /* .... */

        if (app.sessionState.history) {
            nav.history = app.sessionState.history;
        }
        args.setPromise(WinJS.UI.processAll().then(function () {
            if (nav.location) {
                nav.history.current.initialPlaceholder = true;
                return nav.navigate(nav.location, nav.state);
            } else {
                return nav.navigate(Application.navigator.home);
            }
        }));
    }
});

app.oncheckpoint = function (args) {
    app.sessionState.history = nav.history;
};

Next up, the page itself. Our default.html page is actually going to load home.html as a control inside a div.  Application.PageControlNavigator is a control inside that navigator.js framework we mentioned earlier. This should feel very familiar to to our Day 4 conversation on WinJS controls.

<body>

    <div id="contenthost" 
            data-win-control="Application.PageControlNavigator" 
            data-win-options="{home: '/pages/home/home.html'}">
    </div>

</body>

Next up, let’s look at the subpage, inner page, child page, or little box in the bigger box, starting with its markup. Since we’re a subpage of default.html we don’t need to reference the WinJS frameworks like we did in default.html because they we’re already in scope for us. The rest of our page is just standard ole markup. Nothing fancy to see here. In this case, back button, header and some content.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>homePage</title>

    <link href="/pages/home/home.css" rel="stylesheet" />
    <script src="/pages/home/home.js"></script>
</head>
<body>
    <div class="fragment homepage">
        <header aria-label="Header content" role="banner">
            <button class="win-backbutton" aria-label="Back" disabled type="button"></button>
            <h1 class="titlearea win-type-ellipsis">
                <span class="pagetitle">Welcome to App16!</span>
            </h1>
        </header>
        <section aria-label="Main content" role="main">
            <p>Content goes here.</p>
        </section>
    </div>
</body>
</html>

Now onto the it’s associated behavior. Remember our subpage is really something called a PageControl found in WinJS.UI.Pages. Why not just a normal page? Well if you think about how the lifecycle of a page really works we’re well beyond the bounds of that. Things like our standard page events ( like document ready ) have been thrown off as they have really happened on our parent page. This is where our pageControl control comes in. It gives you the perception of being a page, acting like a normal page even though it’s a control inside another page.

(function () {
    "use strict";

    WinJS.UI.Pages.define("/pages/home/home.html", {
        ready: function (element, options) {
            var isReady = "I am ready are you?";
        }
    });
})();

At this point we have a running app which is using the navigation framework with bonus points of because we’re saving our navigation state to our apps sessionState through the PLM events. I know the template did this all for you but just don’t tell your boss that.

Before we move on let’s create another page home2 that we can navigate too. We can easily do so, by adding a new item called a pageControl. A page control is really nothing more than an html, js and css files already semi-wired up for you to start messing around with. I say semi because depending on how you’re using it, you could in fact remove some of the WinJS references, as your parent page already has them.

Navigating Between Pages

We started off this article briefly running through a set of anchor tags, which take you to another document or to a different location in a site\application. The same is true for a Windows Store App. A simple anchor tag will redirect you from one top level page to another.

<a href="/pages/home2/home2.html">Goto MultiPage Navigation</a>

Which will work fine and one could build an app like that no problem. But today I want to focus on the Single Page Navigation model that we’ve touched on earlier. To accomplish that we will use the navigation framework that we’ve already briefly introduced. As you can imagine, we’re going to call a method called navigate passing it our destination.

WinJS.Navigation.navigate(“/pages/home2/home2.html”); 

Next we need to actually use our navigation framework. To easily do so, we want really want to replace the default behavior of our anchor tags default behavior. We can easily hijack their behavior by first wiring into their event like so:

WinJS.Utilities.query("a").listen("click", anchorHandler, false);

and then preventing them from doing what they normally would do and rather call the WinJS Navigation.

function anchorHandler(eventInfo) {
    eventInfo.preventDefault();
    var link = eventInfo.target;

    WinJS.Navigation.navigate(link.href);
}

Now all of our anchor tags will not link like they normally do but rather use our navigation framework to navigate to other pageControls. Of course it doesn’t just have to be an anchor tag, but I am taking the easy road here.

Now that got us to someplace, what about going back? Remember we don’t have the browser back and forward buttons and further more the browser and\or the HTML5 History API would\could be keeping track of that for you ( it depends on how you setup ). The same is true when you use the WinJS Navigation. The navigator is keeping our session history and has a number of methods and events on it for your disposal. If you’re using the template you may notice the back button at the top of your second page and if you click on it, you’re magically taken back. Well not really. In fact all it’s doing is calling one of those methods on WinJS.Navigation, specifically back(). You can see this directly in the navigator.js file.

_updateBackButton: function () {
    var backButton = this.pageElement.querySelector("header[role=banner] .win-backbutton");
    if (backButton) {
        backButton.onclick = function () { nav.back(); };

        if (nav.canGoBack) {
            backButton.removeAttribute("disabled");
        } else {
            backButton.setAttribute("disabled", "disabled");
        }
    }
},

Passing Data

Next, we’re going to want to pass data between our pages.  Maybe an object, maybe a string, but data nonetheless.  As it turns out, our WinJS.Navigation.navigate method is overloaded to also accept a data parameter. So I am just going to create a simple little object, and modify my call to navigate to pass it alone.

var myData = {
    firstName: "Clark",
    lastName: "Sell"
};

....

WinJS.Navigation.navigate(link.href, myData);

....

Then on the receiving side of that call it comes to us as the options on the ready handler for our pageControl.

ready: function (element, options) {
    var results = document.querySelector("#results");
    results.innerText = options.firstName + " " + options.lastName;
}

I don’t think that gets much easier.

Application Lifecycle

Now what if your app is down a few levels and the user then switches to something else, forgetting he or she was running it. Windows suspends it and then what? All is lost? I hope not. We would want the user to resume where they left off and if that meant hitting your back button first thing, then they should be able to. Well this is in fact true. We touched on it earlier but lets took a quick look at what that code in the template was doing.

Before your app suspends, it will call checkpoint. This is our opportunity to take our navigation state and persist it.

app.oncheckpoint = function (args) {
    app.sessionState.history = nav.history;
};

Now with things saved off, what happens in the other direction when things start up. Well honestly it does what you would think.

• Check your apps sessionState for any history
• If there is, re-populate the navigation history
• Then after all the controls are processed, see if the user was somewhere
• Return the user to the correct location.

app.addEventListener("activated", function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
            // TODO: This application has been newly launched. Initialize
            // your application here.
        } else {
            // TODO: This application has been reactivated from suspension.
            // Restore application state here.
        }

        if (app.sessionState.history) {
            nav.history = app.sessionState.history;
        }
        args.setPromise(WinJS.UI.processAll().then(function () {
            if (nav.location) {
                nav.history.current.initialPlaceholder = true;
                return nav.navigate(nav.location, nav.state);
            } else {
                return nav.navigate(Application.navigator.home);
            }
        }));
    }
});

Honestly nothing too complicated, and since it’s done for you, well even easier but you should know what is at least going on.

Summary

Easier than using your GPS to find the nearest Subway? Maybe. It’s not overly complicated and in fact the frameworks are already there to really support us. Of course today’s applications can be very complicated so don’t assume your work is done for you. Today we covered the navigation models, the Navigator App template, navigation back and forth and even persisted our navigation history in case our app gets suspended.

If you would like to download the complete code sample from this article, you can click the icon below.

Tomorrow, we’re going to start our conversation determining a user’s current location using GeoLocation, including the rules that go with using this technology.  See you then!

There are a number of events from now until the end of year and I wanted to just take a quick moment and list them all out for everyone. This is just what I know about, so if you would like to add something just reach out to me.

So, here we go…

• November 15th – Windows 8 Unleashed
• Microsoft Waukesha Office, WI
• More Information and Registration
• November 28th – The New Era of Work
  • Swiss Hotel, Chicago, IL
  • More Information and Registration
• November 29th – Windows 8 Unleashed
• Microsoft Office – Indianapolis, IN
• More Information and Registration
• December 6th – The New Era of Work
  • Hyatt Regency, Indianapolis, IN
  • More Information and Registration
• December 7th – Build a Windows 8 Store App in a Day
  • Herzing College, Madison, WI
  • More Information and Registration
• December 10th – Windows Azure, Window Phone, Window 8 and a cup of coffee
  • Microsoft Office, Downers Grove, IL
  • More Information and Registration
• January 18th – Build a Windows 8 Store App in a Day
• Fox Valley Technical College, Appleton, Wisconsin
• More Information and Registration
• January 25th – Build a Windows 8 Store App in a Day
• Microsoft Office – Waukesha, WI
• More Information and Registration
• Visit us at the Microsoft Store
• More Info and Registration

Oh yea, and don’t forget That Conference will happen again this coming August the 12th – 14th.

Today, we are talking about Background Tasks.  The short way to describe Background Tasks is this:

A Background Task is the code that runs when your app doesn’t.

Think of the scenarios:

• Continue streaming audio, even when the user is running another app.
• Update the user’s Live Tile to reflect new data.
• Pop a Toast Notification to let the user know something important has happened.
• Update the user’s lock screen, even when the device is locked.

But I guess we should start by asking the question, why isn’t it running. With the release of Windows 8 and WinRT a new application lifecycle was introduced. But more on PLM in another upcoming article. Also as a web developer this isn’t something we would typically even bother thinking of. We typically think of http requests, session state, endpoints and so on. At a high level the application lifecycle looks something like this:

Image courtesy of http://msdn.microsoft.com/en-us/library/windows/apps/hh464925.aspx

So in short we need background tasks just in case we might not actually be running. For purposes of today, we’re going to build a sample will get all the pipes working together and send some push notification based on system events. Getting a background task established and registered with the system is a two-step process.  First, you have to register the Background Task in your package.appxmanifest file.  Once that has been done, you still need to register the events of that Task with the system from your application code, and then there are additional events to manage what happens when Background Tasks should get fired, when it completes etc.

Our Background Task

As you might imagine, a background task is nothing more than a self executing anonymous function. Sure we have to do some special sauce around the thing but we basically registered an endpoint, a trigger and then the function that should get executed, in this case the JS file that should run.

Given this the first place we’re going to start is adding a new JS file to our blank project and add the most famous three lines in Windows 8 development.

(function () {
    "use strict";

})();

Of course if this is in fact our background task, then you should expect the next step to be something like this.

....

function run () {
            
}

run();

....

I know I am starting out simple here but I want to prove some points along the way. 1. it’s just JavaScript. 2. we’re going to leverage WinRT where needed.  At this point we have a function that when run will execute itself, hit run() and call the run function.

Now it’s a background task so of course we want the ability to close or cancel it. Let’s extend our function a bit to add a cancellation handler. Now to do that we’re going to need an instance of our background task running and we get that from Windows.UI.WebUI.WebUIBackgroundTaskInstance.current. Let’s revisit the entire function to add the cancellation handler AND call close when our work is done. After all we need to signal the fact we’ve finished.

(function () {
    "use strict";

    var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current;
    var canceled = false;

    function run() {
        //make awesome!!!
        close();
    }

    function onCanceled(cancelSender, cancelReason) {
        canceled = true;
        close();
    }

    if (!canceled) {
        run();
    } else {
        //Must Call Close
        close();
    }

    //register event handlers
    backgroundTaskInstance.addEventListener("canceled", onCanceled);

})();

At this point we have a background task. Now it doesn’t actually run any “background code” or talk with app but it’s there and ready to go. We will come back to our task later after we have it executing.

Setting Up Your Package.Appxmanifest File

Ah yes. the package.appxmanifest. I hope by now you understand just how much you need to know this file. Once again we’re back in there. The next step in our process is to declare that we will be using Background Tasks in this application.  We do this in the package.appxmanifest file, in the Declarations section, as illustrated by the screenshot below (click to enlarge):

As you can see, we’ve added a declaration for Background Tasks (you will have to add a new one of these for each Background Task you want to add to your project), and set the entry point to be the JavaScript file we just created. You will notice that I selected System Event and Push Notifications ( raw notification in this case ). You can think of each of these as a category of different triggers.

Now over the past few days we have learned about live tiles, badge updates and the lock screen. I figure today we will continue to build upon that. To do so, we will have our background task just fire some tile updates.

Since I selected Push Notification I also have to go back to the Application UI and update the appropriate fields in the Tile and Notification sections, otherwise I couldn’t send any push notifications to it. Now you already know how to do that from Day #9 on Live Tiles.

Next, we need to register this task in our actual application, so that Windows 8 knows to run it at the appropriate times.

Registering Your Background Task

Up to now, we have our background task shelled out, and registered in the appxmanifest. Now on our startup of the application we need to register it with Windows. To do this we’re going to run through a few things:

• Loop through all of the tasks and see who is registered
• Get an instance of the task builder
• Register the exact trigger
• (optional) Register the entry point ( although this might be duplicate work here )
• (optional) Set any conditions on the trigger
• Register it
• Add any handlers we care about such as when the task completes.

Let’s start by looping through the BackgroundTaskRegistration.allTasks collection. We we could have multiple Background Tasks running under our application, but in our case we will only have one that we’re “really” interested in. Because of that, we’re going to cheat a bit code just to prove the point and work through the process.

var _isRegistered = false,
    _bgTaskName = "our task",
    _appModel = Windows.ApplicationModel,
    _background = _appModel.Background,
    _registeredTasks = _background.BackgroundTaskRegistration.allTasks.first(),
    task;

//loop throught all of the tasks and find out who is already registered
while (_registeredTasks.hasCurrent) {
    var task = _registeredTasks.current.value;
    if (task.name === _bgTaskName) {
        _isRegistered = true;
        break;
    }

    _registeredTasks.moveNext();
}

Once we have looped through to find out if our task was registered, we can go forth and register the our task.

if (!_isRegistered) {
    var taskBuilder = new _background.BackgroundTaskBuilder();

    var taskTrigger = new _background.SystemTrigger(
        _background.SystemTriggerType.timeZoneChange, false);

    taskBuilder.name = _bgTaskName;
    taskBuilder.taskEntryPoint = "js\\backgroundTask.js";
    taskBuilder.setTrigger(taskTrigger);

    /*
        do we add any conditions here...

        taskBuilder.addConditions(
            new _background.SystemCondition(
            _background.SystemConditionType.userPresent));
    */

    task = taskBuilder.register();
}

In short, we’re creating the BackgroundTaskBuilder and using it to configure our task. Once done we will then register it. Now in the sample above you will see I am setting the entry point of the task. A fresh caffeinated mind should remember that I actually set that entry point in our appxmanifest. You can do either. I guess you could be somewhat dynamic with the trigger and pass in the entry point but you would need to unregister and reregister the task.

Now I choose to use a simple SystemTrigger and one that might seem odd, the timeZoneChange trigger. There was no real reason for doing so other than it’s easy for you to setup things and the change your time zone kicking off the trigger.

If you ever have a need to unregister your Background Task, it’s pretty simple. Like we registered we can unregister. Difference being we pass a Boolean in as a parameter which tells the taskBuilder to either kill what is in progress or wait until that task has completed to kill it.

task.unregister(false);

So we’ve worked through registering and unregistering our Background Task, and we now have specified that our application should kick off our Background Task when the time zone of the machine changes.  Let’s write some actual code in our Background Task class, and then give this thing a test.

Making Your Background Task DO Something

Earlier we shelled out our background task class. Since we’ve spent the last few days working on sending updates to live tiles, I figure why not send out a push notification when our background task gets called by changing the time zone.

To send out that notification we could simply do something like this, note I am grabbing the Date object so we can see the Time and TimeZone on our tile:

function sendTileUpdate() {
    var notifications = Windows.UI.Notifications;

    var smallTemplate = notifications.TileTemplateType.tileSquareImage;
    var smallTileXml = notifications.TileUpdateManager.getTemplateContent(smallTemplate);

    var wideTemplate = notifications.TileTemplateType.tileWideText01;
    var wideTileXml = notifications.TileUpdateManager.getTemplateContent(wideTemplate);

    var wideTileTextElements = wideTileXml.getElementsByTagName("text");
    wideTileTextElements[0].innerText = new Date().toTimeString();

    //merge tiles..
    var node = wideTileXml.importNode(smallTileXml.getElementsByTagName("binding").item(0), true);
    wideTileXml.getElementsByTagName("visual").item(0).appendChild(node);

    var tileNotification = new notifications.TileNotification(wideTileXml);

    var currentTime = new Date();
    tileNotification.expirationTime = new Date(currentTime.getTime() + 10 * 1000);

    notifications.TileUpdateManager.createTileUpdaterForApplication()
        .update(tileNotification);
}

You have seen that code a few times already. Next we would clearly need to update our original run method to call that sendTileUpate.

function run() {
    var key = null,
        settings = Windows.Storage.ApplicationData.current.localSettings;

    // aka "background work"
    sendTileUpdate();

    // Record information in LocalSettings to communicate with the app.
    key = backgroundTaskInstance.task.taskId.toString();
    settings.values[key] = "Succeeded";

    close();
}

Now I slipped in a few new lines. Let’s say you wanted to interact with your background task in some way, maybe get a status some kind of status or log. You can see I just wrote some key values pairs to our apps localSettings. Then from my app I can easily just grab it from anywhere in my application. I thought that might be a good way to pull you back to day #8.

Obviously, we could write a similar Background Task to implement sending a Toast notification, updating the Lock Screen, or other valuable calls to web services for example. I just thought this might be a good way to tie together the past few days together.

Also one point to note, if it was clear from earlier. Your app will have to at least run once to register the background task.

Summary

That is a pretty good run-through of how you can setup and run a background tasks. Now clearly, there are a number of different triggers and conditions for a background task so it’s not all ice cream and apple pies. They also get increasingly more difficult depending your overall dependencies and setup which makes them harder to debug. In fact, Microsoft has written an entire article about exactly how to Debug Your Background Tasks.  I highly recommend reading it.  They have also created a quickstart tutorial called Create and Register a Background Task. Having said that, the sample we built today you can run just hit run and put breakpoints in the appropriate places and mess around just fine.

If you would like to download the working sample code from this article, click the icon below:

Tomorrow, we’re going to shift gears again, and start talking about Navigation.  Specifically, how to navigate between pages in a HTML application, and pass parameters and data as part of that process.  See you then!

Today we cover another part of notifications in Windows 8: the Lock Screen.  If you’re running Windows Phone or Windows 8 on your machine, you’ve likely gotten pretty familiar with the lock screen.  It shows you how many emails you’ve received, Facebook messages, the clock, and your connectivity status.  Here’s my current lock screen:

Yes, that’s a photo of my screen. I have no clue how to take a screen shot of my lock screen without a VM installed. Anyways, you can also see that I’m only writing this article a few days ahead of publication time, and someone has left me a number of instant messages.

We, as developers, have the ability to add our badges to this lock screen as well, but it’s dangerous to go alone.  Take this.  It’s Microsoft’s guidance on the best ways to utilize the Lock Screen notification area.

Configuring our Manifest

To get started the first thing we need to do is configure out application for lock screen notifications. We do that in where? Yes, our package.appxmanifest file under the Application UI / Notification Section. We’re going to set the Lock Screen Notifications to either Badge or Badge and Tile Text. What’s the difference? A Badge would update the lock screen and your tile while Badge and Tile Text would update that + putting a text notification on the front screen if the user selects your app. This is something that appears to be only set from the manifest and by the user. For today let’s go all out and select the Badge and Tile Text option.

Well that fired off a slew of validation errors huh. You’ll notice the screen is now lit up with red X symbols.  When lock screen notifications are enabled, we are required to have a Badge Logo ( we created a new 24×24 png for this which has to be transparent white png ), and since we chose the option that includes tile updates as well, we’re required to provide a Wide Logo image as well.  Here’s my Application UI tab with those files added:

Wait, what? Why still red? Well “If lock screen notifications are enabled, you must specify one or more Background task declarations of type ‘Timer’, ‘Control channel’, or ‘Push notification.’”

What this means is that Lock Screen apps generally expect to be updated from a Background Agent.  Let’s flip over to our Declarations tab, and add a Background Task. We’re going to add support for push notifications and add our default page as the entry point:

In my example app, we’re not actually going to create a background task, however.  I’m going to cover that extensively tomorrow.  Instead, we’re going to focus specifically on the processes and code that allows us to update our Lock Screen information.

Asking for Permission

Before you can ever start thinking about writing content to the user’s lock screen, you need to ask for their permission.  Now, you don’t HAVE to ask, but without asking their permission, the road to the Lock Screen is perilous and fraught with danger.  Here’s what I mean:

You get ONE, and only ONE opportunity to ask the user for permission to be on their lock screen. 

If you ask once, and they say “Don’t Allow”, you’re not even capable of asking again. 

Here’s what it looks like when you ask:

And here’s how you do it:

var background = Windows.ApplicationModel.Background;
var promise = background.BackgroundExecutionManager.requestAccessAsync();

If you never ask, the only way to get on the lock screen is for the user to open their PC Settings, and explicitly add you. How many users will really do that after the fact?

Users can select up to 7 apps to be displayed on their Lock Screen and *1* to display text.  We want to make sure we’re one of them.  So, because our status can change at the user’s whim, we should be responsible before trying to send updates to their Lock Screen.

Making Sure You Have Permission

This is not a required step.  You can have your app, or your background task (as we will cover tomorrow) continue sending updates even if you don’t have permission.  That being said, your updates also won’t ever be seen by the user.  Without permission, your updates will disappear into the ether.

Here’s how we check to see if the user has granted us permission to update the lock screen:

var background = Windows.ApplicationModel.Background;

var promise = background.BackgroundExecutionManager.requestAccessAsync().then(
    function (result) {
        switch (result) {
            case background.BackgroundAccessStatus.denied:
                // Background activity and updates DENIED 
                break;

            case background.BackgroundAccessStatus.allowedWithAlwaysOnRealTimeConnectivity:
                // Added to list of background apps.
                // Set up background tasks
                // CAN use the network connectivity broker.
                break;

            case background.BackgroundAccessStatus.allowedMayUseActiveRealTimeConnectivity:
                // Added to list of background apps.
                // Set up background tasks
                // CANNOT use the network connectivity broker.
                break;

            case background.BackgroundAccessStatus.unspecified:
                // The user didn't explicitly disable or enable access and updates. 
                break;
        }
    });

So at this point, we’ve covered asking the user for permission, and then checking to make sure that permission has been granted.  The next step is actually sending the update.

Updating the Lock Screen

Sending an actual update will look pretty familiar if you’ve read the previous two articles.  (Day #9 – Live Tiles, Day #10 – Toast Notifications)  Like those previous examples, we are grabbing a template that consists of XML (in this case, it’s incredibly simple):

<badge value="31"/>

Next, we need to specify the value that we want to display.  We have several options in this scenario.  Not only can we use any number from 1 – 99, but we also have a number of glyphs to choose from.  The best part is that the template is smart enough to recognize the difference, so the only thing that will change in our code is the actual value we pass in.  Here’s the code to make the update to the badge:

var notifications = Windows.UI.Notifications;

var template = notifications.BadgeTemplateType.badgeNumber;
var templateContent = notifications.BadgeUpdateManager.getTemplateContent(template);

var element = templateContent.selectSingleNode("/badge");
element.setAttribute("value", "31");

var update = new notifications.BadgeNotification(templateContent);
notifications.BadgeUpdateManager.createBadgeUpdaterForApplication().update(update);

Just like the tiles and toast I am setting an attribute on the badge element. In this case I am setting the value attribute to 31. That results in a Lock Screen badge that looks like this:

If you would rather use one of the glyphs, here’s a list of what’s available, courtesy of the Badge overview page on MSDN.

To specify a glyph rather than a number, we only need to change the value attribute to the name of the glyph listed above.

//set
element.setAttribute("value", "alert");

//result
<badge value="alert"/>

That’s about it for Lock Screen apps… Overall this is pretty easy. We’re limited in what what we can display on the screen but if you’re awesome then maybe you’re up there.  

Wait… There’s a few more things. Let’s crawl into the weeds. 

When we started this article we jumped right into the app manifest file. The first thing we did was update the Lock Screen Notifications to chose “Badge and Tile Text” in our appxmanifest file, we enabled these Badges we’re creating to appear on our Tile as well.  (This is why the WideTile.png file was required.)  Here’s what my Live Tile looks like with that same “Playing” badge applied:

Man that tile is just ugly but, ok you get the point. Initially I thought, sweet my work here is done, but something was bothering me. The word text in Badge and Tile Text. We really haven’t displayed any true text right? Turns out the story wasn’t done. If you’re setup for Tile updates you can actually have your app display those tile updates on the Lock Screen too. Wait, what?!!? Yep. Let’s go to: Setting –> Change PC Settings –> Personalize. Look really close at the bottom right hand side of the settings. Choose an app to display detailed status. Select that guy and your app should be listed in the menu. Choose it! Right now!

After doing so, when your app is running your tile text will also show up on the screen. Check out the sauce there.

But wait, who is the lucky winner? I guess that is for you to choose. It appears that your app has no rights to even put itself in that box.

- read this -

Now during the course of writing this there were a few things that I came across.

#1: setTimeout is your friend at least when trying to manually test this. To see what was going to get displayed on the lock screen, I created a silly button in my app. The handler for my button looked like such:

clearNotifications();

setTimeout(function () {
    sendBadgeUpdateXML();
}, 5 * 1000);

setTimeout(function () {
    sendTileUpdate();
}, 6 * 1000);

This allowed me the time to fire off the events and lock the machine. Then I could sit back and watch the magic happen.

#2: There are “three” different ways to fire off badge updates. Why you ask? No clue. The all seem to work the same regardless. First there are two templates:

var template = notifications.BadgeTemplateType.badgeGlyph;

var template = notifications.BadgeTemplateType.badgeNumber;

As the templates would imply, one is for the number and one for the glyph. That is a bit confusing when you know that the xml is just:

<badge value="31"/>

Turns out, it just doesn’t matter which one you pick. They act the same. Maybe down the road this will have more relevance so I would use what  you want to “semantically” do.

So that was 2 different ways. What the third. Well just raw XML manipulation.

var badgeXmlString = "<badge value='alert'/>";

var badgeDOM = new Windows.Data.Xml.Dom.XmlDocument();
badgeDOM.loadXml(badgeXmlString);

var notifications = Windows.UI.Notifications;
var badge = new notifications.BadgeNotification(badgeDOM);
notifications.BadgeUpdateManager.createBadgeUpdaterForApplication().update(badge);

It’s straight forward and works but you pick your poison.

Summary

We can update our Lock Screen information from our app at any time, but the tricky part is getting the user’s permission.  Once you’ve gotten that, updating the information is pretty simple, as we saw in this article.

If you would like to download a working application that uses the code from this article, click the icon below:

Tomorrow, we’re going to wrap up the last three days by talking about Background tasks.  We’ll show how to update Live Tiles, Toast notifications, and Lock Screen data from a background task.  See you then!

This article is Day #10 in a series called 31 Days of Windows 8.  Each of the articles in this series will be published for both HTML5/JS and XAML/C#. You can find additional resources, downloads, and source code on our website.

Yesterday, we spent some time looking at Live Tiles, and how to let your users know about important information from your app.  Today, we’re looking at a different type of user notification: Toast Notifications.

If you haven’t worked with Toast Notifications in the past, the word might seem a little silly to you.  The word “toast” in this case, comes from the image of a piece of toast emerging from a toaster. Yummy. Our notifications appear in a similar way, popping up in front of our user to let them know when something interesting has happened.

The primary difference between Toast notifications and Live Tile notifications is that Toast messages will appear on the user’s screen regardless of which app they are currently running.  By default in the top right hand corner. Live Tiles have to be viewed on the user’s Start Screen.

Toast messages scream “YOU NEED TO KNOW THIS INFORMATION RIGHT NOW!” where Live Tiles are significantly more passive.  Be sure you consider this when you’re sending toast messages.  If you’re spamming them with unimportant nonsense, they’re going to turn off your ability to send notifications, or worse, uninstall your app.  Make sure you take a little time to read Microsoft’s guidance on toast notifications before you get too deep into this.

For reference, here’s a few examples of Toast notifications.

Just like Live Tiles, there’s an entire catalog of Toast Notification types you can use, but we’ll get to those in a moment.

Enabling Toast Notifications in Your App

Our first step to greatness with Toast Notifications is actually enabling them in our application manifest.  Open your package.appxmanifest file to the Application UI tab, and select “Yes” from the “Toast capable” dropdown list.

It will be very tempting, as you go through this article, to create a Badge logo file, and upload it to your application, but for this tutorial, don’t.  Here’s why:

If you upload a Badge Logo, you must enable Lock Screen Notifications.  However, if Lock Screen Notifications are enabled, you must have a Background Task.  We’re not covering Background tasks for two more days, and Lock Screen updates are tomorrow. Just be patient.

Today, we’re focused on notifying the user via a Toast message.  Let’s get to that.

Launching a Toast Notification from Your App

Yesterday, Day #9’s article focused on Live Tiles, and if you read that, launching Toast Notifications is going to seem *incredibly* familiar and I am not going to go into the same amount of detail here.  Just like live tiles there is an xml schema which represents the toast we want to send, note <toast>.

<toast>
    <visual>
        <binding template="ToastImageAndText01">
            <image id="1" src="image1" alt="image1"/>
            <text id="1">bodyText</text>
        </binding>  
    </visual>
</toast>

As we did with Live Tiles, we do the same or very  similar with toast. 

• Get an instance of WinRT Notification
• From Notifications, get your Template
• From that Template, get it’s content aka that XML we showed above
• Select and Update appropriately
• (optional) set your duration
• (optional) set audio
• (optional) set any app launch parameters
• Create a new tile notification
• Send tile update

var notifications = Windows.UI.Notifications;

var template = notifications.ToastTemplateType.toastImageAndText02;
var toastXml = notifications.ToastNotificationManager.getTemplateContent(template);

var toastTextElements = toastXml.getElementsByTagName("text");
toastTextElements[0].innerText = "31 Days of Windows 8";
toastTextElements[1].innerText = _toastMessage.value; //taking from screen

var toastImageElements = toastXml.getElementsByTagName("image");
toastImageElements[0].setAttribute("src", "ms-appx:///images/clarkHeadShot.jpg");
toastImageElements[0].setAttribute("alt", "Clark's Head");

var toast = new notifications.ToastNotification(toastXml);
var toastNotifier = notifications.ToastNotificationManager.createToastNotifier();
toastNotifier.show(toast);

As you can see this is scary similar to Live Tiles. I am setting two text properties, and one image property.  For the image, you’ll notice I added an extra line this time, referencing the “alt” attribute.  If you’ve done any web development before, you probably already know what that is, but it’s an important piece of the accessibility story on Windows 8.  It provides a text representation of the image, for those users that are unable to see their screen.

Finally, we create a new ToastNotification object, and show(toast) it on the screen.  That’s the simple story to creating toast notifications in Windows 8.  And here’s what that exact tile looks like on my machine:

But wait, there’s more!  If you created a project, and launched the toast message, you may have noticed that there is an audio clip that goes with it.  This is the default Toast Notification sound, but you have options.  There’s also some other cool things you can do with toast messages.

Setting the Audio for a Toast Notification (and more!)

Everything about creating a Toast Notification stays the same, but we can add some additional nodes to our XML to select a different audio sound, set the duration of the message, and even dictate a page to launch when the notification is clicked (with query parameters as well!)

First, regarding audio, I have some bad news.  You can’t use your own custom audio file.  I know you were hoping to delight your user with the sound of a popping toaster, but it’s just not possible.  Instead, you can select from a list of 9 audio files, 4 of which are looping sounds that can be used like ringtones or alarms.  You can see the entire list of the audio files and descriptions available to Toast Notifications here.

To set the audio, we first need to crack open the XML we’ve been creating.  By default, none of the Toast Templates have an audio node defined, so we need to create one.  First, we need to dive into the <toast> node of our template, and then we can set our options.  In the code sample below, I’ve excluded code for creating a Toast notification ( just look above ) and just added the part where we would modify the template to add our audio clip.

....

var toastNode = toastXml.selectSingleNode("/toast");

var audio = toastXml.createElement("audio");
audio.setAttribute("src", "ms-winsoundevent:Notification.IM");
toastNode.appendChild(audio);

....

You an also set the duration, how long it will stay on the screen for a piece of Toast.

....

var toastNode = toastXml.selectSingleNode("/toast");
toastNode.setAttribute("duration", "long");

....

It’s important to remember that all of the options are optional, as you could see by their absence in our first example.  Here’s a couple of things to remember about these options:

• Long duration Toast messages are meant for things like VOIP calls and alarm clocks, not for email notifications.  Use this sparingly.
• All of the looping audio options that are available will only work if you have set the duration to Long.
• The looping audio options will only work if you also set the “loop” attribute to true.

Failure to follow those rules will result in the Notification.Default audio to be played instead.

In addition, you might want to have SILENCE for your toast message instead of any of the audio options.  You can do that.  In that case, you still specify an audioNode, but you set a new attribute, silent, to true, like this:

var audio = toastXml.createElement("audio");
audio.setAttribute("silent", "true");

This will result in a silent, but otherwise normal toast notification for your user.  Finally, there’s the “launch” attribute.  Within this, we can pass any text string that we’d like, and it will be passed back to us as a page parameter when the toast message is pressed by the user.  This data should allow you to determine which page to direct them to, with which data populating it.  Don’t put anything in the “launch” parameter that doesn’t need to make the trip.

....

var toastXml = notifications.ToastNotificationManager.getTemplateContent(template);

...

toastXml.selectSingleNode("/toast").setAttribute("launch", '{
                "type":"toast",
                "args1":"31days",
                "args2":"#10"}' );

....

Summary

That’s about it for Toast Notifications in Windows 8.  Very similar to Live Tiles, toast messages are a great way to get the user’s immediate attention, no matter what they are currently doing.  Some of you are probably wondering how we make these updates from a Background task, and for you, we ask for patience.  We wanted to make sure we gave a solid overview of each of these notification types before we dove headfirst into Background tasks.  You’re only two days away from that topic, I promise.

If you would like to download the entire code solution for this article, click the icon below:

Tomorrow, we’ll cover our last topic in the notifications world, Lock Screen.  See you then!

Today, we’re covering a very important topic: Live Tiles.  As we’ve mentioned in previous articles, your tile is one of the most important parts of your application’s success, and it’s one of the most overlooked.

Your tile represents your relationship with your user.  They caringly pin it to their start screen, arrange it with similar apps, even decide if they want it to be big or small.  Your job is to make it as accommodating and responsive to their needs as possible.  We do this by passing useful updates to the tile.  Here’s a few examples from some of my favorite apps:

The family and I have gotten into a game called Jetpack Joyride, their tile is an excellent example.  Here’s four of the five states it rotates through, reminding me of my high score, as well as the achievements I haven’t yet completed.  These updates have dragged me back in more than once.

The weather app, on the other hand, doesn’t flip at all.  But I also don’t need anything more that what one static tile can provide when it comes to weather.  I get today’s high and low, as well as the current temperature.  The five day forecast is always one click away.

Finally, as tiles go, I think that the Photos app might be my favorite.  I haven’t figured out how often it updates the set of rotated photos, or even which libraries it uses, but it always seems to have some great old photo on the tile that makes me remember that event.  Here’s a couple of screen shots of my Netduino garage door controller and some awesome peeps That Conference’s Game Night. Might I suggest you check out That Conference, August 12 – 14 in 2013.

I’ve got thousands and thousands of old photos stored in my photo libraries (yes, they’re backed up online, thank you very much), and getting a blast from the past on a daily basis is awesome.

The Rules

When we work on our apps, I’ve discovered there are a few rules we need to be aware of:

• First, read, and then re-read the Guidelines for Live Tiles.  They’re extensive, but interesting.
• You must ALWAYS have a small tile.  Wide tiles are a nice-to-have, but you MUST accommodate a small tile.
• If you want wide tile notification you MUST provide a default wide tile.

Small tiles are not always as interesting as their big brothers, but they can still be conveyed to show interesting information.  Here’s a few small tiles which range from showing nothing but branding to showing updates on your local weather:

Things like SkyDrive don’t update but one could argue what is there to update? However the Weather and Photos apps give me all the same data I get on the large tiles, just in a smaller package.

As I was investigating all the different ways a tile could look, I was worried that this article was going to be SUPER lengthy after showing an example of every possible tile template.  As it turns out, however, Microsoft has provided an amazing page that shows every single tile template, all forty-five of them.  Make sure you check this page out.  It will definitely help you pick the tile template that is appropriate for you, and it provides the XML markup you’ll need to do it as well.

MUST READ: The Tile Template Catalog

So how do we make our tile dance?  Let’s dance.

Updating the Default Static Tile

By default, you’ve got an icon in your app that looks like this:

(I added a slight gray background to this one so you can see it on a white background, yours is likely transparent.)  If you only want a static tile that uses your own 150 x 150 pixel image, you can do this one of two ways:

• Replace the image that currently resides at images/logo.png in your project.
• Update your package.appxmanifest file, and change the Logo value to a different image in your project, like this:

OK, enough of the boring stuff.  Let’s write some code!

Sending a Notification to a Small Live Tile

Let’s start with sending a small tile notification first, since large tiles will be slightly more complicated.  First, as we discussed earlier, you need to decide which template you want to use from the catalog.  (We’ve  even created a static PDF version of this document for you, that’s how important it will be!)

In this example, I’ve chosen TileSquareText04, which looks like this template:

And is represented by this XML (you’d know this if you’d open the catalog page):

<tile>
  <visual>
    <binding template="TileSquareText04">
      <text id="1">Text Field 1</text>
    </binding>  
  </visual>
</tile>

Now I am sure you’re sitting there thinking, can I use JSON? Well, unfortunately not that I am aware of.  So now we just need to create a new tile update based on that XML, and push it to the TileUpdateManager.  Here’s how it works for TileSquareText04:

• Get an instance of WinRT Notification
• From Notifications, get your Template
• From that Template, get it’s content aka that XML we showed above
• Select and Update appropriately
• Create a new tile notification
• (optionally) set expiration
• Send tile update

That’s it! No really, that’s it. Ok it seems like a lot but it’s really just a few simple functions and you could wrap that up into a nice factory, pattern here, beer there and boom.

var notifications = Windows.UI.Notifications;
var template = notifications.TileTemplateType.tileSquareText04;
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);

var tileTextAttributes = tileXml.getElementsByTagName("text");
tileTextAttributes[0].innerText = _tileMessage.value; // taking from input box

var tileNotification = new notifications.TileNotification(tileXml);
notifications.TileUpdateManager.createTileUpdaterForApplication()
    .update(tileNotification);

So how do you handle the other templates? Can you mix or match? Well you just select the other template, modify the xml accordingly and send it along. Let’s extend what did above to send along for the tile below.

....

var template = notifications.TileTemplateType.tileSquareBlock;

....

var tileTextAttributes = tileXml.getElementsByTagName("text");
tileTextAttributes[0].innerText = "31"; 
tileTextAttributes[1].innerText = _tileMessage.value; // taking from input box

....

As you can see this is a pretty simple process.  One final note about these templates is that it’s likely your SmallLogo.png file will be displayed on some of these tiles as well.  It’s a great way to extend your branding, but it’s also something to be aware of as you’re working on this.  Using the TileSquareBlock template, here’s how my tile actually ends up looking:

This is yet another reason, as we stated on Day #1, for you to use custom images for your app as you explore Windows 8 development.  Without that purple image, I would have had to guess which one was being used, or worse, not realize that it was available at all.  You will see that there are many properties that can be edited for your tile in the package.appxmanifest file of your project.  Not only can we swap out the logo image, but also set background properties, the Small Logo file, and other text and color values.

One important piece of this section is the “Show name” dropdown.

I briefly mentioned this earlier, but I want to make sure you understand where these images and values are established.  In addition, simply by defining a Wide Logo file in this manifest, you immediately support the Large Tile size.  In fact, this is the ONLY way to support a wide tile.  Your application won’t even offer the size as an option until you’ve specified that value.  Give it a try.  Now let’s look at how we send updates to a Large Tile.

Sending a Notification to a Large Live Tile

This time, we’re going to choose a Large Tile template, but we’ll also include an image, so that you can see the syntax for that as well.

Important Lesson:  Remember that the user is in control here.  If they have decided to make your tile large or small, you don’t get to decide that.  What you can decide, however, is whether or not you want to support “notifications” in both sizes.  I recommend it, because it’s an opportunity to have your user pay attention to your app on their Start screen.

Because of this, when we send updates, we can actually create two.  One for the small tile, and one for the large one.  Then, through the magic of XML, we’ll merge them together, and send them as one notification, then regardless of what the user has set, they will still receive notifications. But to do so, you will have to have a wide tile set by default in your package.appxmanifest. If no wide, no notification, regardless of what you have sent. Let’s create these two (I think you should use them in your application too):

The tile XML will end up looking like this:

<tile>
    <visual lang="en-US>
        
        <binding template="TileSquareImage">
            <image id="1" src="/images/clarkHeadShot.jpg" alt="Clark Sell"/>
        </binding> 

        <binding template="TileWideSmallImageAndText03">
              <image id="1" src="/images/clarkHeadShot.jpg" alt="31 Days"/>
              <text id="1">31 Days of Windows 8</text>
        </binding>  

    </visual>
</tile>

Now you already know how to create and modify the small tiles. To modify the large is exactly the same, just different template, and more opportunity to modify things.

var wideTemplate = notifications.TileTemplateType.tileWideSmallImageAndText03;
var wideTileXml = notifications.TileUpdateManager.getTemplateContent(wideTemplate);

var wideTileAttributes = wideTileXml.getElementsByTagName("image");
var wideTileTextElements = wideTileXml.getElementsByTagName("text");

wideTileAttributes[0].setAttribute("src", "ms-appx:///images/clarkHeadShot.jpg");
wideTileTextElements[0].innerText = "31 Days of Windows 8";

Take a close look and you will see that I am actually pulling an image from some weird src, it’s actually the local package. You could use just “/images/clarkHeadShot.jpg” too. You also have the ability to use images that are hosted out on the web or even in your local storage.  Of course the more network hopes something has to take the longer it will take to load, so keep that in mind when using them. Also, to pull images from the web you will need to adjust your apps capabilities in your manifest to allow for internet access. If you do that, you need a privacy policy too.

To merge the two tiles together. We’re basically going to take one template and add it to another.

var node = wideTileXml.importNode(smallTileXml.getElementsByTagName("binding").item(0), true);
wideTileXml.getElementsByTagName("visual").item(0).appendChild(node);

As you can saw above, we will end up with multiple bindings in one <visual> node.  To add additional notifications, you would go through the same process, adding even more to this same node.

- tip -

Above we mentioned there we’re a few different ways we could reference resources like images. Let’s look at a few.

• ms-appx:///images/Cats.png – reference your local package
• ms-appdata:///images/Cats.png – reference ApplicationData.LocalFolder
• /images/cats.png – typical local reference
• http(s)://31daysofwindows8.com – http(s) reference

Clearing Your Notifications

There are also going to be times where you’ll want to delete your notifications.  Perhaps new information has become available, or something changed before your expiration dates have expired, and you need to start over.  To do this, it’s a simple line of code:

var notifications = Windows.UI.Notifications;
notifications.TileUpdateManager.createTileUpdaterForApplication().clear();

Expire Notifications

Should your notification last forever? Well I can’t answer that, but I am thinking that some of those notifications might in fact need to be cleared out. By default local tile and badge notifications do not expire while push, periodic and scheduled notifications will after three days. To expire a notification just set the expirationTime on your tile notification.

var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);

I know you we’re expecting something much harder. So, we’ve covered small and large tiles, even in combination, but what if you want to provide your user with multiple tiles?

Secondary Tiles

Secondary tiles are an excellent way to surface the information your users want directly to their Start screen.  If you’re a weather application, they can pin multiple cities for a quick reference.  If you’re the People app, you allow me to pin the people that are important to me, so that I can easily see what they’re up to.

I originally intended to write an entire section here about how to actually pin a Secondary Tile to your user’s start screen, but Microsoft has done a phenomenal job already.  Check this out:

Quickstart: Pinning a Secondary Tile

Not only do they want you through creating a Secondary Tile, but they also provide you with all of the code to prompt the user from an AppBar, determine if it has already been pinned, and even remove the tile when it’s not necessary anymore.  It’s a great tutorial, and I highly recommend it.

From the cloud

Push, Periodic and Scheduled notification are something we haven’t touched on yet, but I am going to save that topic for another time. Tomorrow we’re talking toast and the two really go hand in hand when we’re talking about something like push notifications.

Summary

We’ve covered a great deal of content today related to Windows 8 Live Tile updates.  From creation to updates, you can see that it’s pretty simple to do from your app.  I can’t recommend updating your app’s tiles with relevant information as frequently as possible.  It will make your app that much more appealing to your user.

To download my entire solution of sample code for this article, click the icon below:

Tomorrow, we’re going to look at the other side of notifications: Toast messages.  Until then, happy coding, and we’ll see you tomorrow!

Today I am proud to release something called On Time. This is an app that I dreamed up about a month ago and today it’s in the Windows Store.

Short story: On Time is monitor for speakers, presenters or just very time conscious people who want to closely monitor their current spot against an agenda.

I hope you will try it out, provided feedback and learn something along the way. This is just the start of a bigger journey.

What is On Time?

On Time is a simple Windows 8 application striving to keep speakers “on time”. If you’re a speaker this is for you. Grab a Windows 8 machine, load in your presentation’s agenda and set it down in front of where you plan on speaking. On Time will display your overall time left, where you should be in your agenda and how much time is left until your next topic. Don’t worry, On Time has a few visual cues to make sure you’re paying attention along the way.

Built for us, developers

I didn’t and don’t want to build this in a vacuum, so it’s all out there for you to see, comment or even collaborate on if you want. It’s real, it’s raw, but it’s shipping. I am guessing a large number of people start with an idea, turn it into a spike and then whoops it’s now a published application. Same here, except I wanted to start this way. I wanted to see if my idea first even worth something before investing a great deal of time. Having said that, it’s worth something to me so I guess it’s a mute point.

I will refactor. Part of starting this way was to quite honestly put myself in a uncomfortable spot. I want to introduce automated tests, patterns, automated build and so on But I want to talk about it along the way and hopefully help a few others out as well.

You can find it all here on GitHub.

Built on open source

Regardless of whatever title I might carry today, I am a web developer. Open source is a big part of our ecosystem and community. The core of On Time is built on Knockout.js. Knockout.js is an amazing tool and I can’t thank that team enough for the awesome work they have built. Windows 8 embraces Open Source just like the web does. As a web developer it’s pretty cool to be able to take some of the tools you’re used to using and use them in your app.

Open source tools used thus far:

• Knockout.js
• Font Awesome

What’s next:

• Website for On Time
• Add a User Voice Site for feedback and suggestions
• Launch the app when clicking on an OT file.
• Update interaction between agenda and main screen
• Pause
• Switch color schemes
• Clean up code – blog series coming there.

Special Thanks:

I would like to thank the following peeps for their support and help.

• Brandon Satrom: Very close friend and business partner of mine. Brandon wrote an app called Tom8to while writing his soon to be released book on Windows 8. I learned a number of things just by browsing his source and seeing what his thought process was compared to mine. I also stole a few nuggets from him.
• Lwin Maung: Friend and Colleague of mine. Lwin cut all of the graphics you will see for On Time and did a bunch of testing.
• Min Maung: Friend and Colleague of mine. Min tested this guy during a number of speaking engagements. He also keeps priming the pump with new features.
• Ryan Niemeyer: Ryan is on the core team of Knockout and has helped me out more than enough times as I have been learning Knockout.

In several of the articles in this series, we’ve mentioned that storing data is not only incredibly important, but also that it’s easy to do, both locally to a device, as well as roaming across the many different devices a user may use.

Microsoft offers us some specific guidance on when to use roaming vs. local storage, but I’ll give you a quick summary here so that you’ve had a chance to read it (because we both know you didn’t click that link).  Again, these are guidelines, so you’re not going to get denied from the store for breaking these rules, but there are also limits to data transfer size and speed.  Exceeding those will prevent your app from actually roaming data for a period of time.

DO

• Use roaming for preferences and customization.  Any choice that a user is likely to make on each machine that they use should be roamed.  These are basic settings, like color preferences, favorite actors, or whether or not to publish data to Twitter.
• Use roaming to let users continue a task.  Having my browser favorites follow me around, or even my high scores is awesome.  Allowing me to continue writing that email (or blog post) I never finished? Even better.

DON’T

• Use roaming for information that is clearly local-only.  This includes things like file paths and other data that only makes sense to the local device.
• Don’t roam large datasets.  There is a quota, which you can determine in code, that limits the size of your roaming dataset.  It is best to only roam preferences and small data files, as we will show in this article.
• Don’t use roaming for instant synchronization or rapidly changing data.  Windows controls when and how often your app data will be roamed, so don’t count on instant synchronization.  Build a web service of your own if you need this kind of reliability.  Also, don’t update the roaming data constantly.  For example, you don’t need to roam the user’s current location at all times, instead update it every minute or so.  You’ll still provide a rich experience without destroying your quota.

One last thing to remember: the way data is roamed across devices is managed by the user’s Microsoft account.  If they log into two machines with the same account credentials, AND they install the same app in both places, THEN the roaming settings and files will travel.  Until then, nothing happens.

Now that I’ve scared you into never using this, let’s take a look at how it’s done.  There are two types of data that can be stored, and we will address each one of them both locally and roamed.  First up is Settings, followed by Files.

Local and Roaming Settings

When you hear the word “settings” in Windows 8 (or even Windows Phone) development, “small, simple data” is what should come to mind.  We’re really talking about storing name/value pairs.

Good examples of these are user preferences.  Perhaps you stored the user’s first name (a string value) so that you could address them as such in your game.  Maybe they decided to turn off notifications (a boolean value) from your app.  Settings are also one of the easiest ways to store data, and I’ve found myself on more than one occasion storing a great number of settings values in my applications. Because these are invisible values that live in an invisible data store, it might be good to wrap the usage of these with a nice CRUD pattern. 

To save this data locally we just leveraging the Windows.Storage.ApplicationData object. To easily explore all of this let’s just create the worst UI with a couple of input boxes and labels. We will just throw data into the input box and expect it to populate the label. As the app cycles we will save those values off to local storage. **I am begging you not to copy this UI**

<div>
    <ul>
        <li>
            <input type="text" id="inputA"/> <label id="labelA"></label>
        </li>
        <li>
            <input type="text" id="inputB"/> <label id="labelB"></label>
        </li>
    </ul>
</div>

Now that we have input. I am just going to create a couple of functions and wire up the changed event to our input box. When the changed event fires we will set the label. Nothing special and not really a real life scenario, but we’re trying to prove a point here.

....

function getDomElements() {
    _inputA = document.querySelector("#inputA");
    _labelA = document.querySelector("#labelA");
    _inputB = document.querySelector("#inputB");
    _labelB = document.querySelector("#labelB");
}

function wireUpHandlers() {
    _inputA.addEventListener("change", inputALeave);
    _inputB.addEventListener("change", inputBLeave);
}

function inputALeave() {
    _labelA.innerText += _inputA.value;
}

function inputBLeave() {
    _labelB.innerText += _inputB.value;
}

app.onready = function () {
    getDomElements();
    wireUpHandlers();
}

....

Again, just plumbing code and I even cut out some of it, like the variables. With the pipes now in place, now let’s integrate local storage. For a brief moment lets assume that’s a hella awesome UI which is actually some application data like your twitter handle and blog address. Hang with me, I promise awesome.

As a user I would should expect that things like this to carry with my app. Right now if I was to run it things would work as expected but the next time I would fire it up, I would have to re-enter all that. This makes little puppies extremely mad. To save the puppies, lets leverage that ApplicaitonData object I mentioned earlier. I am going to create two new functions; get and save.  Since localSettings is just key value pairs, we can easily just start adding whatever values we want.

var _applicationData = Windows.Storage.ApplicationData.current;
var _localSettings = _applicationData.localSettings;

function saveLocal() {
    _localSettings.values["inputA"] = _inputA.value;
    _localSettings.values["inputB"] = _inputB.value;
}

function getLocal() {
    if (_localSettings.values.size > 0) {
        _inputA.value = _localSettings.values["inputA"];
        _inputB.value = _localSettings.values["inputB"];
    }
}

Easy enough. So now where do we call them from? First let’s save and one of the proper places to do this in our friend PLM ( I promise we will cover it, but I am starting to think we should have moved it forward ).  PLM has an event called checkpoint. Checkpoint is actually already wired into the Visual Studio Templates so we will just put our call into the existing function.

app.oncheckpoint = function (args) {
    saveLocal();
};

Run your app, drop some data in, and then kill it. If you running in the debugger you will notice that it still runs for a second or two. At some point checkpoint will fire and a saving  to local storage you will do. Next, get the data. Let’s just call our getData function on onReady which would look like this.

app.onready = function () {
    getDomElements();
    wireUpHandlers();
    getLocal();
}

And like that your app just became a bit more awesome. We’re saving some data.

Roaming

I know what you’re thinking. That was easy, I am sure this roaming thing will just be a pig. Let’s change localSettings to roamingSettings.

var _localSettings = _applicationData.localSettings;

TO

var _localSettings = _applicationData.roamingSettings;

Yea that’s it. What ever you do, please DO NOT tell your boss. That feature right there just put at least 120 hours back on your project. The way I see it, you now owe me a beer.

Given what we have already put together, everything will work as expected. Deploy the app to two different machines, fire up one and make set the input boxes. Then when you fire up the other, those text boxes will receive those new values too. If the data that you’re saving is under 8k, then that save will should happen right away, anything over will take longer.

Of course, there is the scenario where maybe you would like to be alerted on your other machine when the change happens. We can do so, by registering for the datachanged event on roamingSettings.

_applicationData.addEventListener("datachanged", datachangeHandler);

I personally haven’t seen the notification fire instantaneously but it does in fact fire. From our handler we can then do whatever we need to with out new updated data.

- tip -

During the course of writing this, I wanted a way in that datachanged event hander to actually update the labels as well as my input boxes. I had already written handlers for the input boxes change event so I figured why not just fire them again. You may have caught in yesterday’s sharing article I registered and fired some events off in the activation of the Sharing Target such that we didn’t block activation. We did that using WinJS.Application.addEventListener.

WinJS.Application.addEventListener("forceA", inputALeave, false);

Once we register “forceA” if you will we can then later fire it.

WinJS.Application.queueEvent({ type: "forceA" });

I thought it was pretty cool, maybe you will too.

Staying Organized

The more “settings” you create having the ability to add a little organization to the process would be nice. Storage has something loosely called a “composite” which you can just think of as a bucket of settings.

var composite = new Windows.Storage.ApplicationDataCompositeValue();
composite["setting-1"] = 1;
composite["setting-2"] = "string";

_localSettings.values["myComposite"] = composite;

There are also a couple of helper methods hanging off the ApplicationData class. They give you the ability to clear things out, signal event handlers and even set a version number on that data.

As you’re building your apps, it’s important to remember that all of this data, both settings and files, are sandboxed to your application.  What this means is that when your application is uninstalled, all of the values are gone with it.  This also means that when you’re building an app that uses these values, and you want to start with a greenfield user experience, you might want to uninstall the app from your machine before testing it to get rid of any legacy values that may have been saved earlier.

So we’ve taken a deep look at Settings, let’s move on to files now.

Local and Roaming Files

Files operate in a very similar way to settings, except that we are actually reading and writing the values to the hard drive, and I’ll demonstrate that in this example as well.  Like loacalSetting and roamingSettings we just need to create temporaryFolder.

var _tempFolder = _applicationData.temporaryFolder;

Once we have our temp folder we can work with it much like anyone would expect. Below you will see I am grabbing the path WinRT is going to use, then I am using a promise to save, while always replacing the file if one exists. We don’t have to specify folder locations, we don’t even have to define a folder structure if we don’t want to.

function writeFile() {

    _filePath.innerText = _tempFolder.path;

    _tempFolder.createFileAsync("31DaysOfWindows8.txt",
        Windows.Storage.CreationCollisionOption.replaceExisting)
            .then(function (sampleFile) {
                var contents = JSON.stringify(_dataFile);

                return Windows.Storage.FileIO.writeTextAsync(sampleFile, contents);
            }).done(function () {
            });
}

In addition, you can look at your files as they are saved.  Each application stores its files locally on the machine, and if you use a breakpoint, you can determine that location on your device.  For instance, the file we created above was at path:

C:\Users\Clark\AppData\Local\Packages\53657140-d0da-4374-9606-b653e55dfd93_rhg4v0b7gygzg\TempState

Once you’ve created it, you can actually crack the folder open and see the contents, even open the files yourself. Otherwise, that’s about it!  Saving files, even large files, can be done this way.  You only need to remember the file name that you gave them.  The Windows 8 sandbox takes care of the rest.  Please note that my example above actually only stores a local file, but that you use the EXACT same code (with a reference to ApplicationData.Current.RoamingFolder instead) for Roaming files.

As a reminder, roaming files will not transfer immediately, so don’t expect the type of performance you’ve seen with Skydrive or DropBox’s applications.  Be mindful of the data quota, but otherwise, use this stuff extensively. 

Summary

Settings and Files are a powerful tool in our Windows 8 development arsenal. It’s easy to do, and makes your application so much cooler when it lights up multiple machines at once. To download all of the sample code from this article, click the icon below:

Tomorrow, we are going to discuss Live Tiles, and how we create both primary and secondary tiles, as well as how we update them.  See you then!

Over the past two days we’ve dived into this a new Windows feature loosely called contracts. We introduced this notion of contracts by exploring how to incorporate something called Settings into our applications. Then we explored extending our applications presence to users with Search. Today we’re going to take the next step and explore one of the features that gets both Jeff and I really excited, Sharing.

I will just come out and say it, Sharing is a really cool feature. At its most basic principle, the premise is to take something a user found interesting and share it. Like the other contracts, the foundation of sharing isn’t any different. Our application hooks into an “interface” and Windows takes care of the rest. But this feature is different.

For the most part, people are social beings. We talk to one another, share exciting stories and love being loved. Windows 8 feels alive, welcoming users and their apps to interact with other apps, or other people.

The Sharing contract is at the core of this experience. Today’s application developers have a huge eco system to try and get plugged into. Email, Bit.ly, Facebook, Twitter, [insert your favorite this here], and it’s endless and always growing. As a developer, trying to keep up with this can be crazy. What if there was a better way. Can you guess, yes, Sharing.

As you install applications on your Windows 8 machine, something starts to happen. Your applications can start becoming more feature rich. When applications implement the Sharing contract other applications start to become more alive with capabilities. Let’s take something like the browser. I’m guessing anyone reading this has found a webpage that they wanted to share with someone. That could be either Twitter, Email or even something like a local app that keeps bookmarks. It’s impossible for any app to try and keep up with that ever-changing eco system. Rather if we all implement the sharing contract for the types of data that we each can consume then suddenly the core features in our apps start to grow without us doing any work. For example when the user decides to install Twitter because it’s what they like, and Twitter implements the Sharing contract then automatically it will show up in the list of things that accepts sharing.

This is a very powerful feature and one which adjusts to its users. If Twitter isn’t there thing but Facebook is, chances are they don’t have a Twitter app installed and it’s not clogging up their list of apps to share to. Better yet, you never even had to write to any of that, but rather just program to the Share contract.

Sharing Defined

Sharing happens two ways, he who shares ( the source app )  and he who receives ( the target app ). This happens through a broker.

Image via: http://msdn.microsoft.com/en-us/library/windows/apps/hh758314.aspx

So, what can you share? There are 7 different types of content you can share with the broker:

• Unformatted Plain Text
• Link
• Formatted Content / HTML
• File
• Single Image
• Multiple Files and Images
• Custom Data Format

Data is shared through an object called the DataPackage.

Sharing

Let’s start easy with sharing ( data flowing out of our app ). Today I want us to start with a different template, one called the Navigation App. This app is very similar to the blank app template except for adding some plumbing in a navigation model. The best way to think about this navigation model would be just like a single page web site model for the web. Out of the box the default.html page can act like a container for the rest of the site. The reason for starting here, is to create a more complicated “application” for us to work through. Sharing is context sensitive so, if a user navigated to page A verses page B what they might or might not share could be different. I will cover app navigation in detail in an upcoming article.

With our template in place, let’s just run. After your app is fired up, activate your Charms menu and select Share. Windows will tell you you that your app can’t share. Of course not, we haven’t really done anything.  To hook into the Share Charm we need to wire up to an event from the DataTransfer object.

var dataTransferManager =
    Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", dataRequested);

Now when the user is in your app and activates the Share Charm the broker in Windows will fire off your handler. When your function is called, it passes along a DataRequest object for you to populate. Since we’re starting simple were going to populate three properties; title, description and text.

function dataRequested(e) {
    var request = e.request;

    request.data.properties.title =
        "31 Days of Windows 8";

    request.data.properties.description =
        "Have you heard of 31 Days of Windows 8?";

    request.data.setText(
        "Check out 31 Days of Windows 8 at http://31DaysOfWindows8.com"); }

Now in the dataRequested handler above I am just hardcoding the data that we’re exposing through sharing. In a real application we would probably select something relevant to what the user was doing in the application or maybe something they selected. Once your function returns, the broker and the share target will populate that data or item in the appropriate places. This includes the Share Charm itself and later the selected Share Target. As you can see from the image below, the  properties title and description are actually used at the top of the Share Charm.

Then we’re presented with a list of applications ( aka the share targets ) who will accept that data were trying to share, in our case just plain text. Let’s select the mail app from our list.

Now you can see that the mail application has been opened on behalf of Windows. Furthermore the mail application received access to that DataPackage we created earlier.

Now for any page in our application in which we wanted to share, we would repeat this process. ( or so I thought )

Wait What?

So that last statement wasn’t exactly true. I’ve always thought it was very important to share ones stumbling blocks along with everything else. So here goes my midnight fumble.

I started by using the home.html to to implement sharing. Got it all wired up and things worked fine. So then it was time to move onto adding sharing to another page. As you would expect I added notHome.html to the project, and like any good design went back to home.html and added that anchor link to redirect.

Since we started with the navigation template project, I then decided to be a good citizen and wired up the a click handler to our anchor tag so I could use the navigation framework.

WinJS.Utilities.query("a").listen("click",
    function (eventInfo) {
        eventInfo.preventDefault();
        var link = eventInfo.target;
        WinJS.Navigation.navigate(link.href);
    }, false);

Simple enough and things worked as expected. Next up, add sharing to that page right? After adding sharing I saw the following:

Already wired, Huh? On yea, the navigation framework. It’s important to understand the navigation model and its effects your pages and\or the API’s that you might be using. In this scenario we’re just swapping the page in an outer page and WinRT didn’t like that.

Solution? Well, I guess it really depends. It could depend on your page model. It could depend on how you structured your markup and how you select it, it could just depend on what you want to share.

In this case, lets assume you want to share something different on the two different pages. Since we’re in this single page navigation model then our solution ( or “a” solution ) is to just remove our event handlers when the page unloads an recreate them on the next page.

var dtm = Windows.ApplicationModel.DataTransfer.DataTransferManager;

WinJS.UI.Pages.define("/pages/notHome/notHome.html", {
    ready: function (element, options) {
        var dataTransferManager = dtm.getForCurrentView();
        dataTransferManager.addEventListener("datarequested", dataRequested);
    },
    unload: function () {
        var dataTransferManager = dtm.getForCurrentView();
        dataTransferManager.removeEventListener("datarequested", dataRequested);
    }
});

Simple enough but again, it just depends on your situation. Unloading items such as your event handlers is something you should keep a close eye on throughout any application you’re building.

- random tip -

Next time you are running your app and make a little change like update some CSS. Hit “CTRL + Shift + R” which will refresh it in place. It’s a nice way to work in your source code and not have to restart debuggers and whatnot. Think of it like f5 in the browser.

Share Target

On the flipside, the opposite of sharing is the share target, aka the thing being shared to. Just like the other contracts we need to declare that our app can in fact receive shared content from the broker. This is done through our ole buddy the appxmanifest.

After declaring the ability to receive content, we need to setup just what we’re going to be signing up for, specifically the data formats and possibly the file types if we’re in fact sharing files. This of course is telling the broker when to expose your application as a possible share target. For our conversation today, we’re going to accept a URI. Of course you can accept more than one type as well.

At this point lets run our application. Fire up the browser, and select then select the Share Charm. You will see we’re now listed as a possible choice. If we then select it you will see our beautiful splash screen appear before being taken to a blank page. Remember that little nugget on transparent PNGs and setting the background color appropriately?

That blank page we appear to see is actually nothing. We need to configure it. In that Share Target Declaration we just declared. At the bottom, you will find a section called App Settings. In there you will see a start page. This of course defines what page we want to fire when Share is invoked. Of course that means we have to create one, so I have created not only it, but the associated JavaScript and CSS files.

• /pages/shareTarget/shareTarget.html
• /pages/shareTarget/shareTarget.js
• /pages/shareTarget/shareTarget.css

Now if you rerun you should be taken to your page. With our pipes flowing some awesome sauce, let’s wire into the correct events and get our hands on that DataPackage object. We haven’t talked yet about PLM or Process Lifecycle Management, I have mentioned it. It’s exactly where where we’re going to wire in our Share Target.

When our application launched we’re going to inspect the ActivationKind looking for a shareTarget. You could put this logic your default.js page, but I have chosen to put it in my shareTarget.js file just to keep the logical things grouped together. ( best practice, ehh time will tell )  Let’s get our basic structure together.

(function () {
    'use strict';

    var _app = WinJS.Application,
        _activation = Windows.ApplicationModel.Activation;

    var _shareOperation,
        _dt = Windows.ApplicationModel.DataTransfer;

    _app.addEventListener("activated", function (args) {

        if (args.detail.kind === _activation.ActivationKind.shareTarget) {
            args.setPromise(WinJS.UI.processAll());

        }
    });

    WinJS.Application.start();

})();

The biggest difference here from what we have seen before is the usage of ActivationKind. With our structure now in place, during our activation we need to get our share operation and fire off an event async to handle the share. We do this async such that were not blocking the activation process.

_shareOperation = args.detail.shareOperation;

WinJS.Application.addEventListener("shareready", shareReady, false);
WinJS.Application.queueEvent({ type: "shareready" });

Now let’s implement our shareready function. This function will serve as the work horse to populate our screen with the information which came across.

function shareReady(args) {
    if (_shareOperation.data.contains(_dt.StandardDataFormats.uri)) {
        _shareOperation.data.getUriAsync().done(function (uri) {
            document.querySelector("#results").innerText =
                "Uri: " + uri.absoluteUri;
        });
    }
}

Now our scenario is simple. Were just displaying some basic information on the screen. Once we’re done doing whatever we want, we will need to call reportCompleted on the shareOperation, telling the broker we’re done. There are a number of different methods on the shareOperation that we should interact with, especially with long running scenarios and errors. While I am not diving into them here, I have included links below.

More than just display

At this point we have successfully shared and been shared to. The rest is really up to you. That “little” share window could serve as a big feature in your application. If you’re a company like Twitter or Facebook this could be a window into pushing updates to your social graph.

Also don’t forget how we kicked off this notion of contracts, settings. Again if you’re a company like Twitter, then persisting that user profile so when they do share they don’t have to enter their handles, URL shorteners etc. will give your users a very seamless experience. Better yet, roam it so when they get on another machine it’s already setup. We will talk about roaming and storage tomorrow.

What’s next?

Today, we took took a look into at another contract called Sharing. The Share contract provides an amazing new way for your app to expose itself to its users. Now, you just need to determine what exactly you want to either share or accept. Getting yourself in front of your users ensures people are engage with your application. The more ways they use it, the better.

As I mentioned earlier in this article, there are a number of different data types you can Share and while I didn’t cover them in detail here the premise is the same. It’s just different data being set and later retrieved. Below I have listed a number of great references from dev.windows.com which covers those in detail.

• Sharing and exchanging data
• Choosing data formats for sharing
• How to share text
• How to share a link
• How to share an image
• How to share a file(s)
• How to make asynchronous calls in your datarequested handler
• Quick Links

You can download the entire sample solution and tools here:

Tomorrow, we’re going to focus on storing data, both locally on the user’s device, as well as roaming that data in the cloud.  See you then!

Yesterday we introduced Contracts by exploring how to add Settings to our applications. Today we’re going to build upon that with Search, and tomorrow Share. Search and Share are two very interesting contracts because they bring life to your app even when it’s not actually running. In the context of search this means your application can potentially expose itself to the user in a new manner.

For the past 10 years, “search” has typically been synonymous with search engines. A few year ago, search actually became mainstream in Windows and if you we’re like me, you became very used to hitting the start button and just typing the name of your program rather than looking for it. Today in Windows 8 you can just type and those results are nicely displayed.

Better yet, Windows 8 is really extending how we think about search and bringing it right into our Windows Store Apps. Now it’s not really any magic, we just wire up to a few events and display the right things to our users but it changes the typical “entry point” if you will into our applications. Now rather than our user opening our app, finding your command and then acting. They can hit search and be taken directly to the thing they we’re looking for.

Getting Setup

Unlike the past few articles where we’ve started with a blank app, today we’re going to start with the Grid App Template. My reason for starting here rather than with a blank template is simply, hardcoded data. The grid template includes that out of the box and it’s easy for you to use and play with. Once you have created a project you will find this “data” at /js/data.js.

After creating your app, just run it. The first thing you should notice is a sea of the new battle ship black and grey tiles of pointless data. If you click on one you get taken to the detail of that particular item. Cool, we have a running app with some data. Now, let’s search it.

The easiest way to get started is to add a new “Search Contract”. Visual Studio has a built in template and depending on your needs this might be a great place to start. To add a new Contract, let’s first create a folder called search in our pages folder. Then let’s add a New Item, and select the Search Contract from the Windows Store menu.

What just happened?!?! Well:

• Added searchResults.html( default name )
• Added searchResult.css
• Added searchResult.js
• Added the Search declaration to your app’s package.appxmanifest

With that added, we still have one more step. We need to add the searchResult script to our default page, default.html in our case.

<script src="/pages/search/searchResults.js"></script>

Hooking Up

I hope at this point you just scratched your head and said, “wait, why in the world are you adding this JavaScript file to our default page and not our seachResults.html page”. Valid question. There are a few reasons but first we need to just get hooked up to the search contract. We do that by wiring up to onquerysubmitted and the application activation event, which is already written for you (at the bottom) in the searchResult.js file.

onquerysubmitted is fired when a user is in your application and hits the search menu. The Visual Studio Search Contract template has already done this work for you. You can see below we have a function that will grab the search query and pass it along to the searchResults.html page using the navigation framework (more on that later).

    var search = Windows.ApplicationModel.Search;

    search.SearchPane.getForCurrentView().onquerysubmitted = function (args) {
        nav.navigate("/pages/search/searchResults.html", args);
    };

On the flip side, what if  your application isn’t running? This is where we hook into application lifecycle of our app.  What we want to do is wire up to our activated event and act when a user is activating us from the search contract.

    WinJS.Application.addEventListener("activated", function (args) {
        if (args.detail.kind === appModel.Activation.ActivationKind.search) {
            args.setPromise(ui.processAll().then(function () {
                if (!nav.location) {
                    nav.history.current = {
                        location: Application.navigator.home,
                        initialState: {}
                    };
                }

                return nav.navigate(
                        "/pages/search/searchResults.html",
                        { queryText: args.detail.queryText } );
            }));
        }
    });

Once there it’s just like before. Grab the args and pass them along to our searchResults.html page. To test this event in the debugger, we can simply run the debugger like we normally would. Browse to another application or something like the desktop and activate search. After typing your search term in and selecting your app to search, you will see that event fire.

Show me the goods

At this point, we effectively finished and all wired up to the search contract. The remainder is just how you decide to filter the data and display it. The template choses to use the ListView control from WinJS and mark off the items where you search term matches.

Hindsight is 20/20

Honestly I stumbled a few times writing this post, making thing honestly harder than they really needed to be. The template assumes you use the built the navigation framework (navigation.js) included with the Grid and Navigation Visual Studio templates. If you’re using something like the Blank template then the call to WinJS.Navigation.navigate just quietly completes and navigation never actually navigates. { scratches head here “}

Remember it’s a template, not gold code.

Pull out those event handlers from the template. Your default.html page should already be wired into the process activation, you should at least put the search activation handler there. Sure you could wire another function to that event, but why? It just a code smell and leads to maintainability issues down the road. I can see arguments for both sides of the story, but remember it’s just a template. Make it your own.

Summary

Today, we took took a very quick look into adding Search into your application. The Search contract provides a new way for your app to expose your application to it’s users. Now, you just need to determine what exactly you want to expose. Getting yourself in front of your users ensures people are engage in your application. The more ways they use it, the better life is.

You can download the entire sample solution here here:

Tomorrow, we’re going to the next step in our contracts exploration, Sharing.

See you then!

Today we are kicking off a series of posts focused on contracts starting with application settings. The chances are pretty high that your app has them, and you know you hate them. For me, they have always been that thing we’ve just dealt with, without really a great way handle them, until now. Application settings are just one part of something bigger in Windows 8 called contracts.  Let’s start our conversation on settings with a Microsoft definition of contracts:

Contracts A contract is like an agreement between one or more apps. Contracts define the requirements that apps must meet to participate in these unique Windows interactions.

For example, Windows lets users share content from one app to another. The app that shares content out supports a source contract by meeting specific requirements, while the app that receives the shared content supports a target contract by meeting a different set of requirements. Neither app needs to know anything about the other. Every app that participates in the sharing contract can be confident that the sharing workflow is completely supported, end-to-end, by Windows.

via: http://msdn.microsoft.com/en-us/library/windows/apps/hh464906.aspx

Interesting, this really really sounds like a “managed interface” between an application and the Windows Operating System. There are 5 contracts available to our applications:

• File Picker
• Play To
• Search
• Settings
• Share

Just like a typical programming interface, this means he\it who extends it is bolting on some type of functionality without the other actually knowing about it.

With Windows 8, this all actually feels like it happens at the user experience level. What do I mean? Well, let’s take the share contract as an example.  Simply put, applications tell the operating system what they would like to sign up for. In the case of sharing, maybe it’s accepting an image or sharing an image. Windows then will broker the rest.

Imagine a scenario where you find a great article while browsing the web in something like Internet Explorer. You want to share it to someone either in email or Twitter. Assuming you had an application installed that does email or Twitter, and they accepted sharing of an a URI, then Internet Explore could share to those. Better yet, those applications don’t even have to be running to do so. Windows takes care of making all that awesomesauce happen.

Sounds like an typical programming interface doesn’t it.

Defining Settings

The Settings Contract is really just one control, aka the Setting Flyout or WinJS.UI.SettingsFlyout which you will find in the WinJS library. Any application installed from the Microsoft Store will always have two default entry in the Settings Contract; Rate and Review, and Permissions. These are provided by the overall system and not something you will find in the template.

To activate our application settings we need to bring up the Charms menu and selected settings. You can do this a variety of ways, swipe in from the side ( left or right depending on your language ), Windows Key + C, or top \ bottom right hand side of the screen. Once activated select Settings at which point the settings flyout will be appear to float out from the side of the screen. Below is the settings flyout for the Microsoft Store and you can see there are multiple entry points for the store.

The first place to start with creating our own application settings is to tell Windows what in fact our entry points are going to be. We do that when our app starts up for the first time in an event called onsettings.  Below I am going to register two different entry points, “about” and “help”.

WinJS.Application.onsettings = function (e) {

    e.detail.applicationcommands = {
        "about": {
            href: "/pages/settings/aboutflyout.html",
            title: "About"
        },
        "help": {
            href: "/pages/settings/helpFlyout.html",
            title: "Help"
        }
    }

    WinJS.UI.SettingsFlyout.populateSettings(e);
};

An application can currently have 7 entry points, which will be alphabetically sorted by the property name you’ve created in the object. In our case, “about” and “help”, not the title.

With just our entry points created you can actually run your application and see these listed in the Settings Charm. Of course clicking them, will lead you to an error of resource not found. Let’s add our html pages that match the href’s we’ve already defined.

The Setting(s) UI

With our html pages added, now we have to actually create our user interface. Before you start creating those angle brackets, check out the Windows application settings guidance.

I mentioned earlier that our settings was really just a control called the Settings Flyout. To create our most basic settings page we just need a valid page, an element with an id id=”[name here]“ as well as the settings flyout data-win-control=”WinJS.UI.SettingsFlyout” as seen below.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
</head>
<body>
    <div 
        id="help" 
        data-win-control="WinJS.UI.SettingsFlyout">

        <span style="color: black;">Hi.</span>
    </div>  
</body>
</html>

With this in place we can now navigate to that entry point and see Hi in the top left hand side. Useful but useless. Clearly our next step is to add some meat and potatoes to our page.  Below we’re going to:

• Set the controls width to narrow. Two choices, narrow or wide.
• Add a header including a back button to get the user back to the Settings Flyout.
• Add some content.
• And lastly add some CSS to pretty up a few things.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>help</title>
    <link href="/pages/settings/settings.css" rel="stylesheet" />
</head>
<body>
    <div 
        id="help" 
        class="win-ui-light win-header appSettings"  
        data-win-control="WinJS.UI.SettingsFlyout"  
        data-win-options="{width:'narrow'}">

        <div class="SettingsPane">       
            <div class="win-label">
                <button onclick="WinJS.UI.SettingsFlyout.show()" class="win-backbutton">
                </button>
                <span class="SettingsTitle">Help Day #5</span>
            </div>

            <article class="SettingsContent">
                <div>Hi</div>
            </article>
        </div>

    </div>
</body>
</html>

That looks a bit more like what a user might expect.

Getting Data

Now settings are all about “setting” something right. That of course means the user is going to do something in that settings page, maybe enter some account information, flip some switches or just personalize a theme. With our modern interface things like unnecessary buttons we need to get rid of, yet we still need to get at that data right. Thankfully there are a number of events which fire around the Settings Flyout, specifically:

• onafterhide – Raised immediately after the SettingsFlyoutis completely hidden.
• onaftershow – Raised immediately after a SettingsFlyoutis fully shown.
• onbeforehide – Raised just before hiding a SettingsFlyout.
• onbeforeshow – Raised just before showing a SettingsFlyout

To walk the pipes a bit. Let’s add a simple input box to our settings UI.

....

<input id="bacon" type="text" value="Bacon is Yummy" />

....

Since we’re not going to add a button to our UI to “submit” the data somewhere, we need to hand the event afterhide. Here we’re going to attach to that event wiring up our afterSettingHide function.

....

    ready: function (element, options) {
        document.getElementById("about").addEventListener(
            "afterhide", afterSettingsHide, false);
    },
    unload: function () {
        document.getElementById("about").removeEventListener(
            "afterhide", afterSettingsHide);
    }

....

For brevity sake, the afterSettingsHide function will just dump the input box’s value to the console.

function afterSettingsHide() {
    console.log(document.getElementById("bacon").value);
};

Almost Finished

Having a consistent setting user experience is awesome but there is really one last thing you should do for your users, roam their settings. I know this is going to sound crazy, but there are users out there who have multiple machines. We may not want them to configure your app for every machine they use it on. I know as a user, I sure hate it. We will talk more about storage in another post to come.

Summary

When I was first introduced to Windows 8 I kept hearing the phrase, “Win as 1”. Win as 1 is one of the core tenants for  Windows. At first this just sounds like standard  marketing speak but actually it’s really far from that. Having now worked with Windows 8 for some time, the contract are a great proof point of this tenant. Things like application settings are now a centralized for the user, our applications can now spend more time focusing on delivering their core features rather than dealing with things like settings. Furthermore, now that the settings are consistent across all applications, we only ever have to teach a user once to use settings across all applications.

“I only had to be taught how to open a door once and then I could open all doors.” – I made that up.

Today, we took a look the Settings Contract, which is just one of many contracts you will find in Windows 8. Just like a programming interface, contracts in Windows 8 offer your app a unique way to extend your application beyond the traditional definition of an “application process” while providing a consistent user interface to our users.

You can download the entire sample solution and tools below.

Tomorrow, we’re going to look at the Search contract.  Search is something We’ll dive head first into that tomorrow.

See you then!

When Jeff and I put together the list of topics for this series, today got picked as “controls”. Now for those XAML lovers out there, this is something that makes complete sense but if you’re a web guy like me the word controls isn’t really a native word in our tribe. We talk in terms of elements in the DOM and now with html5, semantic elements.

Before we start exploring some of these so called controls, I really should back up and explore just how HTML5 fits into this new landscape. The last couple of days we’ve dipped out toe into things but we really haven’t talked HTML5.

By now I am assuming you at least know, that now with Windows 8 you can write a “native” app for the Windows Store. I put native in quotes only because it’s not running against the bare metal like C++ might. Our HTML5 apps actually run on the same JavaScript and rendering engines that IE10 does.

HTML5 FTW

HTML5 is kind of a big deal today in the web space. HTML5 isn’t by itself one thing it’s really a reference something that amounts to more than 100 specs. Amongst all this are, things like:

• New elements such as the new semantic tags; section, article, header and footer
• New attribute schemes like data-
• Awesome new features in CSS3 like media queries.
• Strict Mode in ES5

Now I am just naming a few awesome features in what is really a huge toolbox of awesome. Windows 8 and furthermore the JavaScript and rendering engines for IE 10 have added an enormous support for features that make up what we call HTML5. A great proof point of this, was seen in yesterday’s article with media queries. It’s the foundation for how we deal with our screen options in Windows 8.

As web developers, this is honestly very exciting. This means the skills you\me\we have built over the years are now applicable on a whole new platform. There is even opportunities to share your code between the different implementations.

Short story.  HTML5 rocks, it’s now “native” to Windows 8 and we web developer can continue to rule the world. Make sure to tell your friends.

- sidebar -

It’s important to not that some HTML and DOM API’s behavior different than when they are in the browser. You can find a detailed list of those difference here. HTML is an evolving specification and different parts are getting approved at different points in times. This means our browsers are moving as well. To effectively write cross browser\platform code we need to understand this notion of  feature detection. If your unfamiliar with feature detection I would highly suggest reading the following two articles:

• No Browser Left Behind: An HTML5 Adoption Strategy
• Same Markup: Writing Cross-Browser Code

Introducing WinRT and WinJS

Now we all know that Windows is clearly much more than just a browser. With the release of Windows 8 a new framework was also released called WinRT. In short WinRT is a number of APIs who provide access to all of the core features of the platform. These API’s are things like devices sensors and pickers. These API’s are exposed to C++, .NET and JavaScript. There is one set of API’s across all and through something called the projection, they are exposed in a way that feels native to the language being used.

Next up, something called WinJS. Let’s start with stealing a definition straight from Microsoft:

The Windows Library for JavaScript is a library of CSS and JavaScript files. It contains JavaScript objects, organized into namespaces, designed to make developing Windows Store app using JavaScript easier. Windows Library for JavaScript includes objects that help you handle activation, access storage, and define your own classes and namespaces. It also includes a set of controls. http://msdn.microsoft.com/en-us/library/windows/apps/hh465493.aspx

When I got started with Windows 8, I struggled with why I even needed it. After all we have build some pretty amazing Websites for years with out some new library. In fact at first glance you might think of this as some jQuery replacement but really it’s not that at all. In fact, you can freely use jQuery, jQuery UI, or my favorite Knockout.JS ( that’s for you Ryan N. ).

What WinJS is, is important. In fact, really important. Us web developers have been exposed to a new world with is mobile development. I am not talking trying to create a responsive page that adapts to a smaller screen size but an actual native app running on a mobile device. **Warning** it’s different, yet scary familiar. There are things we need to account for in our apps, like the overall application lifecycle. Sure we have done this some with a web application but here we need to be mindful of how our apps get started, when they get killed and like you saw yesterday things like namespaces. WinJS is here for us.

WinJS also provides a set of UI “controls” and and style sheets that give us a consistent Metro Windows Store App theme. So you might be thinking, is Microsoft introducing some new elements into the DOM and playing games with the rendering engine. NO. I started this article by talking about the importance HTML5 has in our web and Windows world they implement these controls by taking advantage of an HTML5 feature typically referred to as data-. More on that later.

Setup and Style

Every project HTML5\JavaScript Visual Studio template starts out already setup to use WinJS. This includes a “reference” to a version of WinJS, in our case 1.0. Create a blank app and take a look in your Solution Explorer.

After creating your blank app, open Default.html. You will see right at the top, we (really) reference the WinJS libraries.

<link href="//Microsoft.WinJS.1.0/css/ui-dark.css" rel="stylesheet" />
<script src="//Microsoft.WinJS.1.0/js/base.js"></script>
<script src="//Microsoft.WinJS.1.0/js/ui.js"></script>

By hitting run you should see a dark blank app. If dark isn’t your deal then switch to light.

<link href="//Microsoft.WinJS.1.0/css/ui-light.css" rel="stylesheet" />

Take note of the // in the reference.  This is a special syntax we use to reference built in libraries which are part of the core system and not in fact in our project structure.

Layout

Before getting into a couple of controls, let’s talk about layout. We have a number of different CSS layouts such as multi-column, flexbox, and grid. We could even use some open source frameworks like Twitter’s Bootstrap ( although I haven’t tried that yet on Windows 8 ). Recently a new spec was added to HTML5 called CSS Grid. You can think of the CSS Grid as the ultimate table layout that we have been waiting for for years. In fact if you have done any XAML and worked with the Grid Control, this will feel similar.

The notion is simple, you define a series of columns and rows, both relative and\or fixed. Then you reference those rows accordingly. Let’s create the *very* simple grid that you should have seen by now in my sample projects. In this case we’re going to create a simple one column, 3 row layout. I want all rows\columns to be equally spaced. We define them using grid-columns and supplying either our fixed or relative sizes.

body {
    width: 100%;
    height: 100%;

    display: -ms-grid;
    -ms-grid-columns: 1fr;
    -ms-grid-rows: 1fr 1fr 1fr;
}

This will produce the following grid layout.

With out grid defined, we can easily use CSS to select our elements and position them accordingly. Rows and Columns are 1 based so if we wanted to put our element of ID content in the middle, then we would select column 1 and row 2 as seen below.

#content {
    -ms-grid-column: 1;
    -ms-grid-row: 2;

    text-align: center;
}

While the CSS Grid isn’t THE answer to your all of your layout needs, it’s very powerful and easy to use. You can easily nest grids in grids and create some pretty complex yet awesome layout structures.

The IE team released released something called Hands On CSS3, which is a series of pages allowing you to easily mess around with the different CSS3 Specs like the Grid. They are a great way to play around live without messing up your own site or app.

Our First Control

So far, I have tried to laid out how this all fits together for the web developer. Getting your head around some of this foundational stuff will take a bit, but it’s time well spent. Earlier we very briefly introduced WinJS and what it offers. one of those things are these user interface controls. We can use these controls by adding the appropriate data- attribute. As you see below we’re going to use the attribute data-win-control and then set it to the the control we want to use. For simplicity sake lets add the rating control.

Our end result is adding a rating control under some header that we centered in the screen.

<div id="content">
        <h1>Day #6 - Search Contract</h1>
        <br /><br />
        <div id="ratings" data-win-control="WinJS.UI.Rating"></div>
    </div>

Controls can can also have options. These options are just another data- attribute, data-win-options to be exact. Below I am going to change the default star count of the rating control from 5 to 7.

<div id="ratings" 
    data-win-control="WinJS.UI.Rating"
    data-win-options="{maxRating: 7}">
</div>

Now that we have created and configured a control, we of will want to interact with it. This is nothing different that any other control we’ve worked with in HTML. In short we will select the control and then attach our event handlers.

Having said that data-win-controls are slightly different. Remember they are just an attribute on an empty div. So in fact they are really “nothing” until we make them something. To make them something we need to call WinJS.UI.processAll(). processAll will inspect the DOM and start to populate it with the correct controls. If you tried to bind an event handler before processAll was called you would end up with null reference.

args.setPromise(WinJS.UI.processAll()
    .done(function () {
        var ratingControl = document.querySelector("#ratings").winControl;
        ratingControl.addEventListener("change", changeRating);
    })
);

The solution is easy, we just bind our event handlers after processAll is called. As you would expect our function will fire, we can get access to the control and what the user selected.

function changeRating(ev) {
        var ratingControl = ev.target.winControl;
        if (ratingControl) {

            if (ratingControl.userRating != 0) {

                var userRated = ratingControl.userRating

            } else {

            }
        }
    }

Control.Next

That’s basically it. All of the controls basically work the same but just do something different. Rather than walk through all of the controls, I thought I would list out a few that I seem to use in almost all of my apps.

• App Bar – you would use this for your contextual menu’s at the bottom and top of the app.
• Semantic Zoom – an object allowing you to view data at different semantic levels
• Flyout – a message that requires a visual interaction
• Grid View – grid layout
• Html Control – display content from a web page
• List View – display a list of data
• Page Control – custom control
• Progress Bar\Ring – progress bar
• Setting Flyout – the control used for displaying your apps setting

AppBar Icon Awesome

When you start look into the App Bar control you will notice that you need icon’s for your App Bar. Well you don’t really “need” any artwork for the icons because they are included in Windows. Here’s a HUGE image that shows all of the icons and their names available by default:

You can see below, that I have created a button which is defined in our app bar. The icon property for the data-win-options is set to the name of the icon you will find in the image above.

<button 
	id="openAgenda" 
	data-win-control="WinJS.UI.AppBarCommand"     
	data-win-options="{
		label: 'Open', 
		icon: 'openfile', 
		tooltip: 'Open Existing Agenda.',
		section:'selection'}">
</button>

Summary

Creating a great user interface is hard. Not technically hard, but designing something that users want to use, and continue to use. We web developers our industry is just exploding. From the awesome open source projects like Knockout.js to the built in framework WinJS. It’s here now.

There are a lot of controls in WinJS. Today, I had one goal, hopefully help you understand the foundation on how all of these pieces fit together.

The code and tools you can find below.

Tomorrow, we’re going to get started on a series of articles related to contracts, and Day #5 will focus specifically on Settings within your app.  See you then!

Today, we are going to talk about a small, but very important part of the application lifecycle: the splash screen.  Some of you will see this as a silly topic at first, but it’s actually incredibly important from a user experience standpoint, and it’s the first thing they see.

Let’s say, as an example, that your application connects to the internet to collect some data.  Maybe you’re a weather app.  Every time the user starts your app, they’re going to want up-to-the-second data.  You know that this will generally take 2-3 seconds to grab the data, the appropriate images, and assemble them on your app’s page.

What we see happen in many apps is that the app loads empty, almost to a broken-looking page, only to get populated 2-3 seconds later.  By utilizing the splash screen and its events, we can “extend” the splash screen experience, so that our users don’t see our application until we’re ready for that to happen.  A couple of extra seconds looking at a splash screen is always preferable to opening a broken-looking app or one that is just hung.

So, what we will be doing in this article is determining where the original splash screen image was positioned, and replacing it with our “placeholder” splash screen image until our application is appropriately populated.

Getting Started

If you recall from our article on Day #1, the splash screen image is always 620 x 300 pixels.  For this example, we’re going to provide you with two versions of this image.  The first is the original red one:

Additionally, we’ve created an identical version of the image in a but with red and black so that we can see the difference when they are swapped, while still being able to notice if the positioning of the text shifts at all.

Add these two images to your “Assets” folder in a new “blank” project.  If you run that project after replacing the images, you should see the red image for a second or two before your applications loads to our default.html page.

Now you should have noticed your image was presented on that dark grey background color yet our image was 620×300. There is an easy fix, that’s right,,,,,,, the appxmanifest file. Down at the bottom, right under where we set the image to be displayed we can also set the background color. Set it to #ff0000 and rerun.  As you can guess our splash screen logo should be painted over a sea of red. Clearly we’re in need of a good designer.

It’s also worthy to note, we might really want to use a transparent png here rather than one with a background. We didn’t here, just to help illustrate what is all going on.

Extending our Splash Screen

I guess we should start by asking ourselves, why do we even need to extend the splash screen in the first place? Why not just put that call to the ESPN API and let the startup take longer? Simple, you won’t pass the store certification. Section 3.8 states, that your app must launch in less than 5 seconds. We can get around this policy by “extending the splash screen”, essentially fooling our users to think they are actually on the splash page when if fact they are on our landing page. Sneaky us.

We do this by basically showing and hiding a div on our default page. No really, that’s all. Let’s create a blank project to get started. The first thing we need to do is create that div. The only purpose for this element is to build up and control the resemblance of a splash screen but on our default page. Below I am creating that div, giving it an id and class that we can control later.

<div id="extendedSplashScreen" class="extendedSplashScreen hidden">
    <img id="extendedSplashImage" src="/images/splashscreenALT.png" />
</div>

You can see that our div has a reference to our second splash screen image in our case the red and black one.

The JavaScript

Clearly we need some JavaScript to make this all happen. Essentially what we want to do is:

• Hook into our app’s activation
• Grab the splash screen object, so we can to things like the location of it on the screen.
• Show our image
• Hook into a few events

We want to tie into our applications launch and even the blank template has our PLM or process lifecycle management code shelled out.  During launch, we’re going to grab the splash screen object off the args passed in args.detail.splashscreen. Once we have that, then we can grab it’s screen coordinates for later. Why? Well we need those coordinates so we can position our image exactly in the place as the old one. Once we have that we show the show the div, more on that in a second.

var _splash,
    _coordinates = { x: 0, y: 0, width: 0, height: 0 };

app.onactivated = function (args) {

    if (args.detail.kind === activation.ActivationKind.launch) {

        _splash = args.detail.splashScreen;
        _coordinates = _splash.imageLocation;
        ExtendedSplash.show(_splash);

        window.addEventListener("resize", onResize, false);
        _splash.addEventListener("dismissed", onSplashScreenDismissed, false);

        args.setPromise(WinJS.UI.processAll());
    }
};

We also want to hook into at two different events, resize and dismissed. Resize addresses the scenario where the user of our application might actually snap the application during launch. If they do, we need to be aware of that, and grab the splash screens new coordinates. Secondly we might want to hook into the dismissed event as a way to either interact with the screen a bit more and/or well end our splash screen..

- sidebar – Namespaces

Something I haven’t covered yet is namespacing our objects in JavaScript. The JavaScript that we write for our apps is ECMA Script 5 compliment. We’re also forced to use strict mode, aka pragma ‘use strict’. This is a good thing. strict mode helps us keep the rails on our JavaScript while setting us up for EcmaScript 6. Because of this we need to namespace our function such that we can call them from other JavaScript objects while not polluting the global namespace.

To do this we can use WinJS. Below you will see I am exposing a public name to it’s private function. In the code above, this is where ExtendedSplash came from.

(function () {
    "use strict";

    WinJS.Namespace.define("ExtendedSplash", {
        show: show,
        [publicFunction]: [privateName],
        [publicFunction]: [privateName]
    });
})();

Get very used to typing that code above. You will be doing it a lot. Snippets FTW!!!

Show Me

The ExtendedSplash splash object in which we referenced earlier is just a little helper object I created to use across my different projects. During activation we called it’s show function and passed along the splash screen object.

As I mentioned earlier, we have to overlay our image over the splash screens image and we do this through some JavaScript manipulating the DOM’s elements and their associated CSS. Simply put:

• Get the element of our “extended splash screen”
• Using CSS add set that elements top, left, height and with to what the splash image was originally set.
• Remove our CSS class that was hiding the div in the first place

function show(splash) {
    var extendedSplashImage = document.querySelector("#extendedSplashImage");
    position(extendedSplashImage, splash);

    WinJS.Utilities.removeClass(extendedSplashScreen, "hidden");
}

function position(element, splash) {
    element.style.top = splash.imageLocation.y + "px";
    element.style.left = splash.imageLocation.x + "px";
    element.style.height = splash.imageLocation.height + "px";
    element.style.width = splash.imageLocation.width + "px";
}

Now that we can show, we of course have to add the ability to remove ( like our starting state ) and update when things are snapped for example. To remove, we’re just adding back our CSS class to hide.

function remove() {
    if (isVisible()) {

        var extendedSplashScreen = document.querySelector("#extendedSplashScreen")
        WinJS.Utilities.addClass(extendedSplashScreen, "hidden");
    }
}

function isVisible() {
    var extendedSplashScreen = document.querySelector("#extendedSplashScreen");
    return !(WinJS.Utilities.hasClass(extendedSplashScreen, "hidden"));
}

Update is really nothing more than calling show again.

Style It

I’m not going to walk through in detail the CSS but I do want to cover it at the high level. Nothing below should surprise you, we’re going to hide the div and absolute position things from JavaScript as you have already seen. Simple enough.

.extendedSplashScreen {
    background-color:#ff0000;
    height: 100%;
    width: 100%;

    position: absolute;
    top: 0px;
    left: 0px;
}

.extendedSplashScreen.hidden {
    display: none;
}

#extendedSplashImage {
    position: absolute;
}

Class Splash Dismissed

Our next step is to subscribe to the event handler for when the Splash Screen is dismissed.  This allows us to hide our extended splash div and “start” our app. Now we already registered for the dismissed event when your app was activated.  Inside of dismissed we could just call our remove method and carry on our way.

function onSplashScreenDismissed() {

    ExtendedSplash.remove();

}

But what fun is that? We should really show some awesome ad like this. Feel free to use it in your blog posts of course. Royalty free even!

To do so, we’re just going to extend our original div just a bit to include that awesome image and let’s add a button below it to continue on.

<div id="extendedSplashDescription">
    <span id="extendedSplashText">
        <img src="images/31Days.png" /></span>
    <br /> <br />
    <button class="action" id="learnMore">continue</button>
</div>

Next we will update our OnScreenDismissed function to account for the new “continue” button.

function onSplashScreenDismissed() {

    document.querySelector("#learnMore").addEventListener(
        "click", ExtendedSplash.remove, false);

}

And like that, we have no created one of the worst looking extended splash screens. Why show this? It’s your canvas, it’s your features and customers. The hooks are there for you to be creative but use your creativity wisely. Forcing a user to click continue just to use your app is terrible. Telling your user your fetching a feed, might be welcoming.

Summary

In short, the splash screen can be your friend and a very powerful tool.  It becomes a temporary veil to hide some of your applications startup work until it’s ready.  It’s a highly valuable piece of app real estate, and we definitely think it’s something you should consider taking advantage of in every application.

Tomorrow, we’re were diving into WinJS and some of the UX controls that it has to offer us. But that’s tomorrow. To download the entire sample solution from this article, you can download it from below.

Today we are going to talk about screen sizes, and why they are important to Windows 8 development.  In the first part of this article, we will discuss orientation, and some simple ways we can make our application more useful based on the way our user holds their device.  In the second part, we’re going to look at our application in a “snapped” state, and how we might change our interface to accommodate a much smaller screen size.

Orientation and snap are important because if you don’t consider them in your app, your app won’t be approved for the Windows Store.

If you look in the Windows 8 app certification requirements, in section 3.6, it reads:

Your app must support a snapped layout. In landscape orientation, your app’s functions must be fully accessible when the app’s display size is 1024 x 768. Your app must remain functional when the customer snaps and unsnaps the app.

What this says is that our application already needs to support three visual states, at a minimum:

• 1024 x 768(minimum screen resolution & filled state)
• 320 x 768(snapped)
• Your default resolution that you are planning for, generally 1366 x 768.

Here’s an example of a full screen application moving to a snapped state:

You can see that in this case, we have re-arranged our content to better suit the smaller snapped state.  There is also the opportunity to move your application to a “filled” state, which is represented by the light gray block to the right of our snapped view.

Thankfully, there are some simple ways to recognize which state our application is in, and the rest of this article will be dedicated to showing exactly how this is done.

Running and Debugging

Before getting started with supporting rotation and snapping lets talk about how we run and debug our apps. Now, if you’re anything like me, you like writing your code on a beefy quad-core desktop machine, maybe 8-12 GB of RAM, dual 27” monitors, mouse, keyboard, the whole 9 yards.  Unfortunately, these machines are unlikely to have things like an orientation sensor, and picking up your monitor to change the orientation just isn’t going to work.  Thankfully there are three different ways to run your app; your local machine, a simulator ( included ) or a remote machine ( not included ).

The local machine option is most likely something you have already tried. Hit run, your application is built, deployed to your machine, and then the Visual Studio Debugger attaches itself and your off to the races. As we said before that option might have some limitations based on what type of hardware your developing on.

The simulator. It’s exactly that, a simulator, not an emulator like Windows Phone.  This means that it will only simulate the machine you’re currently working on, not act as a completely different, fully capable device.  No orientation sensor?  You need another device. So why is it important? Well, as a developer you can do things like fake a touch input, rotate the device and play with different screen resolutions.

And my most favorite option, the remote machine. Thankfully, Microsoft has provided a way for us to make this happen on a remote secondary device, much like we do when building Windows Phone applications.  Here’s the short story on how it works (MSDN has the longer, more thorough story): You will need install the Remote Debugging Tools on the secondary device.  We’re  using a Samsung Series 7 Slate, but any Windows 8 device in a tablet form factor should suffice.  You can download the Remote Debugging Tools here.  Make sure you choose the appropriate flavor, x86, x64, or ARM, depending on your device.  To enable Remote Debugging you will have to run the Remote Debugging Tools on the secondary device.  You’ll see an icon that looks like this:

Once the Remote Debugger is running on your secondary device, go back to your primary machine and select “Remote Machine” as your target for deployment. When you choose “Remote Machine” for the first time, you will be presented with a dialog box that looks like the image below.  Remember, devices on your subnet will only appear if the Remote Debugger Tools have been installed and are currently running.

Later, when you want to switch devices, you’re going to struggle to find where this option is stored.  I’m here, my dear readers, to save you that hassle.    Open up your project properties (Alt + Enter), and choose the Debug tab.  From there, you can change or remove your previous choice.  If you remove the choice, the next time you choose remote debugging, you’ll get the dialog box from earlier.

I know what your thinking. There is no way this magic remote debugger will ever work between a domain joined machine and just a tablet you have laying around for testing. Well as it turns out, it works just fine, you will be promoted for your Microsoft Account credentials you have associated with that tablet.

Supporting Rotation

To get started let’s create our almost famous app from the blank template in Visual Studio 2012. Once created hit run in either the simulator or on a remote machine ( assume for the rest of this article, assume I am running on a remote machine ). You will see your awesome blank app and if you rotate it, the app will in fact automatically rotate as well. Why, How?

By default, all templates in Visual Studio are setup to support all rotations. Remember that package.appxmanifest file? In the Application UI tab you will find a section called Supported Rotations. By checking one or more orientation preference you are selecting which orientations your app will support. Again by default we support all.

Depending on your use case, this may be something of value to your apps overall experience. For example, if you’re building a game you might only want to support landscape mode.

Display Orientation

Programmatically we can ask Windows what our current orientation is and even be notified about when it changes. We can do this through an API called Windows.Graphics.Display.DisplayProperties. Below I have have created a very simple function which switches currentOrientation updating an element in the DOM.

function updateDisplayOrientation() {

    switch (Windows.Graphics.Display.DisplayProperties.currentOrientation) {

        case Windows.Graphics.Display.DisplayOrientations.landscape:
            results.innerText = "Landscape";
            break;

        case Windows.Graphics.Display.DisplayOrientations.portrait:
            results.innerText = "Portrait";
            break;

        case Windows.Graphics.Display.DisplayOrientations.landscapeFlipped:
            results.innerText = "Landscape (flipped)";
            break;

        case Windows.Graphics.Display.DisplayOrientations.portraitFlipped:
            results.innerText = "Portrait (flipped)";
            break;

        default:
            results.innerText = "Unknown";
            break;
    }
}

While my updateDisplayOrientation function is pretty much a foolish example it becomes a bit more useful if we we’re to actually hook it up to an event listener. Once our page is “ready” lets add an that eventListener on the “orientationchanged” calling our updateDisplayOrientation function.

....

results = document.getElementById("resultText");

var dispProp = Windows.Graphics.Display.DisplayProperties;
dispProp.addEventListener("orientationchanged", updateDisplayOrientation, false);

updateDisplayOrientation(); // call to set the inital state

....

Now when we rotate the device, our application should be updating an element on the screen with the state of our orientation.

Orientation Sensor

Working with the currentOrientation is pretty simple but also limiting to some regards. Devices these days have a multitude of supported sensors. This is also true for orientation and the Windows 8 SDK has provided us with the SimpleOrientationSensor found at Windows.Devices.Sensors.SimpleOrientationSensor. Unlike our our previous example, the SimpleOrientationSensor is an API over an actual hardware sensor so depending on your hardware the following may or may not work.

So, why another way? Great question and one I honestly scratched my head for a bit on this. I have come to my own conclusions it’s to support the broadest set of hardware as well as fine grain control when you do have a sensor. Not every machine will have a physical sensor but the currentOrientation will always work.  Now I know what you’re thinking. Sure it does, one state, landscape. But that is actually not true. Depending on your graphic card you can actually rotate your monitor and have a different view. For example you could flip a monitor and have it in portrait mode. In this case the currentOrientation would in fact tell you that.

Back to SimpleOrientationSensor. Much like before I have setup another switch statement to see what position the sensor is in.

....

switch (e.orientation) {
    case Windows.Devices.Sensors.SimpleOrientation.notRotated:
        results.innerText = "Not Rotated";
        break;

    case Windows.Devices.Sensors.SimpleOrientation.rotated90DegreesCounterclockwise:
        results.innerText = "Rotated 90";
        break;

    case Windows.Devices.Sensors.SimpleOrientation.rotated180DegreesCounterclockwise:
        results.innerText = "Rotated 180";
        break;

    case Windows.Devices.Sensors.SimpleOrientation.rotated270DegreesCounterclockwise:
        results.innerText = "Rotated 270";
        break;

    case Windows.Devices.Sensors.SimpleOrientation.faceup:
        results.innerText = "Face Up";
        break;

    case Windows.Devices.Sensors.SimpleOrientation.facedown:
        results.innerText = "Face Down";
        break;

    default:
        results.innerText = "Undefined orientation " + e.orientation;
        break;
}

....

And of course this is all find and dandy but much more useful if we can wire up to an event notifying us of a change. Like before we will wire up to the orientationchanged event but on our sensor this time. Of course you will want to check just to make sure you in fact have a sensor to even wire up to.

....

results = document.getElementById("resultText");

var sensor = Windows.Devices.Sensors.SimpleOrientationSensor.getDefault();
if ( sensor ) {
    sensor.addEventListener("orientationchanged", sensorOrientationChanged);
    results.innerText = "Sensor Found";
}
else {
    results.innerText = "No Sensor Found";
}

....

Snapping

At this point, we have an application that recognizes that device orientation has changed.  That’s all well and good for when we want to do something specific in code with orientation, but what if we just want to have our application re-orient itself to be readable/useable to our user?  The responsive web CSS3 have clearly impacted how we design our Windows Store Application layouts. Windows supports four layouts for our application to take advantage of; Landscape, Portrait, Filled and Snapped. We support each of these layouts with CSS3 Media Queries.

Landscape View. By default our application starts as landscape. This is maximum real-estate you have, it’s your canvas.

@media screen and (-ms-view-state: fullscreen-landscape)

Portrait View. Landscape on its side. What else?

@media screen and (-ms-view-state: fullscreen-portrait)

Snapped and Filled View. Here is where things start to get interesting and creative. In the simulator below on the left hand you see an app in the filled state and on the right you can see the application in the snapped state. Minimum screen resolution of 1366px x 768px required to support this.

@media screen and (-ms-view-state: snapped)

@media screen and (-ms-view-state: filled)

This means you can actually run two applications side by side. That also means you may want to reconsider your user experience especially in the snapped view.  Take a look at Microsoft’s Finance Application. When your in snapped view, you get your favorites rather than the entire experience.

As I mentioned earlier we do this all through a CSS3 Media Query. In all of our views above you can see we’re doing something simple like changing the background-color.

@media screen and (-ms-view-state: snapped) {
    body {
        -ms-grid-columns: 20px 1fr 20px;

        background-color: blue;
        font-size: large;
    }

    header[role=banner] {
        -ms-grid-columns: 20px 1fr;
    }
}

Summary

Today, we took a look at how we can determine the orientation of a user’s device, as well as how to use the new LayoutAwarePage item to manage the different visual states our app might encounter.  There are tons of great examples on the web related to orientation and snap, but if there is ONE lesson you take away from today’s article, it’s this:

Your application MUST acknowledge the snapped state.  Make sure you accommodate it.

Tomorrow, we’re going to look at the Splash Screen.  You’ve likely seen something like this before. It’s the first thing your users will experience so let’s make sure we get it right. See you then. You can get the entire solution and the tools below.

In the first article of this series, I thought it was important to cover the inner workings of a Windows Store Blank App template in Visual Studio 2012.  I will cover each of the files, why they are important, as well as many of the settings that may be hidden in each one.  This should give you a solid foundation for the rest of the series, where we will be using each of these files.

There are also several other project templates in Visual Studio 2012, specifically Grid, Split, Fixed and Navigation as you can see below. They were built with a specific type of application or navigation in mind, and it’s generally unlikely that your idea fits that architecture perfectly.  Remember these templates are starting points and not the end solution. For this series we will almost start with the Blank App template.

Here is a view of the Solution Explorer for a brand new Blank App template in a HTML5 solution.

The Images

Let’s start with the easy ones, the images in the images folder.  There are four images inside every new project, and they each serve a specific purpose.  We have created different versions of these images (as well as one additional), so that it’s very obvious which image is which when we run the application.  I highly recommend downloading these images and replacing the default ones, especially when you’re learning.  You can download all five of them here.  Once you have replaced the default images, run your project to see these images in each of their locations, as described below.

Logo.png

This is probably the most common image your application will use.  This is the default background image for your application’s tile on the user’s Start screen.  It is 150 x 150 pixels in size.

SmallLogo.png

This image is used when an application list is shown.  For example, when you search for an application in Windows 8, or in the Share menu.  The SmallLogo.png is 30 x 30 pixels.  At such a small size, you want to make sure this icon really represents something familiar to your user.  I highly recommend just a logo or some other obvious imagery.

SplashScreen.png

This  is the initial image that loads when your application is started.  There are some neat tricks you can do with this, and we will cover those later in this series.  For now, remember that this image will ALWAYS be 620 x 300 pixels, and will be vertically and horizontally centered on your user’s screen, regardless of size.

StoreLogo.png

To save space in the store, we have a smaller icon that is used.  This image is 50 x 50 pixels, but might be the most important 2500 pixels in your entire application.  This is the icon that users will see when they are deciding which new apps to add to their device.  A poor icon indicates a poor application to most users.  Spend some time on this one.

WideLogo.png

This is an additional icon that I include in my initial projects.  You will need to add it to your project by right-clicking on the Assets folder and choosing “Add Existing Item…”  This image is 310 x 150 pixels, and is used to allow your application to have a wider tile than the standard size of Logo.png.

package.appxmanifest

This file contains all of the configuration, settings, and declarations for your application.  It is where you will go for almost every single thing that is related to your app running on a Windows 8 machine.  For example, this is where you define that the search contract is enabled, or which icons to use in each situation. For example, each of those image assets we just walked through are defined in the Application UI Tab of the AppXManifest.  It also defines default background colors, orientations, and specific capabilities your app will require, like access to location.

Make sure you are intimately familiar with this file.  You’re going to need it.

default.html

This is our main entry point or starting page of your application. default.html could actually be named anything, as it’s set in our package.appxmanifest file as the application’s start page. As a web developer default.html should look like any other starting page for a website you’ve created especially if you’ve done any HTML5.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>Day1</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.1.0/css/ui-dark.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.1.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.1.0/js/ui.js"></script>

    <!-- Day1 references -->
    <link href="/css/default.css" rel="stylesheet" />
    <script src="/js/default.js"></script>
</head>
<body>
    <p>Content goes here</p>
</body>
</html>

Like any html page you’ve seen, you will find our references to style sheets and script files. But look closely at the href or src for a the link and script respectively. Take note of the // as the start of the path. This is how we reference the built in scripts and style sheets.

css/default.css

Since we started with the blank template, you should be able to guess that our default style is also non existent. Having said that there are a few clues as to what Microsoft wants us to do at the minimum, orientation and snapping. Tomorrow we will cover orientation and snapping in details but for not it’s enough to say it’s handled by some simple media queries.

body {
}

@media screen and (-ms-view-state: fullscreen-landscape) {
}

@media screen and (-ms-view-state: filled) {
}

@media screen and (-ms-view-state: snapped) {
}

@media screen and (-ms-view-state: fullscreen-portrait) {
}

Now default.css wasn’t the only style sheet our template referenced. We also referenced:

<link href="//Microsoft.WinJS.1.0/css/ui-dark.css" rel="stylesheet" />

This is a build in style sheet our applications can use to help us consistently style things like the built in controls. The template referenced the “dark” style by default but there is also a “light” style as seen here:

<link href="//Microsoft.WinJS.1.0/css/ui-light.css" rel="stylesheet" />

js/default.js

Unlike our default CSS, our default JavaScript file does do stuff specifically around process lifecycle management or PLM. Out of the box our template is setting up some shell behavior to handle some of the different PLM cycles like launching and terminated. These are things we will want to implement

(function () {
    "use strict";

    WinJS.Binding.optimizeBindingReferences = true;

    var app = WinJS.Application;
    var activation = Windows.ApplicationModel.Activation;

    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
            if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                // TODO: This application has been newly launched. Initialize your application here.
            } else {
                // TODO: This application has been reactivated from suspension.Restore application state here.
            }
            args.setPromise(WinJS.UI.processAll());
        }
    };

    app.oncheckpoint = function (args) {
    };

    app.start();
})();

Just like in our CSS, we have also referenced some built in libraries, specifically WinJS. We need WinJS to implement things like PLM. More on WinJS later.

   <script src="//Microsoft.WinJS.1.0/js/base.js"></script>
   <script src="//Microsoft.WinJS.1.0/js/ui.js"></script>

Day1_TemporaryKey.pfx

Every Windows Store app is signed by a certificate. When you first create a new project in Visual Studio it will create a new test certificate automatically. In our case this test certificate is called Day1_TemporaryKey.pfx where Day1 is our project name. Again you can find this set in the package.appxmanifest file under the Packaging tab. You can even create new certificates there, if needed.

Once your ready to submit to the store you will need to associate your application with the Microsoft Store and your Developer Account. You can do this by going to Projects, Store, Associate App with the Store… After doing so, you will notice a new certificate will be added to your project, which will be used to sign the final package.

You can find more information about signing an app package here.

Summary

So that’s it!  We’re only just getting started in this series, but you’ve now gotten a solid understanding of starting files found in a default Blank App template for HTML.

Tomorrow, we are going to focus on orientation and snapping, two important aspects of your application that often go overlooked.  If you haven’t already, download the free tools to build apps for Windows 8 from the link below. I have also included a link to the entire solution mentioned here today.

See you tomorrow!

Given the amount of content we will be producing we wrote a simple Website at http://www.31daysofwindows8.com. You can think of this as your index to everything related to the 31 Day of Windows 8. We will update it daily with the new articles as well as the supporting links for each topic. be updated daily with links to the published articles.

Of course if you prefer RSS dropped in your favorite reader here is both of our endpoints:

• Jeff: http://feeds.feedburner.com/Blankenthoughts
• Clark: http://feeds.feedburner.com/clarksell

We will be hanging out on Twitter using hashtag #31daysofwindows8 and you can follow us at @csell5 and @jeffblankenburg.

Now Jeff has been rocking the 31days of awesome sauce for a number of years now. I would encourage you to check out his previous series here:

~Enjoy

Well, they’re back! With the release of Visual Studio 2012 and Windows 8 they decided to get a bigger RV and do it again BUT this time we’re taking advantage of them. On 9/29 { next Saturday  } .NET Rocks and That Conference are throwing a special 1 day only free event ( lunch provided ). Attendees have a day to immerse themselves in Windows 8, Visual Studio, Azure and at the end watch a live recording of .NET Rocks. This is great opportunity for anyone interested in the Microsoft platform.

We only have 250 seats and it’s next Saturday. Please don’t wait around to register.

Details, agenda and registration can all be found at http://oneday.thatconference.com

Hope to see you there…

First and foremost, I am not an event organizer. It’s not at all a career goal of mine. Ironically, I have planned a few events in my time and it’s really isn’t much different than planning any software product. So why, take on something of this size?

One of the greatest things I get to do in my daily job is travel to the surrounding communities. Sure travel gets old, but it affords me the ability to get out of my own distortion field and experience other communities and cultures. Like it or not our industry is really small but regardless it’s very diverse with different cultures and communities everywhere.

I’ve been fortunate enough to have been involved in someway with CodeMash, from attending, speaking, to just bothering Jim and the other founding members for their guidance. For me, CodeMash ( and there are others too ) is one of the best examples of everything coming together in a perfect storm. So what is this “everything”? I think I can sum up everything in 6 statements:

• People. IMHO this is the most important and it set’s the overall tone of the event. I personally want to be surrounded by great people and not just some negative asshole who knows it all. I want to be inspired, meet new people, and learn from others along the way.
• Content. Content is clearly at the center of the conference but it’s really behind the people that deliver it. You come to see the content but come-on, with today’s internet you are clearly a couple of clicks away too. What you want is the perspective of the person who is talking about it and their experience.
• Community Driven. Hey we know what we want, why not just do it ourselves. Community events are the best place to see the broadest set of people and their experiences.  It also helps build new friendships, business relationships, and a has input into a larger ecosystem.
• Diversity. Like all the points above, what good is it if you can get a diverse look at things. From people, to content it all matters. Our industry suffers from “there is only one right answer and it’s not yours” way to much. At the end of the day we’re all developers ( or pick x ) in the same industry.  
• Fun. We all work hard, learning shouldn’t feel like work. It should just be all around fun.
• Friendly. If it’s not friendly then the rest of it was for nothing.

And yes, That Conference was inspired from CodeMash ( and others ) but we’re also not CodeMash and we will never be CodeMash. We do and will continue to work pretty closely with the CodeMash guys and all of the other conferences around who want to work with us. It’s not about copying one or competing with another, but coming together as a larger community and feeding into each other for a larger success. We can’t thank them enough ( CodeMash, StirTrek and a number of other conferences ) for all the help they have provided us.

Why?

I won’t lie, I was jealous of what the Heartland community created. The density ( # of people who come together ), friendships, passion, and more; I wanted it here too. I grew up hearing, you can either be part of the problem or part of the solution. So I choose the latter…

Now I am not saying there was or is a problem here in the Midwest, I just wanted something that seemed to be missing. We have a lot of awesome stuff going on but we need to come up for air for longer than a day and share with one another.

We set out to create a multi-day event, driven by the community, for the community for a price anyone could afford.

I also don’t think “the conference” is dead. The internet is great, virtual training is great, BUT nothing can actually replace meeting someone and talking to them face to face. I know we have Skype and Google hangout with 1080p webcams but that can’t replace actually talking to someone in real life and shaking hands. Having said that, it means things like That Conference are just as much about the content as they are the people who attend. One way you will see this is by us having longer times between sessions so people have the ability to actually talk to one another.

What?

So what really is That Conference? Well first and foremost it’s a community volunteer technology conference. No one is getting paid and to be totally transparent peoples houses are on the line to try and pull this off.. There are roughly 25 people working daily on That Conference to make it a success.

That Conference is a multi-day technology conference centered around software development. We have well over 100 sessions from speakers across the industry. We tried to center things around a few themes, Cloud, Mobile, Web and Other. We also tried to balance things across all technology sets but that’s was also dependent on who submitted sessions. We had over 400 sessions across roughly 200 speakers and I think we did a pretty solid job of picking our sessions this first year. This will continue to get better year over year and more diverse as communities come together.

That Conference is backed by a not for profit company we created to help facilitate efforts like these. The company “That Conference NFP” has aided efforts like, HTML5.tx, Chicago Code Camp, Give Camp, Hackathons etc. Like it or not, even a 15k event still needs things like a bank account, credit card, w9 and so on. It’s the ugly side of things you never want to think about but when it costs hundreds of thousands to pull off something like That Conference. I would also like to keep my house in the process.

Price

$349. You can’t imagine the number of people who rail on me about how expensive it is and shame on me as to why it’s not free.  Honestly that hurts, remember it’s all volunteer? Guess what, this year all of the volunteers have agreed to buy a ticket – including myself. We all want to see this succeed and in a big way.

Bottom line, it costs money. Our goal was to come up with a conference that was cheap enough you wouldn’t mind paying for yourself. Better yet, what if you could take your family along and create a vacation out of it too.

We couldn’t do this without our great sponsors. No doubt we’re a first year conference and the third year will be even more amazing than the first but you have to start somewhere. Our sponsors have not only invested in us but in you. Their sponsorship proves they feel this is just important to them as it is to the community who surrounds us. Because of that, THANK THEM. Flat out, just say thank you.

So what does $349 get you? Well every ticket is basically broken down into a number of costs:

• Food, Breakfast, Lunch, Happy Hour, Soda, Coffee, Etc – By far this is the biggest expense. For a 1k people this if roughly 300k. Rough numbers of course but it’s crazy expensive. Want to help us save on costs? Drink the entire soda, cause we’re paying for every ounce.
• Swag: Yes, you want something to remember your investment. As an example 1k shirts at $8 a piece is 8k.
• Operating Costs: this is, Wifi, Projectors, Mic’s, Power, and on and on.
• Conference Center: Well there are two parts to getting a conference center like the Kalahari. One you have some minimal costs just to have it. More importantly, you have to fill rooms in their venue. Double edge sword I guess, on one hand we’re not on the “hook” for the cash, but if we don’t rent out the rooms – well we’re on the hook.
• Lawyers: unfortunately you have to be protected no matter how good your intentions are. We now have a layer on retainer and have used them a number of times.
• Company Overhead: paper work, taxes and so on.
• Marketing. Twitter and Facebook aren’t enough. Hopefully over the years to come, this reduces as every attendee will be the voice of That Conference.

Of course there are other costs but this represents the biggest amount and food is clearly the winner. The more people who come, the more we can do.  We have structured the ticket price such that at 1k to 1500 geeks we can put on an amazing show and relieve a little of the pressure on the volunteers in the years to come.

The Speakers

Our speakers are all volunteer as well. Like sponsors, we could not do this without them, so please thank them. As a speaker we cover their ticket cost as a way to say thank you, and hopefully in the years to come, we’ll be able to do more.

A lot of our speakers live in your backyard. You might be amazed by the level of talent here.

The Schedule

I’m working on it. Right now you can see the initial cut of the schedule and it’s activities here: http://www.thatconference.com/schedule. The conference is more than just the sessions. From breakfast, to renting out the waterpark we’re planning for fun. GiveCamp, WaterPark, Code Retreat, Parties, Live Podcasts, Battle Decks etc.

One thing that we can’t represent on the schedule and we hope everyone will participate in, is our open spaces. Open spaces is a great way to spin up “sessions” that we’re never on the schedule in the first place.  We are dedicating a couple thousand square feet to have a great open spaces experience.

How can you help?

The best thing you can do for us, is spread the word. There are over 60k developers here in the Midwest and we haven’t even come close to telling everyone. We need your help. Tell your boss, you’re communities, peers, friends,  whatever. We can’t do this without help from the community at large. You may think the guy next to you knows about it, but chances are he or she doesn’t. There is just no magical way to reach everyone and say, “hey man have you heard..”.

Please Help us, help you. Make some noise about That Conference.

Thank you, and I can’t wait to see you there. I promise you, this is just getting started.

Tickets

Tickets will be on sale tomorrow at 8:13am CST for $349. We’re not doing any early birds, discounts, blaa, blaa, blaa. That $349 covers you for breakfast, lunch, swag and a few other things that we will announce later on. You will purchase tickets through EventBrite at http://thatconference2012.eventbrite.com/. There is also a link on our home page that will redirect later on tonight.

We expect to sell out rather fast so don’t delay. We have a waitlist setup, so if you don’t get in, you never know we might just open up more. Our goal is to include everyone assuming we have the staff to handle it.

Hotel

We have a block rate setup with the Kalahari. You can find more details about it at: http://thatconference.com/Resources/Travel The discount is a rolling discount so if you desire a different room that is ok, we have you covered. The block is first come first serve. The Kalahari is awesome you can see more about it at http://www.kalahariresorts.com/wi/.

Sessions and Speakers Counselors

All of our sessions have been posted to: http://thatconference.com/Sessions. If that wasn’t awesome enough we have a few more tricks up our sleeve. We also have our speakers bio’s here: http://thatconference.com/Speakers but we’re still setting up that tent in camp. Soon we will have some high res head shoots of our counselors.

The Schedule

Coming. Honestly we’ve been so busy getting things ramped up and settled for tomorrow we’re just not there. You will not be at a loss for things to do, just start to practice your cannon balls and laser tag skills.

The Pre-Parties

I am hoping you know by know we’re having a number of pre-events going on leading up to the actual conference and they are all free.

A Date with 8

Are you What’s Next? Have you been waiting to dig into Windows 8? Need a little help? Well that time is now. Why not take a little date with 8 and maybe even with a prize along the way? This Thursday and Friday we’re having a mini-hackathon leading into Chicago Code Camp.

More details and registration here: http://adatewith8.eventbrite.com

That Hack ( June and July )

In partnership with Hackatopia we are running a series of ‘American Idol’ style hackathons.  Win your city, head off to That Conference and convince the audience you have what it takes to win it all.

• Chicago – sold out – http://thatconferencehackchicago.eventbrite.com/
• Milwaukee -  http://thatconferencehackmke.eventbrite.com/
• Madison – coming…
• Minneapolis – http://thatconferencehackmsp.eventbrite.com/

Midwest Give Camp ( Aug 11th & 12th )

Want to use your awesome tech skills to help a little girl change the world? Check out the Give Camp we are putting on the Saturday and Sunday leading into That Conference. http://thatconference.com/givecamp

Stay in The Know

Join our newsletter, signup is right on the front page at http://thatConference.com.

Make some noise!

Help us spread the word. We have been using #thatConference as the hashtag on twitter but that isn’t the only way to get involved. We have a Google Group, Facebook and more are all listed here: http://thatconference.com/Resources/GettingInvolved

Sponsors and Partners

Please check out our partners and sponsors. We have been working over the past year to really do something different here in the Midwest. We couldn’t do it without the help of everyone.

Are you interested in sponsoring? We’re still looking for great partners, all of the details you can find here: http://thatconference.com/Sponsorship/

This begs the question – How can YOU get a token?

It’s easy! If your app is ready and you want to be among those developers who get to submit to the store early, simply attend one of the 100s of free Application Excellence Labs that DPE and Windows are holding around the world.

Follow these steps to get invited to an App Excellence lab:

1. Contact me csell@microsoft.com for instructions on how I can nominate your app for an excellence lab.

2. Create a really great Windows 8 Metro style app (or game) immediately. Get it as ready as if you were submitting to the store.

Hopefully, there will be a lab near you. Right now, we have labs in 40+ countries and we may be adding more.

Of course, coming to the lab is not all you have to do. I have to go back to step #1: You need to have a compelling, functional app that follows our UX guidelines, our performance best practices, and our store certification requirements

The lab is a 4-hour engagement with a trained Microsoft Services Engineer. This person will run your app through a series of tests based on a quality checklist to ensure your app is (or will be) in top-notch shape when you submit. You will also get a chance discuss ways to make your app even better and you will get answers to any questions you might have.

If your app meets the criteria, then booyah! You get a token to register your developer account and (once you have been verified and all that) you will be able to submit your app to the Windows store.  If your app does not meet the criteria, nothing is lost. You will still end up with a much better app and you will be able to submit it when registration opens for all developers.

Good luck. We are looking forward to seeing your apps and helping you to make them great!