Tutorial - Part 4

In this part of the tutorial we'll add some UI components that allow the user to select a city and use persistent storage to retrieve the information when the application restarts.


This part of the tutorial is intended to:

  • Show how to use persistent storage
  • Set up city selection UI
  • Add listeners to handle city selection changes

Modifying the UI

Goal: Add city selection UI

We need to add a drop down which will allow the user to select and get forecast information for a particular city. Open index.html and append the following to the body element:

<div id="options">
    <div id="options_header">Select City</div>
    <select id="city_menu"></select>

Populating City Selection

Goal: Running code which modifies page content

  • Open weather.js and remove getWeatherInfo("CA/San_Francisco", populateWeatherConditions); from the document ready listener.
  • In the document ready listener, we will populate a drop-down with some example cities:

        var cities = [ 
            { name: "London", code: "UK/London" },
            { name: "San Francisco", code: "CA/San_Francisco" },
            { name: "Cape Town", code: "ZA/Cape_Town" },
            { name: "Barcelona", code: "ES/Barcelona" },
            { name: "Boston", code: "NY/Boston" },
            { name: "New York", code: "NY/New_York" },
            { name: "Washington DC", code: "DC/Washington" },
            { name: "Tampa", code: "FL/Tampa" },
            { name: "Houston", code: "AL/Houston" },
            { name: "Montreal", code: "CYUL" },
            { name: "Los Angeles", code: "CA/Los_Angeles" },
            { name: "Miami", code: "FL/Miami" },
            { name: "West Palm Beach", code: "FL/West_Palm_Beach" } 
        cities.forEach(function(city) { 
            $("#city_menu").append("<option value='" + city.code + "'>" + city.name + "</option>");

Clearing Displayed Data

Goal: Displaying new data when city selection changes

When the user selects a new city the first thing we want to do is get rid of the old forecast content. The emptyContent function simply clears the old weather information from the html page.

Note: If you decided to have a different layout this function will need to be specific to your custom display.

function emptyContent() {
    forge.logging.log("[emptyContent] removing old data");
    $("#forecast_conditions table tr").empty();

    forge.logging.log("[emptyContent] finished emptying content");

This function should be called every time new data is about to be displayed, which is handled by the populateWeatherConditions. Add the call to emptyContent at the top of the populateWeatherConditions function, which should then look like:

function populateWeatherConditions (weather) {
    var tmpl, output;


    forge.logging.log("[populateWeatherConditions] beginning populating weather conditions");

    tmpl = $("#forecast_information_tmpl").html();
    output = Mustache.to_html(tmpl, weather.current_observation);
    forge.logging.log("[populateWeatherConditions] finished populating forecast information");

    tmpl = $("#current_conditions_tmpl").html();
    output = Mustache.to_html(tmpl, weather.current_observation);
    forge.logging.log("[populateWeatherConditions] finished populating current conditions");

    tmpl = $("#forecast_conditions_tmpl").html();
    output = Mustache.to_html(tmpl, weather.forecast.simpleforecast);
    $("#forecast_conditions table tr").append(output);
    forge.logging.log("[populateWeatherConditions] finished populating forecast conditions");

    forge.logging.log("[populateWeatherConditions] finished populating weather conditions");

Remembering the previous location

Goal: show different weather reports based on the selected city; and remember the previous selected city

The following code should be placed inside of the document ready listener.

When a city is selected from the drop-down list, we want to remember it to use it as the default city when the app is restarted.

To do that, we listen for changes to the city_menu element:

$("#city_menu").change(function() {
    var city = $("#city_menu option:selected").val();
    forge.prefs.set("city", city);
    getWeatherInfo(city, populateWeatherConditions);

See forge.prefs.set. You will need to enable the forge.prefs module in your config.json for the call to forge.prefs.set to work. You can do this via the App Config tab in the toolkit or by directly editing your config.json file:

    "modules": {
        "prefs": true

Using remembered locations

Goal: default to the user's previously selected city when they re-open the app

When the application first runs we want to check if a city has already been saved from a previous run.

  • the first time the app is run, this preference will be null, meaning its value has not been set
  • if a city has been saved previously, it is selected in the drop-down list

    forge.prefs.get("city", function(resource) {
        if (resource) { // user has previously selected a city
            var city = resource;
        } else { // no previous selection
            var city = "CA/San_Francisco";
    }, function (error) {
        forge.logging.error("failed when retrieving city preferences");
        $("#city_menu").val("CA/San_Francisco"); // default;

See forge.prefs.get.

The weather app should now be complete.

  • Build and run the code
  • Bask in all your glory, you have just written an app using Forge!

Reference app

See the part-4 tag in the Github repository for a reference app for this stage of the tutorial.


What's next?

Read about some suggestions on how to extend the weather app.

Alternatively you may be ready to dive into your own app development! Check out the full list of API modules to see what native features you can use and the Recipes section of our docs to learn more advanced topics.