Learning iCloud Data Management (2014)

Part II: Using the APIs

3. Introducing the APIs and the First Apps

This part of the book shows you how to take advantage of the data your users have placed in iCloud either directly or indirectly by using apps that synchronize their data with iCloud. These apps include Contacts, Reminders, and Calendar as well as iPhoto on OS X or Camera on iOS. iCloud makes this data available to users on all their devices. The opportunity for you as a developer is to build apps that let users take this data and work with it. Their contribution is their data; your contribution is an understanding of what they may want to do with their data. The apps from Apple provide powerful support for the most common tasks that people want to perform with their data, but there are literally thousands (make that hundreds of thousands) of apps that let people combine their data with your ways of working with it.

This chapter introduces the project you’ll be working on in this part of the book. You’ll see what it can do, and you’ll set it up with Xcode.

Getting Started as an Apple Developer

You’ll find documentation and tools on Apple’s Developer website at developer.apple.com. You need to register with an Apple ID for access to many parts of this content. You can use an existing Apple ID (such as one you’ve used in the App Store or iTunes) or you can create a new Apple ID that you will use with your developer’s hat on. There is no charge for an Apple ID.

Each Apple ID has an email address associated with it along with your identity. Apple confirms your identity automatically by sending an email to the email address you provide. When you reply, Apple knows that—at least at that moment—you are the person associated with that email address. You can change any part of this supporting information at any time by logging in to appleid.apple.com, as shown in Figure 3.1. You repeat the verification process if you change your email address.

Figure 3.1 Configuring your Apple ID

To gain full access to developer resources on developer.apple.com, you need not only an Apple ID but also to register as a developer. You can find the details on developer.apple.com: they vary from country to country and they also change from time to time. There are separate programs for iOS and Mac developers; each costs $99 per year in the United States at the time of this writing. That fee covers access to the full site as well as two technical support incidents in which Apple engineers can help you with your code. There is an additional program for Safari developers, which is free.

In addition, there are specialized programs for in-house developers (the Enterprise Program) and for university-level teachers (the University Program). Rounding out the developer programs is the MFi Program, which is designed for manufacturers of accessories for the iOS devices. There are full details on developer.apple.com.

You can continue with this book with just an Apple ID (no charge), but you will need a developer registration in order to proceed to steps such as deploying your apps on iOS devices as well as creating entitlements to use iCloud. You may already have access to a developer account through the University Program or the Enterprise Program, so make inquiries before getting out your credit card.

As noted, many aspects of the developer programs are available without registration; however, from now on this book assumes that you have access to a developer account. Furthermore, this book assumes that you have downloaded and installed a current version of Xcode, the development tool—version Xcode 5 or later. If you have not used Xcode before, take a few moments to experiment with it. It comes complete with templates for projects that you can build and run either on the iOS simulator, your iOS devices, or on your Mac.

Looking at the APIs

As developers, we look at software very differently than users do. Of course, we’re users as well as developers, and we use Mail and Safari along with other users. We also have our own apps to work with, foremost among them Xcode, which is the integrated development environment (IDE) that we use to build apps. When it comes to user data (appointments, notes, contacts, and the like) we work with the application program interfaces (APIs) that are implemented in the frameworks that we use to build our apps.

Most of the APIs that relate to user data have a common architecture. They let you (that is, you as a developer, not you as a user) locate objects such as photos, add new ones, delete old ones, and modify the data. In this part of the book, we focus on AddressBook and Calendar: once you have built a project using both of those APIs, moving on to other APIs should be relatively easy (and you’ll do so throughout the book).

The APIs that are involved with the management of user data are found in the documentation section of developer.apple.com under the Data Management section, as you see in Figure 3.2. This section has a large selection of APIs in it. Note that the names of the APIs generally reflect the names they had when they were developed. Sometimes (as is the case with AddressBook) the consumer tools for using the data has a different name—Contacts. To avoid breaking existing code, the names of the API and its classes generally do not change.

Figure 3.2 Browsing the Data Management APIs

The APIs that relate to user data are

AddressBook

ALAsset (for photos and videos on iOS)

Calendar and Reminders

As Lao-Tzu said, the journey starts with a small step, so at the beginning the focus will be on AddressBook as well as Calendar and Reminders.

Introducing the Built-In Data Apps

In this part, we build an app that lets you type in a brief message and send it to someone in your address book. You’ll be able to add reminders along with the message.

This app may seem like a reimplementation of a very small part of Mail, but it is an example of how you can combine the user’s data with functionality that you create. From this basic step that does, indeed, duplicate a small part of Mail, your app can grow so that in addition to your message, you can add a reminder to the message. That reminder will automatically be synced to all of the user’s devices (assuming that iCloud is enabled—that point won’t be repeated from this point on). The evolution of the app as described in this part demonstrates how adding specific functionality can make the app much more useful to users.

Keeping Up with Apple

There is another important aspect of this app. As noted in the Preface, you should already be familiar with Objective-C and the Cocoa and Cocoa Touch frameworks as well as how to use Xcode. This book is based on Xcode 5, OS X Mavericks (10.9), and iOS 7. Before 2012, Apple went to great lengths not to break code (generally a good idea) and not to force developers to adopt new technologies and ways of coding that they did not want to use. That is why, for example, many of the features of Objective-C 2.0, such as declared properties, released in October 2007 (just 4 months after the debut of the first iPhone), are not more widely used by developers.

When Automatic Reference Counting (ARC) was introduced in iOS 5 (2011), Apple’s guidance to developers was to use it for new projects as well as for major extensions to existing projects, but not to attempt to retrofit it onto old projects. This approach was necessary because of the developer tools available at the time, but it slowed the adoption of ARC.

In Xcode 4.4 (Summer 2012), Apple began to roll out a new approach to helping developers keep up to date. First of all, the default settings began to generate Xcode warnings when new features were not used. You can turn off the warnings or even ignore them, but now you are reminded that, for example, declared properties are in and instance variables are out. Furthermore, in the case of declared properties, Xcode takes care of creating backing variables for you based on the property declaration. The backing variable for myProperty is _myProperty by default, and you can reference it in your implementation file. You no longer need to write @synthesize statements because Xcode can generate them for you behind the scenes. All in all, to use a declared property, all you need is the property declaration: Xcode does the rest.

To further encourage the use of these new features, Xcode 4.4 adds two new commands to the Refactor submenu in the Edit menu. Both are self-explanatory: Convert to Objective-C ARC and Convert to Modern Objective-C Syntax. Both scan your project and suggest changes in the Version editor. You can go through comparing the before and after code and then decide if you want to save it.

With these new tools and the new approach to framework and tool changes, there is no reason to be concerned: if you knew Objective-C, you still know it, and the same goes for Xcode and the frameworks. Because this chapter introduces the book’s first app, as part of that introduction, a few points of the new styles are pointed out, and they are used without further comment throughout this book.

With Xcode 5, more simplifications have been made: specifically, the complete redesign of project settings and the addition of the Capabilities tab has made the process of configuring your app’s entitlements much easier. (You saw these features in Chapter 2, “Setting Up iCloud for Development.”) All of these initiatives have a common goal of pushing changes to the language and frameworks into developers’ apps sooner rather than later.

A good example of these changes is available in “View Controller Catalog for iOS” on developer.apple.com. This document shows the way in which the basics of Objective-C, Cocoa and Cocoa Touch, and Xcode evolve over time. It formerly was part of “View Controller Programming Guide for iOS” but was rewritten and published on its own in January 2012.

As people began to work with iPhone and iPad (people both within and outside Apple), they discovered new ways of working and new interface possibilities. Today, you can search the web for advanced techniques involving iOS views, including such complicated issues as placing a split view controller within a tab bar. You can find code examples that you can use.

Apple addressed these issues of advanced view techniques, and what had been an advanced topic became much simpler. Although the catalog is 70 pages long, you really only need to know two points:

Apple now distinguishes between content view controllers and container view controllers such as split view controllers, tab bar controllers, and navigation bar controllers.

If you use container view controllers, the order of containment is now specified clearly by Apple. If you use them, they must be used with the split view controller (if used) as the topmost view; then (if used) a tab bar controller and, within it, a navigation controller if you use it; and finally, content view controllers and page view controllers. The examples of placing split view controllers within tab bar controllers that you can find on the web may work, but they are now clear violations not just of the human interface guidelines but also of the order of containment, and they may not work in the future.

Thus, something that was an advanced topic in view management as well as an unclearly defined topic has become a basic principle that can be expressed in two thoughts. Sometimes, working with the excitement of new technologies means observing (and participating in) the evolution of those technologies. Many of us find the most exciting part of this evolution to be the synthesis of different ideas that makes things easier. Unfortunately, this does mean that from time to time we need to revisit the basics because they have changed.

These changes can ripple through the APIs and development tools, but it is important to stress the point that you’re not back at the beginning. Many things are easier (and clearer), and occasionally you have a new way of working. Continuing with the issue of container views, you’ll note that in Xcode, some of the library objects that you drag into storyboards come complete with attached and connected container views. Together with the clear containment order from the catalog, this complex process is now simpler and very clearly documented. Your existing knowledge and skills are leveraged.

Fortunately, long-time Apple developers have observed that these changes are reasonably predictable. They revolve around Apple’s Worldwide Developers Conference (WWDC) that is held in June. WWDC typically includes details of new versions of iOS and OS X as well as Xcode. If there are cleanups to existing technologies (such as the view catalog), these typically happen with revised documentation in the first half of the year. New technologies are often announced at WWDC, and documentation pertaining to them is released at that time. As a result, if you want to keep up with Apple’s developer technologies once a year, log in to developer.apple.com a few weeks after WWDC to see the announcements, documentation, and videos. (Beginning in 2013, Apple released videos of the sessions on the same or next day to all registered developers.)

Finally, over time, the pace of the major changes slows down as Apple generalizes concepts and rewrites the basics with the goal of making OS X and iOS development simpler and easier to learn. (Of course, at the same time, the pace of other changes steps up. Read the unofficial Apple blogs to see what Apple may or may not be working on in the next few years.)

App Overview

Think of how this app can be used. It is based on the Broken Swings app built for Steve Peters, superintendent of recreation for the City of Plattsburgh, New York. A parks supervisor can use it on periodic inspections to note broken swings, trees that need pruning, or any other issue. The supervisor can use the app to send that information to a staff member. The reminder can be used to ensure the worker or the supervisor follows up on the issue. In the domain of a park, you can start to build an app that goes far beyond the generality of Mail. For example, instead of asking the supervisor to type in the problem, you can provide a checkbox set with these choices:

Broken equipment

Pruning (tree)

Pruning (bush)

Water fountain

If the app is running on a device with a camera, the user can add a photo of the offending item. And if the device also has location capabilities, that, too, can be added to the email message.

This type of app is ideally suited to one of the iOS devices because it can be used in the field even by a large number of people. The email messages can go to a central address where someone can forward them or place them in a database.

This app lets you take advantage of iCloud without writing a single line of code: address book and calendar data is automatically synced across devices so that the possible recipients of the email message are on whatever device your user is using. Likewise, the reminder can be automatically added to all of the user’s devices using iCloud.

Thus, the simplest way of building a sophisticated iCloud app can be to build an app that uses iCloud-enabled built-in apps and their APIs.

Creating Separate Xcode Projects for iOS and OS X

The first step is to create a project and run it. For projects that will run on both iOS and OS X, it is common (but not required) to create a single Xcode project with two targets. For a project such as this first project, though, you will be letting iCloud do its work behind the scenes, so you do not need common code that will run on both operating systems. The code will be comparable, but you do not need to create a single project with two targets. Because this structure is a little simpler than the multitarget structure, these first apps will have two separate Xcode projects: one for iOS and one for OS X. (You’ll see how to build a single project with both an iOS and OS X app in Chapter 11, “Using Xcode Workspaces for Shared Development.”)

Note that this is one of the places where recent features of Xcode are demonstrated. Previously, Xcode templates that used two targets used scenarios such as one target for OS X and another for Spotlight support. Now, the two targets, at least for iCloud projects, can be iOS and OS X. That is a long-awaited goal that is now achieved.

In both the iOS and OS X Xcode projects, you will produce a (minimally) working version of the app using the graphical user interface of Xcode. The only typing involved in the creation of each project is typing in the name of the app (and, if you haven’t done so before, the name of your company). There is no code to type in for these projects, but rest assured there will be plenty to type in throughout the rest of the book.

Creating the iOS Xcode Project

As a general rule, the templates built into Xcode are the most up-to-date code you can find. If you are working from a previously downloaded sample, check to see if a new version has been created on developer.apple.com and also check the date of the most recent version. With the addition of the refactor commands in the Edit menu, it seems that the sample code can be updated more easily than before. If you’re working from your own older code, seriously consider at least refactoring it to use modern Objective-C syntax and ARC.

Bearing this in mind, the best way to start your new iOS app is to create a new iOS project using the Single View Application, as shown in Figure 3.3.

Figure 3.3 Using the Single View Application template

Select the options, as shown in Figure 3.4.

Figure 3.4 Selecting options

When requested, save the project. When the workspace window opens, as shown in Figure 3.5, choose Universal for Devices. The other settings are fine to leave as-is.

Figure 3.5 Choosing Universal for the Devices setting

Choose the iPhone simulator for your scheme (you can use any iPhone or iPad), and then click the Run button at the upper left of the workspace window to run your new project on the simulator. You should see no error messages, and, in fact, nothing except the blank simulator. Any other result indicates that there’s something wrong either with your Xcode installation or with some configuration within it. The Apple Developer Forums can be helpful here if you run into problems.

Now that you’ve verified that the template runs for you, the first steps you add to this project will let you enter some text into a text view. To make that happen, open the iPhone storyboard, and then drag a text view from the objects library into the storyboard, as shown in Figure 3.6.

Figure 3.6 Adding a text view

Run the app now, and you’ll see your text view with placeholder text. As you see in Figure 3.7, you’ll be able to edit the text in the simulator. (Also note that Retina displays use pixel doubling; on the simulator, this may result in a double-size image.)

Figure 3.7 The text field is ready for use in the simulator.

Now you have an app that you can run; it contains a text field into which you can type text. You’ll want to do something with that text, so, as shown in Figure 3.8, add a button above the text field (you may have to do some rearranging). The reason you may need to add the button above the text field is that on the iPhone, the keyboard may pop up over the button as soon as you tap in the text view if the button is at the bottom of the screen.

Figure 3.8 Adding a button