Handheld Designer Blog

Tutorial: The Obligatory Weather App, Part 3

April 1, 2013

In the second part of this tutorial, we created a “detail” page that displays the detail from an individual day’s forecast. In the tutorial’s final installment, we’ll create a “settings” page that allows the user to personalize the forecast location.

(You can follow along with the tutorial, or download a fully-functional version of the weather app from the sample gallery within Handheld Designer.)

## Settings Page ##

The “settings” page will be shown when the user taps the “Settings” button in the main page’s header.

To begin building the page, click the “New Page” button and change its id property to settings.

Now that we’ve created the “settings” page, we can add the “Settings” button to the main page’s header. Return to the “main” page by selecting it from the project pane, then select the header in the design view. Set the following properties:

  • rightButtonLabel: “Settings”
  • rightButtonGotoPage: “settings”
  • rightButtonGotoPageTransition: “flip”

This will cause the user to navigate to the settings page (with a “flip” animated transition) when the “Settings” button is tapped.

Returning to the new “settings” page, we can now create that page’s objects.

Page Objects

The settings page contains three visual objects: the header, a textbox where the user can set the location for the forecast, and a radio button group where the user can choose between Fahrenheit and Celsius.

Add the objects to the page as follows:

  • Add a JQMHeaderToolbar object to the page and configure as follows:
    • title property: “Settings”
    • rightButtonLabel property: “Done”
    • rightButtonIcon property: “check”
    • leftButtonTheme property: “b”
  • Add a JQMTextbox object beneath the header. This textbox will allow the user to set the location for the forecast. Configure the textbox as follows:
    • id property: “locationTextbox”
    • label property: “Location”
  • Add a JQMRadioButtonGroup object beneath the location textbox. This object will allow the user to choose between Fahrenheit and Celsius. Configure it as follows:
    • id property: “unitsRadio”
    • label property: “Units”

Finally, add two items to the radio button group’s options property:

  • “F Fahrenheit”
  • “C Celsius”

Note the abbreviated value separated by the vertical bar (i.e. “pipe”) character. This is a special form of values for the options property that performs automatic translation between the text displayed to the user (i.e. the text that appears after the vertical bar) and the string returned by the object’s value property. For example, in this case, if the user has selected the “Fahrenheit” option in the radio button group, the object’s value property will be “F”.

The onLoad Function

The user’s settings are stored in the localStorage object, which allows you to persistently store data on the user’s device. (For more information on the localStorage object, see http://html5.litten.com/html5-web-storage-using-localstorage-and-sessionstorage-objects/.)

The setting page’s onLoad function will be responsible for retreiving the user’s settings from the localStorage object and loading those values in the user-interface controls.

To create the onLoad event handler, select the page object by clicking the design-view background (or selecting it from the popup menu above the property editor), open the “Events” group in the property editor, locate the onLoad property and click the arrow. (Alternately, right/control click an empty area on the page and select onLoad from the “Events” context menu.)

Populate the handler with the following code:

function settings_onLoad(event) {

	// get the settings from persistent storage
	var appSettings = JSON.parse(localStorage.getItem("appSettings"));

	// update the user-interface controls	
	locationTextbox.value = appSettings.location;
	unitsRadio.value = appSettings.units;

Saving the Users’s Settings

Finally, we need to save the user’s settings and return them to the “main” page when they tap the “Done” button in the header. Create a rightButtonOnClick handler by selecting the header in the design view, and opening the “Events” group. (Or alternately, right/control click the header and select rightButtonOnClick from the “Events” context menu.)

Add the following code to the event handler:

function header1_rightButtonOnClick(event) {

	// create an empty JavaScript object to hold the settings
	var appSettings = {};

	// get the settings from the user-interface controls
	appSettings.units = unitsRadio.value;	
	appSettings.location = locationTextbox.value;
	// store them in persistent storage
	localStorage.setItem("appSettings", JSON.stringify(appSettings));

	// remove any cached weather data so the main page will reload:

	// return the user to the "main" page, with the proper animated transition
	application.gotoPage("main", {}, {transition: "flip reverse"});


That’s it! You should now be able to run your app and configure it with your new “settings” page.

While this tutorial gives you a basic weather app, you’re encouraged to make it your own. Adjust the visual design to your taste, add support for multiple cities, and more.

As always, your feedback is welcome. Please use the Handheld Designer contact form for any questions, comments, or suggestions.

Copyright © 2010-2017, Handheld Designer, LLC, All Rights Reserved.
Made by hand in New England, USA.