PhoneGap on WP7 Tip #5: Live Tiles and Deep Linking

Windows Phone has a unique and very handy way of providing multiple entry points into your application. This is done through the use of one or more Live Tiles. The start screen on Windows Phone is comprised of tiles that represent many things – applications, people, websites, music, map locations, and more.

There’s a neat way to get a feel for this UI metaphor even if you don’t have a Windows Phone or the emulator installed. Point your iOS or Android device to https://m.microsoft.com/windowsphone/en-us/demo/ and you can see the tiles in action.

When you have an application on Windows Phone, one of the best compliments that a user can give your app is to pin it to their start screen. And the cooler your application tile, the more your users will like and use your application. With Windows Phone 7.5, you can now have multiple tiles representing multiple entry points for your application pinned to the user’s start screen. Check it out in this quick video of FourSquare on Windows Phone. FourSquare allows you to pin locations and people to the start screen for quick access.

A common example of using multiple Live Tiles is a weather application. The user’s start screen might have a tile for each location for which they want to access the weather quickly. Each tile represents a different location, and when the user launches the app from each tile, the application responds by going straight to the details page for that city. This is a huge timesaver for the user.

Not only can the tiles represent multiple entry points into your application, but each tile can surface a small amount of data to the end user from your application, with different images and text being shown on each tile. In the case of a weather app, each city’s tile could display the current conditions or forecast, maps, and more for that city. Live Tiles also have this cool flipping effect, so you can even put things on the back of each tile like secondary images or text. The tile will flip over randomly, making for a dynamic start screen that users really get a kick out of.

You can manage your application’s Live Tiles from within the app’s code. And since a PhoneGap application runs within a Silverlight application, you could write some C# or Visual Basic code to create, change, or remove the tiles. But there’s an even easier way. Check out the Live Tile plugin on Jesse MacFadyen’s plugin page. It provides a simple way to create and update tiles from within the JavaScript of a PhoneGap application.

Here is some code from the sample page that shows how to create a secondary tile:

 function createSecondaryTile() {
     console.log('Create secondary tile');
  
     var success = function (res) {
         console.log('secondary tile was created');
         document.getElementById('res').innerHTML = res;
     };
  
     var fail = function (e) {
         console.log("Error occurred: " + e);
         document.getElementById('res').innerHTML = "Error occurred: " + e;
     };
     navigator.plugins.liveTiles.createSecondaryTile(success, fail, 
      { title: document.getElementById('title').value, 
        image: 'Images/appbar.save.rest.png', 
        count: document.getElementById('count').value, 
        secondaryTileUri: secondaryTile, 
        backTitle: 'back' 
      });
 };

The key call in here is to navigator.plugins.liveTiles.createSecondaryTile. This code sets up the image, count and title to control how the tile appears, which are useful. But the key to making the secondary tile a deep link to someplace in your application is in the SecondaryTileUri parameter.

Normally that URI contains two things that a Windows Phone app cares about – the page to be navigated to (a XAML page in the project) and some parameter to be sent to the page, like the zip code of the city whose weather to display. These are formed just like a web based HTTP request. In Windows Phone app, the XAML part of the URI is automatically navigated to, and you can write code in C# or VB to retrieve the querystring parameters to get what you need.

Now, in our case what we want to do is go to the same XAML page each time (the one hosting the PhoneGap application) and navigate to a different HTML page within the PhoneGap file structure. So we just need to provide the proper URI to that HTML page as a querystring parameter at the end of the XAML page’s name in the URI we assign to that tile. Fortunately the plugin handles the XAML page part, and you just specify the HTML page to navigate to. In the code above the secondaryTile variable is set earlier in the code.

 var secondaryTile = 'www/liveTiles.html';

This is added to the end of the URI for the tile.

While the plugin is useful, it’s missing one key part. Specifically, it doesn’t contain a way for the PhoneGap application to navigate to the proper HTML page when it is activated from a tile that has a deep link URI. So you’re going to need to put a little code in the hosting XAML page, and actually tweak the secondaryTile variable in the sample to get it to work.

If you’ve created a project from the PhoneGap template, open MainPage.xaml.cs. Inside the constructor method (which starts off with public MainPage), type Loaded += then hit Tab twice. This will create a MainPage_Loaded event handler. Change that to be the following:

 void MainPage_Loaded(object sender, RoutedEventArgs e)
 {
     try
     {
         string pgUri = this.NavigationContext.QueryString["Uri"];
         PGView.Browser.Navigate(new Uri(pgUri, UriKind.RelativeOrAbsolute));
     }
     catch { };   
 }

This code will pull the HTML page off of the end of the URI and send the PhoneGap control’s browser off to that page. We wrap it in a try/catch in case there’s no URI or the Navigate fails.

The final thing to do is change the URI of the HTML page so it has the correct URI for the desired HTML page. Revisit the liveTilesExample.html page and change the secondaryTile variable to be this:

 var secondaryTile = 'app/www/liveTilesExample.html';

Now run the project, click on Live Tiles page, and create a secondary tile. That should bring you back to the start screen and show the secondary tile. If you tap on the tile, it should launch the app and navigate to the Live Tiles page instead of the main page. Press the Windows key at the bottom, swipe to the right and you’ll see the main icon for the application. Launching the app from there will go to the index.html page and not the live tile page. If you press and hold that icon, you can pin it to start, and now you’ll have the main tile for the app as well as the secondary tile.

One thing I’m finding a challenge is passing a parameter into the HTML page. So if your page was showWeather.html and you wanted to send in a zip code, I’m finding that you can’t simply append ?zipcode=90210 at the end of the HTML page – it won’t work, although you can still make it part of the tile’s URI. I’m working on a tip for handling that, so look for a future blog post about it.

I encourage you to explore all the things you can do with Live Tiles now that you have a way to use them easily from PhoneGap. Here’s a useful article on MSDN on what you can do with them. Have fun with Live Tiles!