Not too long ago, as part of my team’s effort (which we call APIMASH) to create a set of starter kits to demonstrate how to use a variety of publicly-available APIs in Windows Store apps, I created an app that leverages the Meetup.com API, along with the Bing Maps JavaScript SDK, to retrieve upcoming Meetups for a given city and also display coffee shops nearby the Meetup location.

You can see a screenshot below:

The goal of my starter kit (and the other kits on the site) is to demonstrate how to call the API from a Windows Store app, how to display the results (in my case using databinding), and also to provide a starting point for folks who might want to “mash up” one of the starter kits with additional data from other APIs.

Reimagining for Windows Phone

The next step in APIMASH is bringing our starter kits to Windows Phone. In my case, my original starter kit was written using HTML and JavaScript, and built on top of the Grid App Visual Studio template, which uses the WinJS ListView control to display the data on the home page.

Because WinJS is not supported on Windows Phone, I had to make a decision on how to move the app to that platform. I could have chosen to use the WebBrowser control, and architect the app using the single-page-app (SPA) style of development, using libraries like KnockoutJS, etc. And if I was starting an app today from scratch that I wanted to build with HTML and JavaScript, and deploy to both the Windows Store and Windows Phone, that would probably be an avenue I’d explore. Perhaps I’ll do just that in a future blog post. In the meantime…

Given the UI differences between a PC and a phone, I figured I would just approach the phone version of the app in the same way I did the Windows Store version…find the Visual Studio template that most closely approximates my needs, and modify it as little as needed to achieve the UX and functionality I desired.

I settled on the Windows Phone Databound app template, as shown in the dialog below:

This template provides a simple databound list in the main page, and when any given item is invoked, the app navigates to a details page for that particular item. The app uses a simplified MVVM architecture, and demonstrates the use of sample data as well.

Understanding the Template

The Windows Phone Databound App template is pretty straightforward. It consists of:

• 2 XAML pages, MainPage.xaml and DetailsPage.xaml (both with accompanying “code behind” C# files.
  • An App.xaml file, whose main purpose in the context of the app template is to instantiate and initialize the main viewmodel of the app (more on that in a moment)

    • A set of design-time sample data, implemented in a XAML file (this file is located in the aptly-named SampleData folder)

      • A pair of ViewModel classes, implemented in C#, a MainViewModel, which implements the items collection which will be bound to a list in MainPage.xaml, and an ItemViewModel, which contains the properties that represent an item.
      Let’s start with the ViewModels. Their job is to abstract the concerns of fetching and parsing data away from the pages. The ItemViewModel has three properties, LineOne, LineTwo, and LineThree, which are implemented with private members for internal representation (whose names start with an underscore and a lowercase first letter), and public properties (whose names start with an uppercase letter). Each one calls NotifyPropertyChanged if the property value changes, so that any controls bound to the data can update the value.

    We could just stuff the values we want for a given meetup into these properties, which would avoid some changes elsewhere in the code, but there are a couple of problems with this…one, it would be potentially confusing to stick with such generic property names, since they don’t tell us anything about what the property represents, and two, we probably actually need more than three properties. We’ll come back to the ItemViewModel momentarily.

    The MainViewModel, which as noted above is instantiated and initialized at app launch in App.xaml.cs, is responsible for creating an ObservableCollection of ItemViewModel items, and (via its LoadData function) populating the collection with data. In the template code, the runtime data is populated by simply adding a bunch of instances of the ItemViewModel class initialized with sample data.

    Template Modifications

    To modify the template code for our purposes, we’ll start with the ItemViewModel.cs class. First, we’ll rename both the class and the filename to MeetupViewModel, to be more descriptive of what the model is. One nice feature of C#, if you’ve not used it before, is the support for refactoring, in particular for renaming members. So when we change the class name from ItemViewModel to MeetupViewModel, Visual Studio gives us a hint that there’s some context-specific commands available, which we can expand using the Ctrl+. keystroke combo, which shows the following:

    

    This command will search the project, and find all references to the ItemViewModel class and update them to the new name. If you prefer to review each change, you can use Rename with preview… This is a very convenient way to quickly update all (well, nearly all…if a member is referred to by a string, such as in the call to NotifyPropertyChanged in the the property declarations, rename won’t update it).

    Next, we’ll update the properties and replace the generic LineOne, LineTwo, etc. properties with more descriptive properties, including MeetupID, Name, Url, Description, CityState (combines the City and State fields from the Meetup venue property, for easier display), and more. One of the advantages of using a ViewModel is that we can describe how we want the data to look for our app, regardless of whether that’s how the original data actually looks. When we load the data, we can massage it to fit the format we want to use.

    That’s all that’s needed for the MeetupViewModel class.

    For the MainViewModel (view the full code here), we’ll start in the constructor. In order to support the retrieval of live data, we’ll add a couple of lines of code to create an instance of the System.Net.WebClient class, and handle its DownloadStringCompleted event:

       1: public MainViewModel()

   2: {

   3:     _client = new WebClient();

   4:     _client.DownloadStringCompleted += 

   5:         _client_DownloadStringCompleted;

   6:     this.Items = 

   7:         new ObservableCollection<MeetupViewModel>();

   8: }