A group of colleagues and I developed a Windows 8 reference application called “Contoso Food & Dining”. This application shows restaurant information and reviews around some location. Among other things, I owned the implementation of secondary tiles.
Secondary tiles enable users to promote specific content by pinning it to their Start Menu. Selecting the secondary tile through a touch or a click launches the parent app and deep-links to that pinned content. For example, a Weather app may allow me to pin a specific city’s weather page to the Start Menu as a secondary tiles. Then, when I click on that tile, it launches the Weather app and takes me straight to that city’s weather page.
Here are my top 3 tricks that helped me work with secondary tiles in a real-world application.
1. Don’t Forget to Unpin!
A great resource for learning Windows 8 Development is the hands-on labs for the Contoso Cookbook. They give you a step-by-step walkthrough of implementing all of the major Windows 8 features, including the logic to pin a secondary tile. However, their code doesn’t include the ability to unpin a secondary tile. According to the guidelines on secondary tiles, you are supposed to provide this.
Reading the guidelines and checklist for secondary tiles, one of the requirements is:
When the content in focus is already pinned, the app bar button icon and label should be changed to show an "unpin" command instead. This will attempt to remove the existing secondary tile, subject to user confirmation.
Let’s walk through how to implement the functionality for both pinning and unpinning a restaurant as a secondary tile. First, I need to add buttons for pinning and unpinning the restaurant to the AppBar. I added the following code into the XAML of the restaurant’s detail page:
This creates buttons in the AppBar that look like this:
Notice that in the XAML above, each button has a name so I can access it programmatically from my code-behind, as well as style, click, and visibility attributes. Let’s discuss each of these in more depth:
I am specifying the style of each button to be bound to a static resource called “PinAppBarButtonStyle” or “UnpinAppBarButtonStyle”. These are predefined AppBar button styles that were provided in StandardStyles.xaml. If you are not familiar with StandardStyles.xaml, it is included in the Common folder in any Visual Studio XAML template for Windows Store apps. You can leverage the styles defined in it which already follow the Windows UI design guidelines and will look professional and familiar to your users. Definitely poke through StandardStyles.xaml if you have not done so already – there is styling for a variety of common AppBar buttons (like Play, Pause, Edit, Delete, Save, Refresh, Help, etc.) which all derive from the same base AppBar button style, which you could extend for your own custom styles as well.
On the Click event, I am specifying an event handler. Here is the event handler code for clicking “pin” and “unpin”.
Finally, in my XAML, the buttons have visibility attributes which are bound to visibilities. For example, the restaurant’s Pin button is bound to a PinSecondaryTileButtonVisibility. We want this to be visible when the restaurant is not pinned and invisible/collapsed when the button is already pinned.
The logic to change the visibilities when the button is pinned and unpinned is part of the event handler code that you just saw. In addition, we are defining these visibilities in the restaurant details ViewModel:
When we first load the restaurant details, we will initialize these visibilities:
Handle activation argument on launch
The final piece that we need to get secondary tiles working is functionality that recognizes when the app is being called with an activation argument and responds with the deep-linking behavior of secondary tiles. In the OnLaunched method in App.xaml.cs, we will check for arguments and if they exist, we will get the corresponding restaurant from the activation argument and then navigate to its page.
2. Pinning a secondary tile where the logo is from the internet (http not ms-appx)
With this functionality that we’ve implemented, I can pin a restaurant tile to the Start Menu. We are getting the restaurant images which are displayed on the restaurant tile from Yelp. However, in the secondary tile constructor, you need to use a logo image which is located at a ms-appx or ms-appdata:///local/ URI. This means that if I want to use an image from the internet for the secondary tile logo, I have to download it locally before I can use it.
In my “Pin” click handler, I am calling a method called GetLocalImageAsync. This method copies an image from the internet (http protocol) locally to the AppData LocalFolder. Then it can be accessed using the ms-appdata:///local/ protocol and passed into the SecondaryTile constructor.
3. How to debug secondary tiles
There is a trick to debugging secondary tiles. In Visual Studio, you can easily set breakpoints, hit F5 to run the app, and step through pinning the secondary tile to the Start Menu. But when you launch the secondary tile from the Start Menu, you won’t have Visual Studio attached to the process by default. If you want to step through this logic, you can set Visual Studio to wait to attach to your Windows Store app.
Right-click on the C# executable project and select Properties. In the left sidebar, select the Debug tab. In the “Start Action” section, check the box for “Do not launch, but debug my code when it starts”. Then you can press F5 to run and Visual Studio will wait; when you click the secondary tile from the Start Menu to invoke the app, Visual Studio will attach to the process and you can debug.
Secondary Tile Reference
Finally, here are some further resources on secondary tiles.
- Secondary tiles overview
- Guidelines and checklist for secondary tiles
- Quickstart: Pinning a secondary tile – HTML
- Quickstart: Pinning a secondary tile – XAML
- SecondaryTile class
- Secondary tiles sample
Are you interested in further tips on Windows 8 development? Sign up for the 30 to launch program which will help you build an application in 30 days. You will receive a tip per day for 30 days, along with potential free design consultations and technical support from a Windows 8 expert. (See https://aka.ms/JenGenApp and click on “Coders”). Register at https://aka.ms/Jen30TLWin8.