Pro tip: Build a Today iOS 8 app extension using Xcode 6

 Image: Cory Bohon/TechRepublic

iOS 8 app extensions let you move your app into other parts of iOS, such as taking advantage of the Today view in the Notification Center, sharing views, and custom keyboards. In this article, we'll take you through the process of building a simple extension using the tools in Xcode 6.

In order to start creating an iOS 8 extension, you'll need an Xcode project that is already being built against the iOS 8 SDK. If you have this, you can easily add an extension. This is what we'll be doing to build our extension demo for this article. (Note: For the sake of this demo, we'll show you how to build a Today widget using Objective-C, but the exact same steps can be used if you're using Swift in your projects.)

SEE: Build iOS 8 extensions: A quick how-to resource

Building the extension

Once you're ready to get started, launch Xcode 6 and open your existing application project (or create a new one), and then follow these steps to add an iOS 8 Today extension to your project.

1. Go to File | New | Target.

2. Select iOS | Application Extension | Today Extension, and then click Next (Figure A).

3. Give your extension a unique name that is different from the base application, and ensure that the Project option is set to your currently opened project file, and that the Embed In Application is set to the correct target (your base app) (Figure B).

4. Click Finish.

Figure A

There are multiple extension types that you can choose, but you'll have to choose the ones that will best benefit your base application.

Figure B

When setting up the new target, you need to make sure that the correct Project and Embed In Application is selected.

You'll notice new source files (TodayViewController.h and TodayViewController.m), as well as a new Storyboard to support the interface elements of the Today view widget, added to your project. In addition, if you click your project in the Project Navigator, you'll see the new Extension target that has been added to the project. Using this, you can build out your widget as you would build out any other view in iOS -- with a few exceptions. Let's look at one of those exceptions.

If you look at the implementation file for the Today widget, you'll see that it conforms to the NCWidgetProviding protocol. Using this NCWidgetProviding, you can ensure that your widget remains up to date. The system will occasionally snapshot your widget's view. Whenever this widget becomes visible again, the most recent snapshot will be displayed until the system replaces this view with a live version. This protocol lets you update the widget's state before the snapshot is taken.

In the method -widgetPerformUpdateWithCompletionHandler:, you'll be able to call the completion handler block in the protocol method like this (this code will already be set up for you in TodayViewController.m):

- (void)widgetPerformUpdateWithCompletionHandler:(void (^)(NCUpdateResult))completionHandler { // Perform any setup necessary in order to update the view. completionHandler(NCUpdateResultNewData); }

When returning to the completionHandler, you can pass in various items for NCUpdateResult:

• NCUpdateResultFailed if an error occurred.

• NCUpdateResultNoData if there is no update required to the widget.

• NCUpdateResultNewData if the existing data is stale and needs an update.

In this same method, before calling the completion handler, you will be responsible for updating your view's contents so that when the completion handler is called, the Notification Center can update your widget in the Today view.

Let's hook this up to perform a task. We'll add an IBOutlet, and hook that up to the "Hello World" label that is already added to the Storyboard through this template. So, in the @interface declaration for your TodayViewController, add the following line of code:

@property (nonatomic, weak) IBOutlet UILabel *nameLabel;

Next, update the code in the -widgetPerformUpdateWithCompletionHandler: so that it looks like the following:

- (void)widgetPerformUpdateWithCompletionHandler:(void (^)(NCUpdateResult))completionHandler { // Perform any setup necessary in order to update the view. self.nameLabel.text = @"Cory"; //replace with your name completionHandler(NCUpdateResultNewData); }

- (void)widgetPerformUpdateWithCompletionHandler:(void (^)(NCUpdateResult))completionHandler { // Perform any setup necessary in order to update the view. self.nameLabel.text = @"Cory"; //replace with your name completionHandler(NCUpdateResultNewData); }

Finally, open the MainInterface.storyboard file in the extension project folder, select your Today View Controller in the Scene sidebar, and then show the Connections Inspector. Drag and drop a line between the nameLabel Outlet that we created and the "Hello World" UILabel (Figure C).

Figure C

Be sure to hook up the elements in Interface Builder; otherwise, the results won't appear when the widget is displayed in the Today view.

We can see our changes take effect by running our application in the simulator.

Running and displaying the extension

Build and run your base application in the Simulator or device (if you're running on the device, remember that you'll need to sign your base app and extension with a valid provisioning profile in order for it to run). When the application launches, perform these steps to add the new widget:

1. Swipe down from the top of the screen to open the Notification Center.

2. Tap the Today view.

3. Scroll down to the bottom, and tap the Edit button.

4. Tap the + button to the left of the new widget to add (Figure D).

5. Exit editing mode.

Your widget now appears inside of the Today view under its own heading (Figure E), and the view that is generated displays your name, as we added in code in the TodayViewController.m file.

Figure D

Add your widget to the Today view by tapping the + button beside the application name.

Figure E

After a few seconds of being on the screen, Notification Center will call your code through the protocol and ask the view to be updated.

Where to go from here

Apple has provided a lot of documentation and other resources for extensions in iOS 8. Here are some of the key resources that will have you building extensions in no time.

• App Extensions Overview

• App Extensions Programming Guide

• WWDC '14 Video: Creating Extensions for iOS and OS X, Part 1

• WWDC '14 Video: Creating Extensions for iOS and OS X, Part 2

Automatically subscribe to TechRepublic's Week in Review newsletter.