I recently released two Windows 8 templates on GitHub with an accompanying quick start guide for the Finder App Template. This article will go through the optional NodeJS backend server and how to get started with it and connect it to the Windows 8 template.

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 display on a map. If no point of interest data is available, it is accompanied by a backend server which allows the importing of data which can be used to feed the Windows 8 application.

In Part 1 of this article we went through the Windows 8 template and set it up to consume various feeds to display on a map.

In this part, we will go through some of the features of the NodeJS backend server and how to connect to the Windows Finder App Template.

NOTE: the backend server is optional and not required for the Windows 8 Finder App Template.

Requirements

The Finder App Template Backend Server is writing in NodeJS running on Windows Azure Web Sites.

To run the backend server on Windows, you will require the following

1. NodeJS installation from http://nodejs.org/
2. Git for Windows used for local version control system and to push to Azure Web Sites
3. http://mongolab.com/ account. Sign up is free for 500MB of storage.  Make sure to create your storage on Azure (NOTE: it is still in beta)
4. Windows Azure Account (90Day free trial will suffice)

This article assumes that you are familiar with NodeJS, JavaScript, MongoDB, Git and Windows Azure Web Sites.  If not please see the following

1. Node.js on Windows Azure
2. www.git-scm.com
3. Getting Started with MongoDB

Technical Walkthrough

The Finder App Template backend server is a server to store any relevant point of interest information in a MongoDB database.

The server contains all APIs to pull data and also contains APIs to push data into MongoDB. It also contains the web user interface to view the data from an administrative point of view.  The web application is not to be used for end users.

Technologies Used

The backend server was written using the following technologies

NodeJS

NodeJS was used to develop the backend server as well as publically available open source modules to add functionality to the backend server.  The following core modules were used for development

1. ExpressJS – web application framework providing features for developing single, multi-page and hybrid web applications.
2. HoganJS – a compiler for the Mustache templating language.
3. MongooseJS – a MongoDB object modeling tool designed to work in an async environment
4. PassportJS – extendable authentication framework
5. Passport-WindowsLive – authentication strategy for use with Windows Live accounts using in conjunction with PassportJS

If you are unfamiliar with any of these modules, please read the links above before continuing

MongoDB

The storage of all point of interest data is stored in MongoDB using MongoLab as a third party data store.

File Structure Overview

In the next few sections we will outline the file structure of the project.

If you are familiar with MVC pattern, this should be familiar to you also.

App.js

App.js is the main file that runs our server.  It is responsible for starting up our HTTP server and managing the routing of web requests.  To start the server, all that is required is typing in node app.js on the command line and you will be presented with Express server listening on port 3000.  Any request that comes in will be displayed to the company console

App.js contains how the server handles any requests that come into the system.   On line 33 (approx.), there are the definitions of the routes and where it should point to. For example, navigating to http://localhost:3000 shows the main page and makes sure we are authenticated with the following code

app.get('/', ensureAuthenticated, routes.index);

The ensureAuthenticated() makes sure the user is authenticated using PassportJS before presenting them the content. If not authenticated it will route them to the login page.

Routes

The routes directory contains one file called index.js. This sets up all our routes and how we should render our views to the user.  For example the following code will render the index view which was setup in the previous section

exports.index = function(req, res) {
	res.render('index', {
		title: 'Express',
		user: req.user
	});
};

 

Notice how we can pass in the title and we can also pass in any objects into the view to be rendered in to the user.

Views

Views contain all our templates for the web application views. For example the index page is defined in index.mustache.  layout.mustache defines the layout of the application and index.mustache will be ‘inserted’ into the layout at runtime.  This allows us to separate the various views into its own file for display.

Model

The model directory contains our POI model and user information pull from MongoDB.

Public

This directory contains any CSS, javaScript or images image files required for the dashboard.  These are usually files that are included in HTML head tags.

Changing Your Keys

Before you are able to run the NodeJS server on your own. The following sections describe the details.

Windows Live ID Authentication

The NodeJS server uses Windows Live ID authentication to sign into the server. You will need to obtain a Key and Secret for the server to function.

1. Obtain a client ID and secret at http://dev.live.com for Windows Live ID Authentication
2. In app.js, change the following with the keys you just obtained
   1. WINDOWS_LIVE_CLIENT_ID (line 11) with the ID you just created
   2. WINDOWS_LIVE_CLIENT_SECRET(line 12) with the secret you just created
   3. callbackURL to the url to handle the authentication. The sample in GitHub has an Azure Web Site url but you can essentially host it anywhere that supports NodeJ

MongoDB

A MongoDB is used for the backend data store of point of interest data. The following will get you up and running on http://MongoLab.com

1. Go to http://mongolab.com and create an account
2. Once an account is created, create a new database setting your Cloud Provider to Windows Azure. The free plan will suffice
3. Once created, copy the URL to connect to the database.  Should look something like mongodb://<dbuser>:<dbpassword>@ds011111.mongolab.com:11111/databaseName
4. Open up model/baseRepo.js
5. Replace the path variable with the connection string you just copied

If everything goes well, you should be able to run the server with the node app.js command and navigate to http://localhost:3000 in a browser.

Debugging Server Locally

To debug the server locally you will have to change a few lines as Windows Live ID SDK does not allow you to set a callback URL of http://localhost.  To debug the server locally, do the following

1. Open up app.js
2. In the ensureAuthenticated function (near the bottom)
   1. comment out the if statement
   2. uncomment the return next() line

When running the server, it should no longer ask you to authenticate.  NOTE: remember to change this back when pushing to production!

API Details

The API developed for the dashboard allows for pulling of POI items into and also uploading data into the system from the dashboard.  The following is a screen shot of a dashboard running locally

Data Sets Available

The system supports adding multiple data sets as shown in the image above.  To get a list of data sets available, the following API format can be used

http://localhost:3000/api/tables

Calling this URL on our local server instance will result in the following JSON data

["Flu_Data","Another_Flu"]

 

Pulling Data from Data Sets

Pulling data set data is just as easy as determining the data sets available.  To get a list of data in the data sets, the following API format can be used

http://localhost:3000/api/data/[DATA_SET_NAME]

And an example is

http://localhost:3000/api/data/Flu_Data

Note that the data set name is case sensitive, and calling this will return the following information

The default format returned is JSON, but the API supports returning CSV, RSS, XML by appending the type at the end of the url

1. CSV – http://localhost:3000/api/data/Flu_Data.csv
2. RSS – http://localhost:3000/api/data/Flu_Data.rss
3. XML http://localhost:3000/api/data/Flu_Data.xml

Uploading Data

Uploading data allows you to add your own POI information to your MongoDB instance as a data set.  Navigating to http://localhost:3000/upload produces the following

Set the Dataset Name, Path To Items if your dataset is in an array and select the JSON file.  Internally, the parsing and uploading of the data happens in index.js on the exports.uploadPost method.

NOTE: Currently the only supported upload format is JSON.

Publishing to Windows Azure

Publishing a NodeJS project to Windows Azure is beyond the scope of this article. Fortunately there are many resources on publishing to a NodeJS project Windows Azure Web Site.  The following are some relevant articles that will help you along

1. Build and Deploy a Node.js Web Site to Windows Azure
2. Build and Deploy a Node.js web site to Windows Azure using WebMatrix
3. Using Node.js Modules with Windows Azure Applications
4. Publishing a Web Site with Git

Once you have published your NodeJS application, you will be ready to connect it to your Windows 8 Finder application.

Connecting to Windows 8 Finder Template

The Windows 8 Finder template customization was discussed in Part 1 of this article. As a quick overview you will be required to change config.js with the following

1. staticUrl to your Windows Azure server
2. latitudeField to the name that contains the latitude in your data set
3. longitudeField to the name that contains the longitude in your data set
4. nameField to the field name that contains the name of the data set item data set item to display
5. secondaryField to the field name that contains other information of the data set item to display

Conclusion

In part 1 of this article, we went through a technical overview and customization of a Finder App Template.  In this part, we went over the technical details of the Finder App Template backend server, how to upload data to the server and how to connect it to the Windows 8 Finder Template.