Setting Up the App and Designing the UI

The app we are about to develop will let the user read the weather forecast for any known city around the world. The app will present the information as a five-day forecast, and the data for each day will be sampled every three hours. It will include the expected temperature and an icon to depict the weather conditions.

Start by creating a Single View iOS Application project (File ➤ New ➤ Project…, then iOS ➤ Application ➤ Single View Application) and naming it WeatherApp. We will design the user interface (UI) of the application as part of the setup, so we can focus on code in the rest of the chapter.

Figure 14-1 shows you what the UI will look like: on the left there is a mock-up with the UI elements you will need to place in the view on the storyboard and on the right is a screenshot of the storyboard with the elements already positioned on it.

Figure 14-1. The app’s user interface

As you can see in Figure 14-1, at the top of the screen there is a text field, which will be used to input the name of the city, for which we want to see a forecast, and a button to start a data search for it. The forecast results will be displayed in a table view, where each row will contain a piece of forecast information: the expected temperature, the day and the time, and an image that represents the weather conditions.

Open Main.storyboard and arrange the UI as shown in Figure 14-1 by adding a text field, a button, and a table view. Do not forget to add constraints, so that the app adapts its look to whatever device it runs on. If you need a reminder for how to set constraints and make adaptive UI, have a look at Chapter 5 .

Next, open ViewController.swift and create two outlets, one for the city text field and another for the table view. Then create an action for the Search button’s Touch Up Inside event. (See Chapter 2 for how to create outlets and actions.) Your code should look like that in Listing 14-1.

Listing 14-1. Adding an Outlet and an Action to the ViewController Class

import UIKit

class ViewController: UIViewController {

    @IBOutlet weak var cityTextField: UITextField!
    @IBOutlet weak var tableView: UITableView!

    //The rest of the code goes here

    @IBAction func searchForCity(sender: AnyObject) {
    }

}

Next we will set up the app to connect to a web service. With iOS 9, Apple introduced a feature called App Transport Security (ATS). It forces apps to use the more secure HTTPS protocol by blocking less secure connections that use HTTP. This, on the one hand, is great, as it improves the security and privacy for your users’ data. If you have control at the server end, you can help your app support ATS by setting up the server to use Secure Sockets Layer (SSL). This enables it to send and receive encrypted information. On the other hand, if your app needs to connect to a third-party service, which may or may not support SSL, you may want to bypass ATS.

To do this, open project’s Info.plist file and add new key with name App Transport Security Settings, then add a subkey named Allow Arbitrary Loads and set its value to YES (Figure 14-2). This instructs the app to allow any network connections, including insecure ones.

Figure 14-2. Disable App Transport Security

Note that ATS also allows you to configure behavior for individual domains and only allow non-SSL communications for certain ones (see https://goo.gl/neuUz9 for more details).

With the app set up, let us have a look at the weather web service, which we will query for data.

The Weather Forecast Web Service

The app will get its data from a public weather web service . There are a few of these available on the Internet. For this tutorial we will use OpenWeatherMap. We chose it because it

• has a free account option.

• offers plain and simple URL structure.

• returns data in JSON format.

• has an easy authorization policy: it uses only an application programming interface (API) key at the end of each request.

Before we can use OpenWeatherMap we have to create an account. Every account is given a unique application programming interface (API) key, which is used to authorize any apps you create that send queries to the server.

To create your free account open your favorite web browser and navigate to this URL: https://home.openweathermap.org/users/sign_up . The web site will ask you to enter a username, an e-mail address, and a password (Figure 14-3).

Figure 14-3. OpenWeatherMap’s account registration page

Once your account has been created, you will be redirected to the account settings page. Here you can copy your API key (Figure 14-4). We will use the key later for authorizing the app’s requests to the web service.

Figure 14-4. Get an OpenWeatherMap API key

OpenWeatherMap offers an API that you can explore if you navigate to http://openweathermap.org/api in a web browser. The web site has a detailed manual, which explains how to connect to the service and retrieve weather information. In this tutorial we will focus on how to get the 5-day/3-hour forecast (i.e., a forecast for five days with data every three hours (see http://openweathermap.org/forecast5 for more details).

According to the manual, to get a forecast for a given city using only its name, we need to send a request that has the following format:

api.openweathermap.org/data/2.5/forecast?q={city_name}&units=metric&APPID={api_key}

Let us dissect the request:

• api.openweathermap.org/data/2.5/forecast is the entry point URL for the 5-day/3-hour forecast service.

• The q parameter instructs the weather service that we want to search for a city by its name. The value of the parameter is the name of the city.

• The units parameter specifies the units for the data. If we omit this parameter, we will get temperature data in Kelvins. To use Celsius, set units to metric.

• The APPID parameter expects the unique API key from your account. This parameter needs to be appended to every request to OpenWeatherMap made by the app. If it is missing, the server will respond with an error string.

The response to this request will come in JSON format. JSON is a text format for describing objects with the help of key-value pair hierarchies. Listing 14-2 shows a typical response from the weather service in JSON format.

Listing 14-2. JSON Weather Forecast Response

{
   "city":{
      "id":1851632,
      "name":"Shuzenji",
      "coord":{
         "lon":138.933334,
         "lat":34.966671
      },
      "country":"JP",
      "cod":"200",
      "message":0.0045,
      "cnt":38,
      "list":[
         {
            "dt":1406106000,
            "main":{
               "temp":298.77,
               "temp_min":298.77,
               "temp_max":298.774,
               "pressure":1005.93,
               "sea_level":1018.18,
               "grnd_level":1005.93,
               "humidity":87,
               "temp_kf":0.26
            },
            "weather":[
               {
                  "id":804,
                  "main":"Clouds",
                  "description":"overcast clouds",
                  "icon":"04d"
               }
            ],
            "clouds":{
               "all":88
            },
            "wind":{
               "speed":5.71,
               "deg":229.501
            },
            "sys":{
               "pod":"d"
            },
            "dt_txt":"2014-07-23 09:00:00"
         }
      ]
   }
}

JSON distinguishes the following data types: number, string, Boolean, object, and array. In Listing 14-2 an example of an object is the value following the city key. The weather forecast data is stored in the list array. Every object in the list describes a weather forecast for a certain time of the day.

To get the forecast, we need to read the values of the following keys from the JSON response:

• temp—the temperature of the air, measured in the units we specified in the request.

• icon—a string identifier, which contains an icon name. This name can later be used to download a weather icon.

• dt_txt—a timestamp in a string format.

In the next section we will create a data model class to contain the data, which we extract from the JSON server response.

Preparing the Forecast Data Model

Following the Model-View-Controller (MVC) paradigm , we will create a model to store and work with the forecast data. For a reminder about MVC, see Chapter 5 .

We will create two Swift classes to implement the data model. The first one will represent a single forecast item with all of its data properties. The second one will store a collection of forecast items and will provide helper functions to access those items. We will host both of the classes inside the same swift source file.

In Xcode add a new file to your project, name it ForecastModel.swift, and open it for editing.

Let us start with the first class, ForecastItem. You can see its definition in Listing 14-3. Each forecast item has several properties of type String: a temperature measurement, a day and time for the forecast, and an identifier for the weather image icon.

There is one more property, named uiImageCache of type UIImage. UIImage is a class from the UIKit framework, which stores image data and provides a number of helper functions for loading and displaying data from various formats, such as PNG or JPEG. We will use uiImageCache to store an icon for the forecast.

ForecastItem contains a helper method, which stores image data in uiImageCache: addImageCache. As we will see later, the image data we download comes in an NSData object. You can think of NSData as analogous to ActionScript’s ByteArray. addImageCache uses NSData to construct a UIImage instance and store it in uiImageCache.

Listing 14-3. ForecastItem Class Implementation

import UIKit

public class ForecastItem {
    //Forecast temperature stored as String
    public var temparature : String
    //Forecast date and time entry
    public var dayAndTime : String
    //Weather icon name
    public var imageID : String
    //Cached weather image
    public var uiImageCache : UIImage?

    init( temperature: String, dayAndTime : String, imageID : String) {
        self.temparature = temperature
        self.dayAndTime = dayAndTime
        self.imageID = imageID
        self.uiImageCache = nil
    }

    //Load image from data and cache it
    public func addImageCache(fromData data : NSData) {
        //Create UIImage from NSData
        uiImageCache = UIImage(data: data)
    }
}

Our app will show the weather forecast for five days and the data for each day will be sampled every three hours. This makes 8 forecast items per day or 40 items for the whole five-day period. The next class we are going to implement, ForecastModel, will be responsible for storing these items and for providing access to them to the other parts of the application. The class has four methods:

• getItem: atIndex, which returns a forecast data item from the list by its index.

• removeAll(), which removes all previously stored forecast items from the model.

• appendItem: newItem, which is used to populate the forecast list with new items.

• getItemCount(), which returns the number of the forecast items in the list.

You can see the implementation of ForecastModel in Listing 14-4.

Listing 14-4. The ForecastModel Class

public class ForecastModel {

    //An array of forecast items
    private var forecastData : [ForecastItem]

    init() {
        forecastData = []
    }

    //Remove all forecast items
    func removeAll() -> Void {
        forecastData.removeAll()
    }

    //Get a forecast item at a given index in the forecastData array
    func getItem( atIndex index : Int ) -> ForecastItem {
        return forecastData[index]
    }

    //Add a new forecast item to the list
    func appendItem( newItem newItem : ForecastItem ) {
        forecastData.append(newItem)
    }

    //Get the number of forecast items
    func getItemCount() -> Int {
        return forecastData.count
    }
}

Writing the Network Communication Logic

We will create another class that will be responsible for connecting to the remote server, getting data, and parsing it for the forecast model. This will help with keeping all network communication code in one place.

Add a new source code file to the project and name it WeatherForecastService.swift. Listing 14-5 shows the WeatherForecastService class definition with all the methods stubbed out. We will add functionality to them in a minute.

Listing 14-5. WeatherForecastService Class

public class WeatherForecastService {

    //Path to the API entry point
    private let apiBasePath : String =
        "http://api.openweathermap.org/data/2.5/"

    //Unique key to access the OpenWeatherMap service
    private let apiKey : String = "739c23f0ecc3b86bf0545471b*******"

    //An aray of data tasks
    var dataTasks = [NSURLSessionTask]()

    //Unique error domain of the app
    let errorDomain = "com.diadraw.WeatherApp.WeatherForecastService"

    //Enum of possible error conditions
    enum ErrorCode {
        case noForecastData(Int)
        case urlFormatError(Int)
        case serverError(Int, String)
        case jsonParsingError(Int, String)
    }

    //Get a forecast from OpenWeatherMap service
    //and populate the forecast model
    public func getForecast( forecastModel forecastModel : ForecastModel,
        forCity city: String, completionHandler: (NSError?) -> Void) {
      //The body of the method goes here
    }

    //Request data from the server and decode it into an NSDictionary
    private func requestToServer( apiEndpoint url : NSURL,
        completionHandler: (NSDictionary?, NSError?) -> Void ) {
        //The body of the method goes here
    }

    //Download a forecast PNG icon and cache it in the forecastItem
    public func downloadForecastImage( forecastItem forecastItem :
        ForecastItem , completionHandler: (NSError?) -> Void ) {
        //The body of the method goes here
    }

    //Transforms ErrorCode to NSError
    func getNSError( fromCode errorCode:ErrorCode ) -> NSError {
        //The body of the method goes here
    }

    deinit {
        //The body of the method goes here
    }
}

The class has two constants that are used to build a connection string to the weather service. apiBasePath holds the entry point of the API. The apiKey property, as its name implies, holds the unique API key that we must use to connect to OpenWeatherMap.

For communicating with the weather service we will create several asynchronous tasks to retrieve data from the server. We will keep track of them in an array called dataTasks. This gives us control over safely stopping tasks that may still be running when the app is closed.

Retrieving remote data is not entirely in our control, however. During this process a number of errors may occur. We will use an enumeration for the error states that can happen during data retrieval and decoding.

There are five methods in the WeatherForecastService class.

• getForecast(:forCity:) initiates a request to the forecast API of the weather service and populates the forecast model with the data that comes back.

• downloadForecastImage(:) is called when we need to download an icon to depict the weather conditions.

• requestToServer(apiEndpoint:completionHandler) serves as a generic function that sends request to the web service API, waits for a response, and converts JSON into equivalent Swift objects.

• getNSError:fromCode transforms an error code into an NSError instance that will be used by other parts of the application to inform the user that something went wrong inside the WeatherForecastService class.

• deinit is the place where all open connections to the server and unfinished jobs will be closed.

//Download a forecast PNG icon and cache it in the forecastItem
public func downloadForecastImage( forecastItem forecastItem : ForecastItem ,
    completionHandler: (NSError?) -> Void ) {
    //Get a URL to the weather image from the imageID string
    let url = NSURL(string:
        "http://openweathermap.org/img/w/(forecastItem.imageID).png")

    //Get a shared session instance and start a task
    //to download the image data from the url
    let downloadImageTask = NSURLSession.sharedSession().dataTaskWithURL(url!) {
        (data, response, error) in

        if error == nil {
            print("Download Finished")

            //Get a UIImage from the returned data and cache it
            forecastItem.addImageCache(fromData: data!)
        }

        //The task is complete, call the completion handler
        completionHandler(error)
    }

    // Add the task to the tasks list
    dataTasks.append(downloadImageTask)

    //Start the download task
    downloadImageTask.resume()
}

//Request data from the server and decode it into an NSDictionary
private func requestToServer( apiEndpoint url : NSURL,
    completionHandler: (NSDictionary?, NSError?) -> Void ) {

    //Get a shared session instance and define a task
    let task = NSURLSession.sharedSession().dataTaskWithURL(url) {
        (data:NSData?, response:NSURLResponse?, error:NSError?) -> Void in

        guard error==nil else {
            //There was an error returned from the server
            completionHandler(nil, error)
            return
        }

        // Check for JSON serialization errors
        guard let unwrappedData = data else {
            completionHandler(nil, self.getNSError(
                        fromCode: ErrorCode.jsonParsingError(50,
                        "Unexpected data format.")))
            return
        }

        var jsonObject : AnyObject? = nil

        do {
            //Deserialize JSON data to a dictionary
            jsonObject = try
                NSJSONSerialization.JSONObjectWithData(unwrappedData,
                        options: .AllowFragments)

            //Check if the resulting object from the serialization
            //is a dictionary
            guard let deserializedDictionary = jsonObject as? NSDictionary
            else {

                //We expected dictionary, but some other
                //object was returned. Return error.
                completionHandler(nil, self.getNSError(
                                fromCode: ErrorCode.jsonParsingError(50,
                                "Unexpected format.")))

                return
            }

            completionHandler(deserializedDictionary, nil)
        }
        //There was an error with JSON deserialization
        catch {
            completionHandler(nil, self.getNSError(
                        fromCode: ErrorCode.jsonParsingError(50,
                        "There was an error with JSON deserialization.")))
        }
    }

    // Add the task to the tasks list
    dataTasks.append(task)

    //Start the task
    task.resume()
}                                                                                    

//Get a forecast from OpenWeatherMap service
//and populate the forecast model
public func getForecast( forecastModel forecastModel : ForecastModel,
    forCity city: String, completionHandler: (NSError?) -> Void) {

    //Clean all previeously entered items from the model
    forecastModel.removeAll()

    //Set the forecast API entry point
    let urlString =
        "(apiBasePath)forecast?q=(city)&units=metric&APPID=(apiKey)"

    //Encrypt the URL string to use percent characters instead of blank spaces
    let encodedUrlString =
        urlString.stringByAddingPercentEncodingWithAllowedCharacters(
            NSCharacterSet.URLQueryAllowedCharacterSet())

    //Try to create a NSURL instance from the encoded URL string
    guard let url = NSURL( string:encodedUrlString! ) else {
        completionHandler( self.getNSError(
                fromCode: ErrorCode.urlFormatError(50) ) )
        return
    }

    //Connect to the web service and get data as dictionary
    requestToServer(apiEndpoint: url) {
        (json:NSDictionary?, error:NSError?) -> Void in

        guard error==nil else {
            //Signal that the operation has finished with an error
            completionHandler(error)
            return
        }

        //Check if there is a list of forecast data
        guard let forecastList = json!["list"] as? NSArray else {

            //Check if the server responded with a
            //valid JSON but with error code inside
            if let errorCode = json!["cod"] as? String {

                //Get the server's error message
                let errorMesage : String? = json!["message"] as? String

                //Construct en error message
                let serverError = self.getNSError(
                    fromCode: ErrorCode.serverError(Int(errorCode) ?? 50,
                    errorMesage ?? "unknown error") )

                //Signal with server error
                completionHandler(serverError)
                return                                                
            }
            else {
                //Signal with error: there is no valid forecast data
                completionHandler( self.getNSError(
                                fromCode: ErrorCode.noForecastData(50) ))
                return
            }
        }

        for entry in forecastList
        {
            //Check if all needed forecast properties
            //are present in the dictionary
            guard let forecastTempDegrees =
                        entry["main"]!!["temp"] as? Double,
                rawDateTime = entry["dt_txt"] as? String,
                forecastIcon = entry["weather"]!![0]!["icon"] as? String

                else {
                    //Signal with error that there is no forecast data
                    completionHandler( self.getNSError(
                            fromCode: ErrorCode.noForecastData(50) ) )
                    return
            }

            //Hydrate the forecast model with data
            forecastModel.appendItem(
                newItem: ForecastItem(temperature: "(forecastTempDegrees)",
                    dayAndTime: "(rawDateTime)",
                    imageID: forecastIcon)
            )
        }
        //Signal that the operation has finished
        completionHandler(nil)
    }
}

//Transforms ErrorCode to NSError
func getNSError( fromCode errorCode:ErrorCode ) -> NSError {
    switch errorCode {
    case .noForecastData(let code):
        return NSError(domain:errorDomain, code:code, userInfo:
                 [NSLocalizedDescriptionKey:"There is no forecast data."])
    case .urlFormatError(let code):
        return NSError(domain:errorDomain, code:code, userInfo:
                 [NSLocalizedDescriptionKey:"URL format error."])
    case .serverError(let code, let message):
        return NSError(domain:errorDomain, code:code, userInfo:
                 [NSLocalizedDescriptionKey:"Server error: (message)"])
    case .jsonParsingError(let code, let message):
        return NSError(domain:errorDomain, code:code, userInfo:
                 [NSLocalizedDescriptionKey:"JSON parsing error: (message)"])
    }
}                                                                            

Showing the Forecast in a Table View

Finally, we are ready to show the forecast to the user. We will display every forecast item on a separate row of the table view we added in the beginning of the chapter. Open ViewController.swiftfile and get ready to code.

As we saw in Chapter 6 , the table view needs to get its data from an object, which conforms to the UITableViewDataSource protocol. We will modify the ViewController class to work as a data source and conform to the protocol by first adding the protocol name to ViewController’s inheritance list:

class ViewController: UIViewController, UITableViewDataSource

Then we will add two of the protocol’s methods: tableView(_:numberOfRowsInSection:) and tableView(_:cellForRowAtIndexPath). For now let us just stub them out as shown in Listing 14-10.

Listing 14-10. Implement UITableViewDataSource Protocol’s Methods

class ViewController: UIViewController, UITableViewDataSource {

    //The rest of the code goes here

    func tableView(tableView: UITableView,
        numberOfRowsInSection section: Int) -> Int {
        return 0
    }

    func tableView(tableView: UITableView,
        cellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell {
        return UITableViewCell()
    }

}

Let us override UIViewController’s viewDidLoad method and set up ViewController as the data source for the table view in it (Listing 14-11).

Listing 14-11. Set Up the Data Source for the Table View

class ViewController: UIViewController, UITableViewDataSource {
    override func viewDidLoad() {
        super.viewDidLoad()
        tableView.dataSource = self
    }

    //The rest of the code goes here
}

Next, we will add two properties to ViewController to work with data: an instance of ForecastModel to keep the data and an instance of WeatherForecastService to fetch it from the server (Listing 14-12).

Listing 14-12. Instantiate the WeatherForecastService and ForecastModel Classes

class ViewController: UIViewController, UITableViewDataSource {
    //The rest of the code goes here

    let weatherService = WeatherForecastService()
    let forecastModel = ForecastModel()

    //The rest of the code goes here
}

Let us now add implementation to the two methods we stubbed out earlier, so that the forecast items can appear in the table view. First we will have tableView(_:numberOfRowsInSection:) work out and return the number of items in the forecast model, which corresponds to the number of rows we need in the table (Listing 14-13).

Listing 14-13. Work Out the Number of Rows in the Table

func tableView(tableView: UITableView,
            numberOfRowsInSection section: Int) -> Int {
    //Return forecast items number
    return self.forecastModel.getItemCount()
}

The tableView(_:cellForRowAtIndexPath:) method is called when the table view needs to populate a given cell with data and this is what we will implement it to do (Listing 14-14).

Listing 14-14. Populate a Cell in the Table with Data

func tableView(tableView: UITableView,
cellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell {

    //Create new table cell for the row
    let cell = UITableViewCell()

    //Get a forecast item corresponding to the row number
    let forecastItem = self.forecastModel.getItem( atIndex: indexPath.row )

    //Set the cell's text label to the forecast item’s
    //temperature, date and time
    cell.textLabel?.text =
            "(forecastItem.temparature)° C | (forecastItem.dayAndTime)"

    if forecastItem.uiImageCache == nil {
        weatherService.downloadForecastImage( forecastItem ) { (error) in

            dispatch_async(dispatch_get_main_queue(), {[weak self] in
                if let error = error {
                    //If there is an error message print it
                    print(error)
                }
                else {
                    //Assign the cached image to the cell's image view
                    cell.imageView?.image = forecastItem.uiImageCache

                    //Refresh data in the row
                    self!.tableView.reloadRowsAtIndexPaths([indexPath],
                                                    withRowAnimation: .None)
                }
            })
        }
    }
    else {
        //Assign the cached image to the cell's image view
        cell.imageView?.image = forecastItem.uiImageCache
    }

    return cell
}

In the code in Listing 14-14 we first get a forecast item from the model that matches the row of the cell that has been requested. Then we set the cell’s textLabel property to display the temperature and the date. The interesting part is how we load a weather image in the cell.

The UITableViewCell class comes with a property called imageView, which we use to display a weather image. If the uiImageCache property of the forecast item is not empty, we can assign its value directly to the cell.imageView.image property. Otherwise we have to download the image first and do the assignment once the download is complete. Thus we call the downloadForecastImage method with a closure completion handler, in which the cell’s image view can be updated.

Note the dispatch_async(dispatch_get_main_queue(),{() -> Void}) call in the completion handler. It ensures that the image view update happens on the main thread, as this is the only thread that is allowed to access the user interface in iOS, while our completion handler is most likely to be called on the thread where the download happened.

The last bit of code in the app will be the implementation of the Search button action that queries the server and populates the model with forecast items. Do you remember the @IBAction searchForCity stub we created earlier? This is where we will add the implementation (Listing 14-15).

To populate the model we just need to call weatherService.getForecast and hand a model reference to it. It takes a completion handler, which we will implement as a closure. In it we ask the table view to reload its data if there were no errors while fetching the forecast. Again, we make sure that any UI update happens on the main thread.

Listing 14-15. Implementation of the searchForCity Action

@IBAction func searchForCity(sender: AnyObject) {
    weatherService.getForecast( forecastModel:forecastModel,
            forCity: cityTextField.text!){ ( error : NSError? ) -> Void in

        if let error = error {
            //If there is an error message print it
            print(error)
        }
        else {
            dispatch_async(dispatch_get_main_queue() , {[weak self] in
                //Refresh data in the table view
                self!.tableView.reloadData();
                })
        }
    }
}

And this is it. Run the app and type the name of the place you live in to see if the weather service can find it. If it does, you will get the weather forecast for the next five days (Figure 14-5).

Figure 14-5. Our weather forecast app running in a simulator

Let us see what the weather in London, UK, will be like. Hard to believe! There are some sunny days ahead.

Summary

In this chapter you saw how to create a network session to a remote web service, download images, and work with JSON-formatted data. You built a weather forecast application that retrieves data from the OpenWeatherMap service using the HTTP API the service provides.

In the next chapter we will explore the power of push notifications and Apple’s advertisement channel as a way to monetize your apps.