Quick Start Guide to Windows 8 Finder App Template

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:

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.
Microsoft Visual Studio Express 2012 for Windows 8 which is a free version of Visual Studio for Windows 8 development
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

app.onsettings = function (e) {
    e.detail.applicationcommands = {
        "settingsDiv": { href: "/pages/settings/settings.html", title: "Options" },
        "about": { href: "/pages/about/aboutflyout.html", title: "About" },
        "privacyDiv": { href: "/pages/privacy/privacy.html", title: "Privacy Policy" },
    };

    WinJS.UI.SettingsFlyout.populateSettings(e);
};

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

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

appName – defines the application name to show in the upper title bar
staticUrl – defines the URL where the POI information will be retrieved from. Currently the URL must return JSON
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
longitudeField – the field in the returned data that contains the longitude to the POI item
latitudeField – the field in the returned data that contains the latitude to the POI item
nameField – a field in the POI item that contains the name to be used for visual display in the user interface
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

waitText – the text to display while a search is in progress
poiDataAvailable – text to display when data is found
noPoiData – text to display when no data is found
noPoiDataMessage – text to display in message box when no data is found
noPoiDataMessageTitle – the title of the message box for noPoiDataMessage
includeUserLocationOnPoiSelected – determines if the users current location should be included in the map bounds when a POI item is selected
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

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

POI Detail Page

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

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

aboutText – the text to display in the about page
copyright – the copyright information text to include in the about page
version – the version of the app. NOTE: this is taken from a helper function in RedBit.Utilities.appVersion()
versionFriendly – The friendly display of the app version number. NOTE: this is taken from a helper function in RedBit.Utilities.appVersionFriendly()
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

bingMapsKey – key required for use of the map. If you don’t have one see requirements section for obtaining one
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.

Search – will search the in memory data and return the results
Filter – will filter the in memory data and update the Locations.locations variable
reclacDistances – helper function to recalculate distances from current user location
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.

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

Add a new property to RedBit.Settings.js similar to unitOfMeasure
Add the appropriate HTML code to settings.html to display the new setting item
Update settings.js to load and save the new settings to local storage (see wireEvents and loadSettings)
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

{
    d: [
        { 
            "PartitionKey": "0360264785_0000000000", 
            "RowKey": "1", 
            "Timestamp": "2011-06-01T21:33:05.9615281Z", 
            "entityid": "70e4b844-19cd-490d-8483-a1e29dc75f37", 
            "id": "1", 
            "label": "Arbutus Village Park", 
            "official": "1", 
            "streetnumber": "4202", 
            "streetname": "Valley Drive", 
            "ewstreet": "King Edward Avenue", 
            "nsstreet": "Valley Drive", 
            "googlemapdest": "49.249783,-123.155250", 
            "hectare": "1.41", 
            "neighbourhoodname": "Arbutus Ridge", 
            "neighbourhoodurl": "http://vancouver.ca/community_profiles/arbutus_ridge/index.htm", 
            "advisories": "N", 
            "facilities": "Y", 
            "specialfeatures": "N", 
            "washrooms": "N", 
            "address": "4202 Valley Drive", 
            "lat": "49.249783", 
            "lon": "-123.155250"
        }, 
 { ... },
 { ... },
 { ... },
 { ... }]
}

Change the appName variable to Vancouver Parks
Change the staticUrl to http://datadotgcds2.cloudapp.net/v1/Hack%20OpenData/VanParkParks/?format=json
Change the pathToArray to d
Change the latitudeField to lat
Change the longitudeField to lon
Change the nameField to label
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.

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.

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.

Get a Bing Maps key at http://www.bingmapsportal.com/
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

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 Images. Optimizing 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

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.

Open the package.appxmanifest
Change the Display Name and Description in the Application UI Tab
In the Packaging tab change the Package Display Name and Publisher Display Name
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.

Quick Start Guide to Windows 8 Finder App Template

Introduction

Requirements