Quick Start Guide to Windows 8 Hero App Template and Server

February 18, 2013 — 4 Comments

In 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 Template and Hero App Server which are built on top of the Finder App Template and Server.

Introduction

The Windows 8 Hero App Template is a template developed to allow developers to quickly and easily create an application to collect certain information while out in the field on a Windows 8 device. For example, if a developer wanted to create an app to allow people to submit information on roads needing pothole repairs, the Hero App Template is a good starting point.

The Hero App Template is a derivative of the Windows 8 Finder App Template described in a previous article and The Hero App Server is a derivative of the Finder App Server described in a previous article.

This article will go through some of the technical features of the Hero App Template and accompanying NodeJS server to store all information. It’s assumed you have already gone through Windows 8 Finder App Template and Finder App Server articles.

Requirements

The following are the requirements for the Windows 8 app and the backend server

Windows 8 App

To develop an app for Windows 8 and to compile and 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.

Backend NodeJS Server

To run the backend NodeJS 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 and Git.  If not please see the following

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

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

Technical Overview

The Hero App template is a Windows 8 Template and a backend server to allow the creation of a Windows 8 application that allows the developer to collect certain information such as ‘pothole repair information’ for various users.

The template compromises of a Windows 8 template and a Backend NodeJS Server.  Both source code projects are a derivative of the Finder App Template and Backend Server so we won’t go in as much technical detail.  Please review the Windows 8 Finder App Template and Finder App Server articles for more technical details.

Windows 8 Template

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

In the next few sections we’ll go through some of the new items added for the Hero App Template

Config.js

Config.js adds a few new properties for authenticating users.  The Hero App template currently supports Facebook OAuth2 authentication.  The new variables are

  1. oAuthLoginProvider – identifies which login type to use and options are facebook
  2. oAuthKey – key to use for API access

Settings are also retrieved from the server and defined in the following variable

  1. settingsUrl – defines the location of the settings to be used for the application

Auth.js

Auth.js handles authenticating users in the application.  The main method to call here is Hero.Auth.login() which will handle authentication using the Windows.Security.Authentication.Web.WebAuthenticationBroker

Data.js

Data.js adds a new variable called Locations.serverSettings. This stores the following server settings that the application adheres to

  1. allowAnonIssues – determines if a user is allowed to submit issues anonymously
  2. allowAnonCommenting – determines if a user is allowed to submit comments to issues anonymously
  3. autoApproveIssues – determines if the server backend is setup to auto approve issues
  4. autoApproveComments – determines if the server backend is setup to auto approve comments

Backed NodeJS Server

The Hero App Template backend server is a server to store any data submitted by users from the Windows 8 application. All information is stored in a MongoDB database and currently the sample uses www.mongolab.com.

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.

As the Hero Backend Server is a derivative of the Finder Template Backend Server, we’ll only cover the new items added to the server

Controllers

The controllers directory now contains three files to handle routing of authentication, the API and the dashboard

live-authentication-controller.js

live-authentication-controller.js handles authenticating users with Windows Live ID. Previously this code was in app.js but has been moved into it’s own file.

hero-controller.js

hero-controller.js contains all the code for API available with Hero server and access by the Windows 8 application.  This file contains all the routes and logic to upload, delete, update and retrieve issues stored in the database.  It also provides the appropriate functionality to retrieve the comments for an issue.

dashboard-controller.js

Dashboard-controller.js handles the settings retrieving and updating the settings in the data.js file. Please note, the rest of the dashboard functionality is contained in app.js if you are looking to modify it.

API Details

The API developed allows for the add, delete or update of issues and also add, delete, update of comments associated with an issue.  The following is a list of the REST APIs available

  1. /issue (GET) – gets all issues in the data store
  2. /issue (POST) – adds a new issue to the data store
  3. /issue/:id (DELETE) – deletes an issue with the passed in id from the data store
  4. /issue/:id/image (GET) – gets the image associated with the issue
  5. /issue/:id/comment (POST) – adds a new comment to an issue
  6. /issue/:id/comment/:cid/image (GET) – gets an image associated with a comment
  7. /settings (GET) – gets the current server settings to be used on the device
  8. /settings (POST) – posts new settings to the server to save

Customization

Now that the core components of the Hero Template have been described, we will go through how to customize the application for your specific scenario.  Again, since it’s built on top of Finder App Template and Server it is very similar to customize.

Application Name

The default application name for the app is Hero Application.  To change this name do the following

  1. Open config.js
  2. Find the appName variable
  3. Change the  name to the desired value

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 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 NodeJS

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!

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 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 Hero 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 Hero 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 Hero App 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 technical details of the Windows 8 Hero Application Template Client and Hero App Template Server discussing some of the minor differences from the Windows 8 Finder App Template and the companion Finder App Server. It also went through customizing the application and getting the application ready for the Windows Store.  If you are not familiar with Windows 8 HTML5/WinJS development or any of the technologies used such as NodeJS, the requirements section listed some relevant articles to get started with Windows 8 HTML5/JavaScript development.

Trackbacks and Pingbacks:

  1. Windows Store Developer Links – 2013-02-20 | Dan Rigby - February 20, 2013

    [...] Quick Start Guide to Windows 8 Hero App Template and Server (Mark Arteaga) [...]

  2. Quick Start Guide to Windows 8 Hero App Template and Server | Windows 8 development | Scoop.it - February 20, 2013

    [...] In 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 Template and Hero …  [...]

  3. Quick Start Guide to Windows 8 Hero App Template and Server - February 20, 2013

    [...] Read original post at Mark Arteaga's Blog [...]

  4. Interesting .NET Links - February 20 , 2013 | TechBlog - February 20, 2013

    [...] Quick Start Guide to Windows 8 Hero App Template and Server – Mark Arteaga [...]

Leave a Reply