Quick Start Guide to Windows 8 Finder App Template

February 17, 2013 — 4 Comments

I recently announced the release of two Windows 8 templates on GitHub.  This article will go through a technical overview of the Windows 8 Finder App Template and how to get started with it.

Introduction

The Windows 8 Finder Template is a template developed to allow developers to quickly and easily create a location based type application for the Windows 8 store. It allows a developer to easily pull existing point of interest data into the app to visually display on a map. If no point of interest data set is available, it is accompanied by a backend NodeJS server which allows the importing of data which can be used to feed the Windows 8 application.

In Part 1 of this article we will go through the Windows 8 Finder Template and set it up to consume various feeds to display on a map. In Part 2, I’ll cover the backend NodeJS server and how to get started with that.

Requirements

To develop an app for Windows 8 and to compile or update this template the follow are required:

  1. Windows 8 operating system.  If you are an MSDN subscriber you can download that at the MSDN website. If not you can download an evaluation version of Windows 8 to get started.
  2. Microsoft Visual Studio Express 2012 for Windows 8 which is a free version of Visual Studio for Windows 8 development
  3. Bing Maps SDK for Windows Store Apps which is the map SDK used in the template.
    1. If you are not familiar with it, please see Getting Started with Bing Maps
    2. You will need a Bing Maps Key
    3. Windows Store Developer Account (when you submit to store). See Opening a Windows Developer Account.

This article assumes you are familiar with developing for Windows 8.  If you are not familiar with it please see Windows Developer Centre on MSDN specifically the Getting Started with Windows Store Apps.

This is all that is required to get started, once that is downloaded and installed, you can get started.

Technical Walkthrough

Windows 8 store apps allow you to build apps in C#/XAML, JavaScript/HTML5/CSS3 or C++.  The Finder App template was written using JavaScript & HTML5/CSS3.

In the next few sections we’ll walk through some of the core sections of the template and give a description of each.  If you are not familiar with creating a Windows 8 app using HTML please see Create Your First Windows Store App Using JavaScript.

The next few sections will go through some of the core files in the template that you will need to be familiar with to customize the template.

Default.js

Default.js is the main JS file where everything starts off.  All code is pretty much standard with the exception of WinJS.Application.onsettings which allows us to add any pages available for our settings flyout.  The following code accomplishes this

Which results in our Options, About and Privacy Policy links shown in our apps settings page.

 settings-options

Config.JS

Config.js holds all the runtime configuration for the application.  The next few sections will describe what portions are container in here.

Point of Interest Data

The following variables hold specific information to decipher the point of interest data and can be found under the Finder.Config namespace

  1. appName – defines the application name to show in the upper title bar
  2. staticUrl – defines the URL where the POI information will be retrieved from.  Currently the URL must return JSON
  3. pathToArray – in some instances, the data returned by the staticUrl may be in an array.  This variable allows us to set the path to allow us to extract the details
  4. longitudeField – the field in the returned data that contains the longitude to the POI item
  5. latitudeField – the field in the returned data that contains the latitude to the POI item
  6. nameField – a field in the POI item that contains the name to be used for visual display in the user interface
  7. secondaryField – a field in the POI item that contains an arbitrary secondary field to be used for visual display in the user interface

Helper Text

Throughout the app various text is displayed that is defined in this config.js file.  These fields are as follows

  1. waitText – the text to display while a search is in progress
  2. poiDataAvailable – text to display when data is found
  3. noPoiData – text to display when no data is found
  4. noPoiDataMessage – text to display in message box when no data is found
  5. noPoiDataMessageTitle – the title of the message box for noPoiDataMessage
  6. includeUserLocationOnPoiSelected – determines if the users current location should be included in the map bounds when a POI item is selected
  7. includeUserLocationOnPoiDisplayed – determines if the users location should be included in the map bounds when all the POI data is displayed on the map

Sharing Configuration

The application has the ability to share a POI item using the sharing charm.  This section describes the details of the variables used

  1. shareTitle – the title of the message when sharing
  2. shareText – the text to use when sharing
  3. shareDescription – the description of the share item

POI Detail Page

The detail page allows you to show information text on the POI details page.

  1. infoFormat – this is the format of the information field to be displayed

About Page Configuration

The about page is dynamically generated from the following variables

  1. aboutText – the text to display in the about page
  2. copyright – the copyright information text to include in the about page
  3. version – the version of the app. NOTE: this is taken from a helper function in RedBit.Utilities.appVersion()
  4. versionFriendly – The friendly display of the app version number. NOTE: this is taken from a helper function in RedBit.Utilities.appVersionFriendly()
  5. contactUsText – the text to display to allow users of the application to contact the developer

Bing Maps Configuration

Bing Maps is used as the main map to display POI items.  Used are Bing Maps routing API and the Map JavaScript control. The following describe the variables required

  1. bingMapsKey – key required for use of the map. If you don’t have one see requirements section for obtaining one
  2. routeUrl – URL used for routing

Data.js

Data.js is the main JS file that will contain the downloaded data in memory and manage downloading any of the data.

Locations Namespace

This is the main namespace that will hold the data in memory and also will hold any other application state in memory for example the currently selected POI in the variable selectedPOI.  Please see data.js for more details on the variables.

Finder.Data Namespace

The Finder.Data namespace holds various helper functions for the retrieval of data.

  1. Search – will search the in memory data and return the results
  2. Filter – will filter the in memory data and update the Locations.locations variable
  3. reclacDistances – helper function to recalculate distances from current user location
  4. getData – retrieves the data from the URL specified in Finder.Config.staticUrl and also uses the various variables in the config.js explained in the previous section.

RedBit.Settings.js

This JS file is a helper library to help with saving application settings. It will be found under the RedBit.Settings namespace and currently only has the unitOfMeasure property which determines if the distance being displayed should be in Miles or Kilometers.

settings-sample

The pages/settings/settings.html page will read from the settings and display appropriately in the user interface.

To add a new setting type do the following

  1. Add a new property to RedBit.Settings.js similar to unitOfMeasure
  2. Add the appropriate HTML code to settings.html to display the new setting item
  3. Update settings.js to load and save the new settings to local storage (see wireEvents and loadSettings)
  4. Use the new property created throughout your application as needed

RedBit.Windows.jquery.js

If you have done web development before then you may be familiar with jQuery.  If you are not, essentially jQuery is a JS library which allows for easy access to the HTML Document object model and handles the many browser differences.

When using jQuery with Windows 8, there was no need to determine which browser was being used as we knew it was IE10 engine, so doing browser checks did bring a performance hit.

RedBit.Windows.jquery.js is a substitute library used for Windows 8 development to allow code compatibility with web based applications.

This is an open source project located on www.GitHub.com and is ongoing work.  It is not a full replacement for jQuery currently, but is the start of some of the main methods required for this template.

Feel free to keep up with the RedBit.Windows.jquery.js project and contribute.

Customization

Now that the core components of the Finder Template have been described, we will go through how to customize the application for your specific scenario.

Changing the Data Feed

The data feed is what will be driving what information to display on the map and it will be configured in config.js. Config.js includes some sample feeds that can be used and we will use one of them as a walkthrough here.

In the next few steps we will configure a Vancouver Parks data feed which has the following format

 

  1. Change the appName variable to Vancouver Parks
  2. Change the staticUrl to http://datadotgcds2.cloudapp.net/v1/Hack%20OpenData/VanParkParks/?format=json
  3. Change the pathToArray to d
  4. Change the latitudeField to lat
  5. Change the longitudeField to lon
  6. Change the nameField to label
  7. Change the secondaryField to address

After these changes are complete the application will download the new dataset and display the POI information appropriately including changing the upper bar title.

finder-customization

 

Changing the About Screen

The about screen is where you want to show information about the application and how users of your application can contact you.

finder-about

To customize the about screen, modify the variables related to the about screen in config.js.  For further customization, modify the files located under /pages/about.

Changing Your Keys

Before you are able to run the application on your own, you will have to obtain and set your keys within the app.

  1. Get a Bing Maps key at http://www.bingmapsportal.com/
  2. Set your key in config.js in the bingMapsKey variable

Getting Ready for Windows Store

To get ready for the Windows Store, you will be required to change a few small things in addition to the items described in the Customization Section. In addition MSDN has documentation to get you familiar with the process of submitting a Windows Store app

  1. Selling Windows Apps
  2. Publishing your app To the Windows Store
  3. Packaging your Windows Store app using Visual Studio 2012

In the next few sections, we will cover some of the high level items that you will need to change to get your application submitted to the store.

Obtaining a Windows Store Account

You will be required to have a Windows store account to be able to publish into the Windows Store.  See Opening a Windows Developer Account on how to open an account.

Icons

The Finder App template has the default icons that Visual Studio inserts when you create a new Windows 8 project.  If you attempt to submit your customized Finder Template application with these icons you will fail certification.

The icons can be found under the /images directory.  To assign the new icons you must first create some icons following the guidelines in Choosing Your App ImagesOptimizing Images for Different Screen Resolutions is also a relevant resource when creating your icons.

You can modify your package.appxmanifest file by double clicking it which will bring up an editor to assign icons

finder-package-x

Splash Screen

Windows Store Apps must have a splash screen and the Finder Template uses the default one that comes with Visual Studio.  You will be required to change this before submitting to the store.  See Adding a Splash Screen on MSDN for more details for adding this.

App Name & Description

Changing the application name was already covered in the Customization Section but unfortunately there are a few more places to change this.

To change the name and description, do the following.

  1. Open the package.appxmanifest
  2. Change the Display Name and Description in the Application UI Tab
    finder-customization1
  3. In the Packaging tab change the Package Display Name and Publisher Display Name
    finder-customization2
  4. NOTE: the Publisher name will change when automatically when you submit your application to the Windows Store.

This is the core of customization and getting your application ready for the Windows Store.

Conclusion

This article went through the details of the Windows 8 Finder application template and how to customize it for use with different data feeds.  It also went through getting the customized application ready for the Windows Store and listed some relevant articles to get started with Windows 8 HTML5/JavaScript development.

In the next part, we’ll look at using a server to store our custom data and to display within the application.

Trackbacks and Pingbacks:

  1. Quick Start Guide to Windows 8 Finder Template Backend Server | Mark Arteaga - February 17, 2013

    […] Part 1 of this article we went through the Windows 8 template and set it up to consume various feeds to […]

  2. Quick Start Guide to Windows 8 Hero App Template and Server | Mark Arteaga - February 18, 2013

    […] two previous articles, I went through a technical overview of Windows 8 Finder App Template and the companion Finder App Server.  In this article, I’ll go through the Hero App […]

  3. Hacking Open Data with the Finder Template and a Sandwich: Citizen-Ready Apps in Minutes | OpenHalton - April 5, 2013

    […] the Quick Start Guide – Mark Arteaga did a great write-up that walks through pretty much the same thing I’m doing here, but more technical and without a […]

  4. Hacking Open Data with the Finder Template and a Sandwich: Citizen-Ready Apps in Minutes | OpenHalton - April 5, 2013

    […] Browsed the Quick Start Guide – Mark Arteaga did a great write-up that walks through pretty much the same thing I’m doing here, but more technical and without a sandwich. I focused on the Requirements & the Customization Section. […]

Leave a Reply