Let’s imagine this scenario: you’ve got a successful app with a great number of daily users and 100% crash-free rate. You are happy and your life is amazing. But at some point you start seeing negative reviews coming to the App Store saying that it constantly crashes. Checking Fabric doesn’t help – no new crashes have appeared. What could it be then?

The answer is OOM (Out of Memory) termination.

As you use RAM on an end user’s device, the operating system can decide to reclaim that memory for other processes and terminate your app. We call this an Out of Memory termination. There might be various reasons for that:

• retain cycles;
• race conditions;
• abandoned threads;
• deadlocks;
• layout feedback loop.

There are a lot of solutions provided by Apple to debug such kind of issues:

• Allocations and Leaks instruments for resolving retain cycles and other types of leaks
• Memory Debugger which has been introduced in Xcode 8 and replaces some functionality from Allocations and Leaks instruments
• Thread Sanitizers help you find race conditions, abandoned threads or deadlocks

Layout Feedback Loop

We are going to take a look into layout feedback loop. It is not a very frequent type of issue, but once you encountered it, it could give you a lot of headache.

Layout feedback loops occur when your views are running their layout code, but part way through something causes them to start their layout pass again. This might be the result of one view changing the size of one of its superviews, or perhaps because you have an ambiguous layout. Either way, this problem manifests itself as your CPU maxing out and RAM usage steadily marching upwards, all because your views are running their layout code again and again without ever returning.

– Paul Hudson from HackingWithSwift

Luckily for us, in WWDC16 Apple spent the whole 15 minutes(!) introducing “Layout Feedback Loop Debugger” which helps identify the moment when a loop happens during debugging. This is just a symbolic breakpoint and the way it works is as simple as it gets: it counts the amount of times layoutSubviews() method on each view has been called in a single run loop iteration. Once it exceeds a certain threshold (let’s say, 100), the app is going to stop at this breakpoint and print a nice log that helps you to find the root cause. Here is a nice article shortly describing how to work with this debugger.

This works perfectly if you can reproduce the issue. But what if you have dozens of screens, hundreds of views but your App Store reviews only say: “This app sucks, always crashing, never use it again!!!” ? You wish you could bring all these people to your office and set up Layout Feedback Loop Debugger for them. While the first part is not entirely achievable due to GDPR, you can try to replicate UIViewLayoutFeedbackLoopDebuggingThreshold in production code.

Let’s recall how this breakpoint works: it counts invocations of layoutSubviews() and sends an event when a certain threshold was exceeded in a single runloop iteration. Sounds easy, huh?

class TrackableView: UIView {
    var counter: Int = 0

    override func layoutSubviews() {
        super.layoutSubviews()

        counter += 1;
        if (counter == 100) {
            YourAnalyticsFramework.event(name: "loop")
        }
    }
}

This code works quite well for your view. But now you want to implement it on another views. You can, of course, create a subclass of UIView, implement it there and then inherit all the views in your project from it. And then do the same for UITableView, UIScrollView, UIStackView, and etc…

You wish you could just inject this logic into whatever class you wanted without writing tons of duplicated code. And this is exactly what runtime programming allows you to do.

We are going to do the same thing – create a subclass, override the layoutSubviews() method and count its invocations. The only difference is that all of this will be done at runtime instead of creating duplicated classes in your project.

Let’s start simple – we’ll create our custom subclass and will change the original view’s class to that new subclass:

struct LayoutLoopHunter {

    struct RuntimeConstants {
        static let Prefix = “runtime”
    }

    static func setUp(for view: UIView, threshold: Int = 100, onLoop: @escaping () -> ()) {
        // We create the name for our new class based on the prefix for our feature and the original class name
        let classFullName = “\(RuntimeConstants.Prefix)_\(String(describing: view.self))”
        let originalClass = type(of: view)

        if let trackableClass = objc_allocateClassPair(originalClass, classFullName, 0) {
            // This class hasn’t been created during the current runtime session
            // We need to register our class and swap is with the original view’s class
            objc_registerClassPair(trackableClass)
            object_setClass(view, trackableClass)
        } else if let trackableClass = NSClassFromString(classFullName) {
            // We’ve previously allocated a class with the same name in this runtime session
            // We can get it from our raw string and swap with our view the same way
            object_setClass(view, trackableClass)
        }
    }
}

objc_allocateClassPair()’s documentation tells us when this method fails:

The new class, or Nil if the class could not be created (for example, the desired name is already in use)”.

This means that you cannot have 2 classes with the same name. Our strategy is to have a single created-at-runtime class for a single view class. That’s why we form the name for the new class by prefixing the original class name.

Now let’s add a counter to our subclass. Theoretically there are two ways you can do this:

1. Add a property which holds your counter.
2. Create an associated object for this class.

But in face, only one way is valid. You can think of a property as something that is stored in the memory that has been allocated for your class whereas an associated object will be stored in a completely different place. Since the memory that was allocated for an existing object is fixed, the newly added property on our custom subclass is going to “steal” it from some other resource. It can lead to unexpected behaviors and hard-to-debug crashes (check here for more info). But in case of using associated objects, they will be just stored in a hash table created during runtime, which is totally safe:

static var CounterKey = "_counter"

...

objc_setAssociatedObject(trackableClass, &RuntimeConstants.CounterKey, 0, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)

Our new subclass is created, the counter is set to 0. Next, let’s implement the new layoutSubviews() method and add it to our class:

let layoutSubviews: @convention(block) (Any?) -> () = { nullableSelf in
    guard let _self = nullableSelf else { return }

    if let counter = objc_getAssociatedObject(_self, &RuntimeConstants.CounterKey) as? Int {
        if counter == threshold {
            onLoop()
        }

        objc_setAssociatedObject(trackableClass, &RuntimeConstants.CounterKey, counter+1, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
    }
}
let implementation = imp_implementationWithBlock(layoutSubviews)
class_addMethod(trackableClass, #selector(originalClass.layoutSubviews), implementation, "v@:")

To understand what is actually going on above, let’s take a look at this struct from <objc/runtime.h>:

struct objc_method {
    SEL method_name;
    char *method_types;
    IMP method_imp;
}

Even though we don’t use this struct directly in Swift anymore, it explains pretty clearly what a method actually consists of:

• Implementation, which is the exact function going to be executed when your method is called. It always has the receiver and message selector as its first two parameters.
• Method types string contains the signature of your method. You can read more about its formatting here, but in our case the string we need to specify is `”v@:”`. `v` stands for `void` as our return type, while `@` and `:` stand for the receiver and message selector respectively.
• Selector is a key by which your method implementation will be looked up during runtime.

You can imagine the witness table (it’s also called dispatch table in other programming languages) as a simple dictionary data structure. The selector, then, would be your key and the implementation — the value. What we are doing in this line:

class_addMethod(trackableClass, #selector(originalClass.layoutSubviews), implementation, "v@:")

is just assigning a new value for the key which corresponds to the layoutSubviews() method.

Straightforward as it gets. We get the counter, increase it by one. In case it exceeds our threshold, we send the analytics event with the name of the class and any payload we want.

Let’s recall how we’ve implemented and used the key for our associated object:

static var CounterKey = “_counter”

...

objc_setAssociatedObject(trackableClass, &RuntimeConstants.CounterKey, counter+1, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)

Why did we use var for our static key property for the counter variable and passed it everywhere by reference? The answer is hidden in basics of Swift language – Strings, like all the other value types, are passed by value. So, when you pass it to the closure, the string is being copied to a different address which would result in a completely different key in the associated objects table. The ampersand always ensures that the same address is given as value for the key parameter. Try the following code:

func printAddress(_ string: UnsafeRawPointer) {
    print("\(string)")
}

let str = "test"

printAddress(str)
printAddress(str)
let closure = {
    printAddress(str)
    printAddress(str)
}
closure()
// The addresses for last two function calls will always be different

Passing the key by reference is always a good idea because sometimes, even if you are not using a closure, the address of your variable can still be changed due to memory management. For our example, if you run the above code for certain amount of times, you may be able to see different addresses even for the first two calls of printAddress().

Let’s go back to our runtime magic. There is an important thing which we haven’t yet done in our new layoutSubviews() implementation. The thing that we normally do every time we override a method from an ancestor class – call the superclass implementation. The documentation of layoutSubviews() says:

The default implementation of this method does nothing on iOS 5.1 and earlier. Otherwise, the default implementation uses any constraints you have set to determine the size and position of any subviews.

For avoiding any unexpected layout behaviour, we have to call the superclass’s implementation. This will not be that straightforward as it usually is:

let selector = #selector(originalClass.layoutSubviews)
let originalImpl = class_getMethodImplementation(originalClass, selector)

// @convention(c) tells Swift this is a bare function pointer (with no context object)
// All Obj-C method functions have the receiver and message as their first two parameters
// Therefore this denotes a method of type `() -> Void`, which matches up with `layoutSubviews`
typealias ObjCVoidVoidFn = @convention(c) (Any, Selector) -> Void
let originalLayoutSubviews = unsafeBitCast(originalImpl, to: ObjCVoidVoidFn.self)
originalLayoutSubviews(view, selector)

What is actually going on here is that instead of the usual way to call a method (i.e. perform the selector which is going to look up in the witness table for the implementation), we are retrieving the needed implementation ourselves and calling it directly from our code.

Let’s see our implementation so far:

static func setUp(for view: UIView, threshold: Int = 100, onLoop: @escaping () -> ()) {
    // We create the name for our new class based on the prefix for our feature and the original class name
    let classFullName = “\(RuntimeConstants.Prefix)_\(String(describing: view.self))”
    let originalClass = type(of: view)

    if let trackableClass = objc_allocateClassPair(originalClass, classFullName, 0) {
        // This class hasn’t been created during the current runtime session
        // We need to register our class and swap is with the original view’s class
        objc_registerClassPair(trackableClass)
        object_setClass(view, trackableClass)

        // Now we can create the associated object
        objc_setAssociatedObject(view, &RuntimeConstants.CounterKey, 0, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)

        // Adding our layoutSubviews implementation
        let layoutSubviews: @convention(block) (Any?) -> () = { nullableSelf in
            guard let _self = nullableSelf else { return }

            let selector = #selector(originalClass.layoutSubviews)
            let originalImpl = class_getMethodImplementation(originalClass, selector)

            // @convention(c) tells Swift this is a bare function pointer (with no context object)
            // All Obj-C method functions have the receiver and message as their first two parameters
            // Therefore this denotes a method of type `() -> Void`, which matches up with `layoutSubviews`
            typealias ObjCVoidVoidFn = @convention(c) (Any, Selector) -> Void
            let originalLayoutSubviews = unsafeBitCast(originalImpl, to: ObjCVoidVoidFn.self)
            originalLayoutSubviews(view, selector)

            if let counter = objc_getAssociatedObject(_self, &RuntimeConstants.CounterKey) as? Int {
                if counter == threshold {
                    onLoop()
                }

                objc_setAssociatedObject(view, &RuntimeConstants.CounterKey, counter+1, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
            }
        }
        let implementation = imp_implementationWithBlock(layoutSubviews)
        class_addMethod(trackableClass, #selector(originalClass.layoutSubviews), implementation, “v@:“)
    } else if let trackableClass = NSClassFromString(classFullName) {
        // We’ve previously allocated a class with the same name in this runtime session
        // We can get it from our raw string and swap with our view the same way
        object_setClass(view, trackableClass)
    }
}

Let’s test it by creating a simulated layout loop for a view and setting our counter for it:

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        LayoutLoopHunter.setUp(for: view) {
            print("Hello, world")
        }
    }

    override func viewDidLayoutSubviews() {
        super.viewDidLayoutSubviews()
        view.setNeedsLayout() // loop creation
    }
}

Did we miss something? Let’s recall again how the UIViewLayoutFeedbackLoopDebuggingThreshold breakpoint works:

Defines how many times a view must layout its subviews in a single run loop before it is considered to be a feedback loop.

We never took into account the “single run loop” condition. If our view stays in the screen for a significant amount of time and is regularly being laid out over and over again, sooner or later our counter will exceed the threshold. But this is not because of a memory issue.

How do we solve this? Simply by resetting the counter on every run loop iteration. For doing so, we can create a DispatchWorkItem which resets our counter and pass it asynchronously on the main queue. This way, it will be called when the run loop enters the main thread next time:

static var ResetWorkItemKey = “_resetWorkItem”

...

if let previousResetWorkItem = objc_getAssociatedObject(view, &RuntimeConstants.ResetWorkItemKey) as? DispatchWorkItem {
    previousResetWorkItem.cancel()
}
let currentResetWorkItem = DispatchWorkItem { [weak view] in
    guard let strongView = view else { return }
    objc_setAssociatedObject(strongView, &RuntimeConstants.CounterKey, 0, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
}
DispatchQueue.main.async(execute: currentResetWorkItem)
objc_setAssociatedObject(view, &RuntimeConstants.ResetWorkItemKey, currentResetWorkItem, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)

The final code:

struct LayoutLoopHunter {

    struct RuntimeConstants {
        static let Prefix = “runtime”

        // Associated objects keys
        static var CounterKey = “_counter”
        static var ResetWorkItemKey = “_resetWorkItem”
    }

    static func setUp(for view: UIView, threshold: Int = 100, onLoop: @escaping () -> ()) {
        // We create the name for our new class based on the prefix for our feature and the original class name
        let classFullName = “\(RuntimeConstants.Prefix)_\(String(describing: view.self))”
        let originalClass = type(of: view)

        if let trackableClass = objc_allocateClassPair(originalClass, classFullName, 0) {
            // This class hasn’t been created during the current runtime session
            // We need to register our class and swap is with the original view’s class
            objc_registerClassPair(trackableClass)
            object_setClass(view, trackableClass)

            // Now we can create the associated object
            objc_setAssociatedObject(view, &RuntimeConstants.CounterKey, 0, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)

            // Adding our layoutSubviews implementation
            let layoutSubviews: @convention(block) (Any?) -> () = { nullableSelf in
                guard let _self = nullableSelf else { return }

                let selector = #selector(originalClass.layoutSubviews)
                let originalImpl = class_getMethodImplementation(originalClass, selector)

                // @convention(c) tells Swift this is a bare function pointer (with no context object)
                // All Obj-C method functions have the receiver and message as their first two parameters
                // Therefore this denotes a method of type `() -> Void`, which matches up with `layoutSubviews`
                typealias ObjCVoidVoidFn = @convention(c) (Any, Selector) -> Void
                let originalLayoutSubviews = unsafeBitCast(originalImpl, to: ObjCVoidVoidFn.self)
                originalLayoutSubviews(view, selector)

                if let counter = objc_getAssociatedObject(_self, &RuntimeConstants.CounterKey) as? Int {
                    if counter == threshold {
                        onLoop()
                    }

                    objc_setAssociatedObject(view, &RuntimeConstants.CounterKey, counter+1, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
                }

                // Dispatch work item for reseting the counter on every new run loop iteration
                if let previousResetWorkItem = objc_getAssociatedObject(view, &RuntimeConstants.ResetWorkItemKey) as? DispatchWorkItem {
                    previousResetWorkItem.cancel()
                }
                let counterResetWorkItem = DispatchWorkItem { [weak view] in
                    guard let strongView = view else { return }
                    objc_setAssociatedObject(strongView, &RuntimeConstants.CounterKey, 0, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
                }
                DispatchQueue.main.async(execute: counterResetWorkItem)
                objc_setAssociatedObject(view, &RuntimeConstants.ResetWorkItemKey, counterResetWorkItem, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
            }
            let implementation = imp_implementationWithBlock(layoutSubviews)
            class_addMethod(trackableClass, #selector(originalClass.layoutSubviews), implementation, “v@:“)
        } else if let trackableClass = NSClassFromString(classFullName) {
            // We’ve previously allocated a class with the same name in this runtime session
            // We can get it from our raw string and swap with our view the same way
            object_setClass(view, trackableClass)
        }
    }
}

Conclusion

That’s it! Now you can set up analytics events for all your suspicious views, release the app and find out where exactly the issue occurs. You can narrow it down to a particular view and resolve the issue with the help of your users without them even knowing about this.

One last thing to mention is that with great power comes great responsibility. Runtime programming is very error-prone so it’s very easy to introduce another critical issue for your app without knowing. That’s why it’s always recommended to wrap all the dangerous code in your app in some kind of killswitch which you can trigger from the backend and disable the feature when you see that it’s causing issues. Here is a nice article about Feature Flags from Firebase.

The full code is available in this GitHub repository and also being distributed via CocoaPods for tracking Layout Loops in your projects.

P.S. I want to say special thanks to Aleksandr Gusev for his help with reviewing and giving more ideas for this article.

Understanding CocoaPods, a dependency manager for Swift and Objective-C projects, is a critical skill every iOS developer should have. If you have no experience with CocoaPods, this short post is written for you. We’re going to take a look at what CocoaPods is, why you should start using it, and how to setup a project with cocoa pods installed!

While most of our tutorials are very detailed, this tutorial is much shorter than a traditional article and only intended to get you off the ground with Cocoapods.

What is CocoaPods?

CocoaPods is a dependency manager for Swift and Objective-C projects. If you’ve ever used Node.js, Ruby on Rails, Python, etc., you’re probably familiar with the concept of a dependency manager. If not, that’s okay! A dependency manger is a tool that manages a set of frameworks and packages for developers. So instead of having to manually import files via drop and drop, a dependency manager like CocoaPods takes care of all that for you.

Consider this sample scenario: You’re working on an app and need to make use of a third party framework like Firebase.

Firebase relies on several other frameworks to work. In order to use it, you have to import all the frameworks Firebase requires, plus Firebase itself. This is a tedious process if you have to do it manually.

Let’s take this example even further. If Firebase ships an update to their SDK, you’ll have to redownload the entire SDK and replace it manually.

This is why CocoaPods has its place. It simplifies the whole process by automatically finding and installing the frameworks, or dependencies require. You will understand the power of CocoaPods in a minute.

Setting Up CocoaPods on Your Mac

Setting up Cocoapods is simple and straightforward, and a very rewarding process. To install Cocoapods, navigate to the terminal and type the following commands:

sudo gem install cocoapods

This line of command installs the CocoaPods gem on your system. CocoaPods was built with Ruby, so it relies on the default Ruby available on OS X for installation. If you’re familiar with Ruby, gems in Ruby are similar to pods in CocoaPods.

You may be prompted to enter your root password and then hit enter. Note that the password will not appear on screen as terminal does not display passwords.

It’ll take several minutes to finish the installation. Just be patient, grab a cup of coffee, and wait the whole process to complete.

Using CocoaPods for Xcode Projects

Once you have CocoaPods installed on your Mac, let’s see how to use it. We will create a sample project and demonstrate how you can install the Firebase framework in the project using CocoaPods.

First, create a new Xcode project and name it CocoapodsTest. Close the project and back in terminal. Use the cd (change directory) command to navigate to your new Xcode project. Assuming you save the project under Desktop, here is the command:

cd ~/Desktop/CocoapodsTest

Next, we need to create what’s called a Podfile. A Podfile is a file that lives in the root of your project and is responsible for keeping track of all the pods you want to install. When you ask CocoaPods to install any pods or updates to your existing pods, CocoaPods will look to the Podfile for instructions.

To create a Podfile, simply type the following command:

pod init

CocoaPod then generates the Podfile like this:

# Uncomment this line to define a global platform for your project
# platform :ios, '9.0'

target 'CocoapodsTest' do
  # Comment this line if you're not using Swift and don't want to use dynamic frameworks
  use_frameworks!

  # Pods for CocoapodsTest

end

That’s the basic structure of a Podfile. All you need to do is edit the file and specify your required pods. We are going to use a text editor called Vim to edit the file. Vim is a program built into every Mac that allows developers to edit content within terminal. That said, you’re free to use other text editors like Atom.

Type the following command to open the file with vim:

vim Podfile

Suppose you’re going to use Firebase in your Xcode project. To do so, edit the file content like this to configure the Firebase pod.

# Uncomment this line to define a global platform for your project
# platform :ios, '9.0'

target 'CocoapodsTest' do
  # Comment this line if you're not using Swift and don't want to use dynamic frameworks
  use_frameworks!

  # Pods for CocoapodsTest
  pod 'Firebase'
end

That’s it. To exit vim, hit the escape key and then type:

:wq

This means write and quit, which will close vim with your changes saved.

Before we move to the last step, let us go through the above configuration:

• The Podfile describes the dependencies of the targets of your Xcode project. Therefore, we have to specify the target, which is CocoapodsTest for this demo.
• The use_frameworks option tells CocoaPods to use frameworks instead of static libraries. This is required for Swift projects.
• The line that we have just inserted (pod 'Firebase') lets CocoaPods know that we need to use the Firebase pod. You may wonder how do you know the pod name. Normally you can look it up in the documentation of the pod or simply search it on cocoapods.org.

Now that you should have a better understanding of the pod file, type the following command in the terminal to complete the last step:

pod install

Cocoapods will now install the Firebase pod! After downloading the Firebase pods, it creates a workspace file named CocoapodsTest.xcworkspace. This workspace file bundles your original Xcode project, the Firebase library, and its dependencies.

So from now on, you have to use CocoapodsTest.xcworkspace instead of CocoapodsTest.xcodeproj.

Opening the Xcode Workspace

If you open CocoapodsTest.xcworkspace with Xcode, you should find both the CocoapodsTest project and the Pod project, which contains the Firebase library.

Now all there’s left to do is use the Firebase pod. Let’s navigate back to Xcode and inside the IDE, go to ViewController.swift. At the top, type:

import Firebase

And look at that! You are up and running with CocoaPods!

Wrapping Up

CocoaPods is an incredibly simple tool that every iOS developer should have in his/her backpocket. I hope this tutorial is clear cut and easy to follow. If you have any thoughts or questions, please leave them in the comment.

Editor’s note: This is a guest post contributed by Eugene Trapeznikov. Imagine you’ve completed the development and testing of your app, you’re now ready to submit it for production release. The problem is that some of the web service URLs are pointing to the testing servers, and the API keys are configured for the test environment. Before submitting the app for Apple’s review, you’ll need to modify all these API keys and URLs to fit for production. This sounds good, right? But instead of changing the values back and forth between the development and production environment, is there a better approach to handle both the development and production builds? This is exactly what Eugene is going to discuss with you.

Enter Eugene’s tutorial.

For starters, some of you may be wondering why you should use two separate databases and environments while developing your app. The reason is because as you continue to build new features or develop your app, you want to separate the development version from the existing public production app. Standard software development practice is to use different environments for the different versions of the software, and in our case, iPhone apps. The development version of an app typically uses a different database (or other systems such as analytics) from the production environment. This is one reason why we should use separate servers and databases for different environments. Developers commonly use dummy images or data during testing. In testing or development environments, it’s not uncommon for one to use test data such as “test comment”, “argharghargh” and “one more test comment”. Obviously, you don’t want your real users to see these kind of messages. In the case of if your app using an analytics system, you may even send thousands of events during the testing stage. Again, you don’t want to mix the test data with the production data in the same database. This is why its always recommended to separate the development and production environments.

While using two separate environments, your app needs to have a way to find out which environment it should connect to. One popular method is to define a global variable in your main app delegate, which will initialize your app to development or production mode.

enum environmentType {
    case development, production
}

let environment:environmentType = .production

switch environment {
case .development:
    // set web service URL to development
    // set API keys to development
    print("It's for development")
case .production:
    // set web service URL to production
    // set API keys to production
    print("It's for production")
}

This approach requires you to change the global variable every time you want to switch from one environment to another. While this method maybe quick and convenient, it comes with some major limitations. First, because we are using a single bundle ID for both the development and production environments, you cannot install both app versions on a single device. This becomes inconvenient when you want to test the development version of the app, but still use the production version of the app on the same device. Also, this approach allows for an opportunity to accidentally ship the development app to the store. If you forget to change that single global variable, you will be shipping the wrong app to your users. I remember once I forgot to change the global variable before submitting my app to the App Store, and users got the development version of the app. That was awful.

In this article I will show you a better approach to differentiate between the development and production builds. Specifically, we will create a development target in XCode. This method is suitable for both new and existing large projects, so you can use one of your existing apps to follow along in this tutorial.

By applying this approach, the production and development versions of the app will have the same base code, but can have different icons, bundle IDs and point to separate databases. The distribution and submission processes will be very straightforward. Most importantly, your testers and managers will be able to install both versions of the app on the same device, so they fully understand which version they’re trying out.

How to Create a New Target

So how can you create a development target in Xcode? I will walk you through the procedure step-by-step with my template project “todo”. You can use your own project and follow the procedures:

1. Go to project’s settings in the Project Navigator panel. Under the Targets sections, right click the existing target and select Duplicate to copy your existing target.

2. Xcode will ask you if your new target is for iPad development. For this tutorial, we just select “Duplicate Only”.

3. Now that we have a new target and a new build scheme with the name todo copy. Let’s rename it so it is easier to understand.

• Select the new target in the TARGETS list. Press Enter to edit the text and put a more appropriate name. I prefer “todo Dev”. You’re free to choose whatever name you like.
• Next, go to “Manage Schemes…”, select the new scheme you created in step 1 and press “Enter”. Make the scheme name the same as the new target name (which is the one you choose for the new target.)

4. Steps 4 is optional, but highly recommended. If you want to make it easy and dummy-proof to distinguish between the development and production builds, you should use separate icons and launch screens for each version. This will make it obvious for your testers to know which app they are using, and hopefully prevent you from shipping a development version. 🙂

Go to Assets.xcassets and add a new icon. Right click icon > App Icons & Launch Images > New iOS App Icon. Rename the new icon to “AppIcon-Dev” and add your own images.

5. Now go back to project settings, select your development target and change the bundle identifier. Say, you can simply append “Dev” to the original ID. If you performed step 4, make sure you change the app icon setting to the one created in the previous step.

6. Xcode automatically added a plist file for your target (e.g. todo copy-Info.plist). You can find it at the root folder of your project. Rename it from “copy” to “Dev”, and place it right below your original plist file. Here, it will be easier for you to manage the file.

7. Now open “Build Settings” of your development target, scroll to “Packaging”, and change the value to the development plist file (e.g. todo Dev.plist).

8. Lastly, we’ll configure a preprocessing macro/compiler flag for both production and development targets. So later we can use the flag in our code to detect which version the app is currently running.

For Objective-C projects, go to Build Settings and scroll to Apple LLVM 7.0 - Preprocessing. Expand Preprocessor Macros and add a variable to both Debug and Release fields. For the development target (i.e. todo Dev), set the value to DEVELOPMENT=1. On the other hand, set the value to DEVELOPMENT=0 to indicate a production version.

For Swift project, the compiler no longer supports preprocessor directives. Instead, it uses compile-time attributes and build configurations. To add a flag to indicate a development build, select the development target. Go to Build Settings and scroll down to the Swift Compiler - Custom Flags section. Set the value to -DDEVELOPMENT to indicate the target as a development build.

Now that you have created and configured the development target, what’s next?

Using the Target and Macro

With the macro DEV_VERSION configured, we can utilize it in the code and perform dynamic compilation for your project. Here is a simple example:

Objective-C:

#if DEVELOPMENT
#define SERVER_URL @"http://dev.server.com/api/"
#define API_TOKEN @"DI2023409jf90ew"
#else
#define SERVER_URL @"http://prod.server.com/api/"
#define API_TOKEN @"71a629j0f090232"
#endif

In Objective-C, you can use #if to check the condition of DEVELOPMENT, and set up the URLs/API keys accordingly.

Swift:

#if DEVELOPMENT
let SERVER_URL = "http://dev.server.com/api/"
let API_TOKEN = "DI2023409jf90ew"
#else
let SERVER_URL = "http://prod.server.com/api/"
let API_TOKEN = "71a629j0f090232"
#endif

In Swift, you can still use #if to evaluate the build configurations for dynamic compilations. However, instead of using #define to define a primitive constant, we simply use let to define a global constant in Swift.

Now when you select the “todo Dev” scheme and run the project, you’ll create the development build automatically with the server configuration set to the development environment. You’re now ready to upload the development build to TestFlight or HockeyApp for your testers and managers to test out.

Later if you need to create a production build, you can simply select the “todo” scheme. No code change is required.

Some Notes on Managing Multiple Targets

1. When you add new files to the project, don’t forget to select both targets to keep your code in sync in both builds.

2. In case you’re using Cocoapods, don’t forget to add the new target to your podfile. You can use link_with to specify multiple targets. You can further consult the Cocoapods documentation for details. Your podfile should look something like this:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '7.0'
workspace 'todo'
link_with 'todo', 'todo Dev'
pod 'Mixpanel'
pod 'AFNetworking'

3. If you use continuous integration system such as Travis CI or Jenkins, don’t forget to configure to build and deliver both targets.

What do you think about this tutorial? How do you manage your development and production builds? Leave me comment and share your thought.

Editor’s note: This is a guest post by Gregory Tareyev, a co-founder and iOS developer of Chill (iamchill.co), the first wearable communication tool that lets you interact with your friends with a tap. In this tutorial, Gregory will share his experience on Apple Watch development and show you how to build a simple weather app using a third-party API and WatchKit. We have written a couple of tutorials about WatchKit. All of them are in Swift. Some readers mentioned if we can provide a tutorial in Objective-C. So here it is.

Enter Gregory’s tutorial.

Hello everybody! My name is Gregory Tareyev (tareyev.ru for any contacts). I am a co-founder and iOS developer of Chill (iamchill.co), the first wearable communication tool that finally makes sense. Recently we had a great experience on launching Chill on Product Hunt which gave us a lot of visibility in the community and attracted major tech blogs to cover the release. We are also discussing our involvement with a few accelerators and considering the best one. We worked really hard to build the app, but I assure you that everybody can do something like that.

Here, I want to share some experience on the app development for Apple Watch. It’ll be easy and fun.

To warm up your interest, I want to explain why it is so important to learn how to develop on wearable devices:

1. The market is still small = you can get a bigger market share as a first-time mover
2. The market is going to grow tremendously = the product will grow along with the market

In this tutorial, we will build a simple weather app for Apple Watch. We will go through a couple of things:

• How to parse JSON in WatchKit app
• How to use OpenWeatherMap API (once you understand it, you should be able to use any JSON-based APIs)

So, let’s get started!

The Demo App

The demo app is a very simple weather app. We’re going to use OpenWeatherMap’s API to get the weather information for a particular city (e.g. London). Here is the sample screen of the final app:

Creating the Xcode Project

First, create a Single View Application and configure the project option like below. Yes, we’re going to write in Objective-C. I think it’s still important, so let’s not forget this wonderful language.

To create a Watch app, go up to the Xcode menu and select Editor > Add Target. Choose Apple Watch > WatchKit App. By using the WatchKit App template, it will generate everything you need to build a Watch app.

Deselect “Include Notification Scene” and leave other details as they are and then press finish.

Now you will get a warning to ask if you want to activate the new scheme. Just accept it. You’ll then see two new folders: WatchKit Extension and WatchKit App.

Designing the UI

Next, we will start to design the user interface of the Watch app. To do that, you have to navigate to “SimpleWeather WatchKit App” and select the Interface.Storyboard File.

First, drag a label from the Object library into the Interface Controller. Name it “Weather in London”. You may need to decrease the font size. Then drag an image, followed by a button into the Interface Controller. You will see that the image and button are layout automatically and stacked vertically. Change the title of the button to “Update” and color to green. Resize the image so that it looks like the screen below:

The label is used to show the weather type, while the image shows an illustration of the weather type. The Update button is the only element that interacts with the user, and is used for updating the weather information.

Interface Builder lets you view the design on different version of Apple Watch. By default, the Interface Controller is set to Any Screen Size. You can click the “Any Screen Size” button at the bottom of the Interface Builder and switch to Apple Watch 38/42mm. If you switch to Apple Watch 42mm, you will find that the image is not perfectly fit. Just resize the image and make sure everything is layout correctly. As you change the size of the image, Xcode automatically adds layout specialisation, just for Apple Watch 42mm.

Understanding JSON and OpenWeatherMap’s API

As mentioned, we use OpenWeatherMap’s API to get the weather data. To understand how it works, open this link: http://api.openweathermap.org/data/2.5/weather?q=London,uk. Copy the resulting text and paste it into http://json.parser.online.fr. You’ll see the JSON data, presented in a structured way. Here, what we are interested in is the weather type, i.e in the “main” key of the “weather” dictionary. This is the information we’ll display it on screen.

Now let’s see how we can parse the JSON data and present the weather information in the app.

To begin, open the Assistant editor. Control-drag from the label to your code in InterfaceController.h file. Name the outlet “weatherType” like this:

Repeat the same step for the image. Name the outlet “weatherImage” instead. When connecting the update button, instead of selecting Outlet, select Action and name it “updateAction”.

Let’s add logic in the updateAction method of the InterfaceController.m file:

- (IBAction)updateAction
{
    NSURLRequest* requestForWeatherData = [NSURLRequest requestWithURL:[NSURL URLWithString:@"http://api.openweathermap.org/data/2.5/weather?q=London,uk"]];
    NSURLResponse* response = nil;
    NSError* error = nil; //do it always

    NSData* data = [NSURLConnection sendSynchronousRequest:requestForWeatherData returningResponse:&response error:&error]; //for saving all of received data in non-serialized view
    
    NSMutableDictionary *allData = [ NSJSONSerialization JSONObjectWithData:data options:NSJSONReadingMutableContainers error:&error]; //data in serialized view
    NSString* currentWeather = nil;
    
    NSArray* weather = allData[@"weather"];
    
    for (NSDictionary* weatherDictionary in weather)
    {
        currentWeather = weatherDictionary[@"main"];
    }
}

In this method, we use NSURLConnection to make a synchronous request to the OpenWeatherMap API. You can use NSJSONSerialization to convert JSON to Foundation objects (e.g. NSDictionary). We parse the data and save the weather type in the “currentWeather” variable.

Next, we need to update the label and image. We can write something like this:

The code is not very pretty, isn’t it?

Instead of hardcoding the weather type, create a method like below, it’ll make your code more flexible.

-(void)setImageAndTextWithWeather:(NSString* ) weatherName
{
     // Use the weather type as the weather image name. For example, if the weather name is "Rainy", the image name is set to "rainy.jpg". 
     
     // Set the weather type to the given weather name
}

Awesome! Now let’s turn the method into real code:

-(void)setImageAndTextWithWeather:(NSString* ) weatherName
{
        NSString* weatherNameWithoutSpaces = [weatherName stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceAndNewlineCharacterSet]]; //delete potential spaces in JSON array
        [_weatherImage setImageNamed:[weatherNameWithoutSpaces stringByAppendingString:@".jpg"]];
    
    NSMutableAttributedString *customString = [[NSMutableAttributedString alloc] initWithString:weatherNameWithoutSpaces];
    [customString addAttribute:NSFontAttributeName
                         value:[UIFont systemFontOfSize:18] 
                  range:NSMakeRange(0, [weatherNameWithoutSpaces length])]; //Making text more readable by creating a custom string

    [_weatherType setAttributedText:customString];
}

Finally, add this line to the end of the updateAction method:

[self setImageAndTextWithWeather:currentWeather];

Adding Images to the Asset Catalog

One last thing before running the app. Download this image pack, unzip it and add all the images to Images.xcassets under the SimpleWeather WatchKit App folder.

You are free to add more images with appropriate weather names. The app will work properly without any code changes.

Test the App

That’s it! Now You can build and run the app in the Apple Watch simulator. To run the app, select the “WatchKitDemo WatchKit App” scheme and choose your preferable device. Then click the run button to test the Watch app. Optionally, you can change the display size of the watch simulator by selecting Hardware > External Displays > Apple Watch – 38mm.

Great! You’ve built a weather app for Apple Watch. What do you think about tutorial? Leave me comment and share your thought. I love to hear your feedback.

For your reference, you can download the final project here.

This is a guest post by Gregory Tareyev, a co-founder and iOS developer of Chill (iamchill.co).

During the development of an application there are various steps involved in the whole process. Some of them are the definition of its specifications, the creation of graphics, the implementation, and the testing phase following the implementation. Writing the code maybe consists of the most important part, as this brings the application to life, but further than that, equally important is the proper documentation of the code. No matter how well-written the code is, if there’s lack of a good documentation accompanying it, future troubles it’s possible to arise. Unfortunately, many developers overlook or ignore the importance of the code documentation, and that’s really bad, as good software is not just good code. It’s more than that.

When talking about documentation, apparently I don’t mean just to add a few lines of comments somewhere in the implementation files. It’s definitely more than that. But first, why is it such a big deal to document the code? Well, there are two cases: Whether you’re working on your own, or you are a part of a team. Let’s see in short each one.

If you are the only developer of the under-development application, then it’s reasonable to believe that writing code documentation costs in time, so skipping doing that will bring you right into your target much sooner. Additionally, it’s easy to convince yourself that as you’re the sole developer there’s really no need to do that. But trust me, that’s the worst decision you might make during the app creation period. Suppose that you successfully implement the application, you sell it either on the app store or in a client of yours, and then you put it in the shelf. And after six months or so, you must create a new version of it by adding new features. When you open the project again and look to the existing code, a long before you write the first new line, you realize one killing truth: That you don’t remember almost anything! It’s hard to remember what you did, how you did it, and why! You must follow the one, painful way to wake that project up in your mind, which is no other than taking the project from the beginning and trying to “decode” your implementation line by line. Just a few comments here and there are not helpful, and eventually you end up making a super-effort for a long time until you understand everything. Many of you that you are now reading these lines may have come to that point, and I ensure you that there were times that I’ve been there too. This case is a real nightmare, and you often want to start building the project from scratch. And of course, the scenario described here would just be a… scenario, if we all invested a little time to write proper code documentation.

On the other hand, if you’re working on a project as a member of a team, then avoiding documenting your code would be catastrophic. When you share code with other developers, you must explain up to a point what you do (in the code) and how you do it, and of course other developers are required to do that too. There’s no case developers in big projects to fully understand the code of other fellow developers, as among all, that leads to unneeded waste of time. So, writing documentation in this case it’s like some sort of communication, but also an assistance to other members of the team to get the meaning of your code. After all, each programmer writes code differently than others, so making clear all the points of your code is a must-do task.

So, hoping that I’ve made my point, let me carry on by saying that the proper documentation and commenting regards all programming languages and all platforms. No matter whether you write apps for iOS, web or desktop systems: The point is that you should document as you go, so it’s easy for you (and everyone else) to revise your code really easy and without much effort.

As you understand, in this tutorial I am going to highlight the most important aspects of the code documentation. I’m going to talk for both Objective-C and Swift, as there are developers writing apps in both languages, and of course I’m planning to show you what the similarities and differences between those two languages are. Furthermore, I’ll show you how to produce full, web-based documentation for your app, but I’m afraid that I have to say that this is still an option for the Objective-C only.

As an iOS developer using the Xcode IDE, you might have been thought that the documenting possibilities would be the same for both languages. That’s not the case though, as Swift supports too few documenting options, compared always to the Objective-C, at least at the time of the writing of this post. However, they both give you enough “supplies” so you can write nice documentation. We will begin with Objective-C, as there are more than enough things to say there, and we’ll close this tutorial with code documentation in Swift. There is no need to get in more details now, as we’ll see them in the next parts.

Before we begin, let me note two last things. First, I’m not trying to make you mad about documentation, just to convince you that writing proper comments will improve your programming life. Second, writing code documentation it’s just a habit you have to adopt, and definitely it’s not a waste of time.

Creating a Demo App in Objective-C

Let’s get started by creating a new project in Objective-C, which we will use as the testing base for what we are going to see next. If you haven’t done yet, launch Xcode and create a new project. As we are not going to create a real demo application, selecting the Single View Application is just fine.

In the next step, name the project DocDemoObjC, and make sure to select the Objective-C option in the Language drop down menu:

Get finished with the guide by selecting a directory in your drive to save the project.

Documentation Specifics

As you know, the simplest way to write a comment in both Objective-C and Swift is to use the two slashes as shown below:

// This is a comment.

You can (and must) place anywhere in your code comments like that, so you clarify each part of it. However, when talking about code documentation, definitely I am not talking about the above notation. It would be pointless after all to devote a whole tutorial to that only. Code documentation regards a structured way to write comments using special keywords, also named tags, and marking the comments area with special characters, so the compiler perfectly understands it. There are a few simple rules that should be followed only. The result of all that is that your documentation can be displayed in three different places:

1. In the Quick Help Inspector of the Utilities panel.
2. In the Help Popup that is displayed when you press the Option key and click on the name of method, class or property.
3. In the code-completion popup.

Additionally, proper code documentation enables you to produce complete HTML documentation for your app using various tools, such as the HeaderDoc and Doxygen. We’ll talk about both of them later, and we’ll see how you can do what I just said.

With all the above in mind, it’s time to make one more step further and say that there are three possible ways to mark a documentation area when writing code in Objective-C:

1. To include your comments in a /** – */ block.
2. To include your comments in a /*! – */ block.
3. To begin each commented line with three slashes: ///

In our examples in this tutorial we are going to use the second way to write our documentation. I’m choosing this way for two reasons: First, it’s the only one recognised by HeaderDoc, and if the comment blocks don’t begin with that, no help pages will be created. At second, even though Doxygen prefers the first way, it also recognises this too. So, it’s going to suit us in both cases. The third commenting style is usually used when documenting single lines, such as properties, but still, we’re going to stick to the second option.

Now, there are specific keywords (or tags) you can use when writing documentation. Tags are divided in two categories: The first one regards top level tags, which they can be used to specify what kind of code exactly is commented, such as classes, structs, files, etc. Note that top level tags are not required to be used, but definitely help exporting tools (such as HeaderDoc and Doxygen) to create better results. In the second category exist the second level tags, which specify each details for each part of the documentation block. This kind of tags is actually what you need, as each one of them define another documentation part.

Right next I give you the most important second level tags, but note that they’re not just them. We’ll see a few top level tags later. What I list is what is mostly used:

• @brief: Use it to write a short description about the method, property, class, file, struct, or enum you’re documenting. No line breaks are allowed.
• @discussion: Use it to write a thorough description. You can add line breaks if needed.
• @param: With this you can describe a parameter of a method or function. You can have multiple such tags.
• @return: Use it to specify the return value of a method or function.
• @see: Use it to indicate other related method or functions. You can have multiple such tags.
• @sa: Similar to the previous one.
• @code: With this tag, you can embed code snippets in the documentation. When viewing the documentation in Help Inspector, the code is represented with a different font, inside a special box. Always use the @endcode tag when you finish writing code.
• @remark: Use it to highlight any special facts about the code you’re currently documenting.

You can find a full list of all supported tags here.

Note that the @ character is a prefix to each tag. Also, you can use special switches inside text, so you change its style and formatting. For example, the Text will make the Text word bold, while the Text will make the Text italic. It’s also interesting that you can represent part of the text as code (not a code snippet), if you write @cText. This will result to a different font formatting when the help is displayed in Xcode.

Alternatively to the above, you can replace the @ symbol with the backslash (\). That way the tags will be represented like this: \brief, \param, \return, etc. Note that the backslash is mostly used by the Doxygen documenting system, while the @ is used by the HeaderDoc. Here we’ll use everywhere the @, as it’s compatible with both documenting systems.

Code Documentation in Objective-C

Let’s see now how everything I mentioned above is used. Open the ViewController.m file, and in the private section of the class add the next property:

@interface ViewController ()

@property (nonatomic, strong) NSString *myName;

@end

Now, document it as shown next:

/*! @brief This property knows my name. */
@property (nonatomic, strong) NSString *myName;

Go then to the viewDidLoad method, and start typing it. You will see that in the code completion popup the description we just wrote is there!

But not only. While holding down the Option key in your keyboard, click on the myName property name to let the help popup come up:

Even more, if you open the Help Inspector in the Utilities panel, you’ll find the same documentation there too:

Note that in the above comment the @brief tag could be omitted without any problem at all, as it’s inferred. That means that the next comment is valid as well:

/*! This property knows my name. */
@property (nonatomic, strong) NSString *myName;

Also, the next notation is equal too:

/** This property knows my name. */
@property (nonatomic, strong) NSString *myName;

And this is also equal:

/// This property knows my name. */
@property (nonatomic, strong) NSString *myName;

Let’s see a first, easy example on how to document methods. At this point you must acknowledge that if your goal is to produce an HTML documentation, then only the documentation in the public methods (the header .h files) is visible. Whatever you write in the private parts of your classes is still visible in Xcode help, but no implementation is exported to the documentation. So, knowing that, let’s define a public method in the ViewController.h file:

@interface ViewController : UIViewController

-(float)toCelcius:(float)fromFahrenheit;

@end

Obviously, this method is going to convert the given Fahrenheit degrees to Celsius. Let’s add its documentation now:

/*!
    @brief It converts temperature degrees from Fahrenheit to Celsius scale.

    @discussion This method accepts a float value representing the temperature in Fahrenheit scale and it converts it to the Celsius scale.

                To use it, simply call @c[self toCelsius: 50];

    @param  fromFahrenheit The input value representing the degrees in the Fahrenheit scale.

    @return float The degrees in the Celsius scale.
 */
-(float)toCelcius:(float)fromFahrenheit;

Note that above we use the and HTML switches to make the included words bold and italic respectively. Also notice how we mark the inline code using the @c switch.

To see in the Xcode help how that documentation looks, open the ViewController.m file and define the method:

-(float)toCelcius:(float)fromFahrenheit{
    return (fromFahrenheit - 32) / 1.8;
}

Then place the caret on the method’s name, and look in the Quick Help Inspector:

You see that Xcode properly formats each part of the documentation. Here’s the same in the help popup (Option + Click on the method’s name):

If you call it in the viewDidLoad method, then you can see the brief description in the code-completion popup:

Great, isn’t it? Just imagine how helpful and self-explaining your code can be that way, especially if you’re working with other people in a team.

To make this example even more interesting, let’s add one more public method that will do the exact opposing thing: Conversion from Celsius to Fahrenheit. Open the ViewController.h file, and add the next method declaration, along with its documentation:

/*!
    @brief It converts temperature degrees from Celsius to Fahrenheit scale.

    @param  fromCelcius The celsius degrees value.

    @return float The degrees in the Fahrenheit scale.

    @code
        float f = [self toCelsius:80];
    @endcode

    @remark This is a super-easy method.
 */
-(float)toFahrenheit:(float)fromCelcius;

In the above snippet we added two new tags: The @code – @endcode pair, and the @remark. You’ll see how they’re displayed right next.

Let’s go to implement the method in the ViewController.m file:

-(float)toFahrenheit:(float)fromCelcius{
    return fromCelcius * 1.8 + 32;
}

And let’s see the Help Popup now:

Pretty nice! Now your documentation has nothing to be jealous of the Xcode default documentation.

Before we move to the next part, open the ViewController.h file, and add the following property declaration (commented of course):

/*! An application delegate object. */
@property (nonatomic, strong) AppDelegate *appDelegate;

Along with it, import the AppDelegate class:

#import 

The reason we added the above property to the class is to make us able to see later how it is exported using the documentation tools (HeaderDoc and Doxygen), along with the methods we already created.

Files, Classes, Structs and Enums

In the previous part we went through the basic documenting principles that you should be aligned with when writing properties or methods/functions. I intentionally chose to begin demonstrating from that point, as the most of your developing time will be consumed there. Now that we’ve seen some of the essentials of our topic, let’s keep going by taking a look on how to add documentation notes regarding files, classes, structs and enums.

Let’s get started by files, and how you write informative documentation in Objective-C. When sharing programming work with others, or you distribute your code as an open source component, then adding file documentation is almost mandatory, as that’s the best place to provide specific information to your partners or users of your code. Normally, you are going to give extra attention to the header file (.h) and the descriptions in it, as this is the one in the final documentation that will be exported (not in Xcode); however this doesn’t mean that you should not add description to implementation files. Don’t forget that when a project opens in Xcode, everything it’s there, not just the header files, so make sure you don’t leave any part of it undocumented. Besides that, implementation is not shown in exported documentation, but the description of all files is always visible.

Let me introduce you a few new tags that you can use when documenting a file:

• @file: Use this tag to indicate that you’re documenting a file (header or not). If you’re about to use Doxygen to produce documentation, then you’d better set the file name right after this tag. It’s a top level tag.
• @header: Similar to the above, but used with HeaderDoc. Don’t use the above if you won’t use Doxygen.
• @author Use it to write the author info of the file.
• @copyright: Add copyright info.
• @version: Use it to write the current version of the file. Pretty important if versioning matters during the project’s lifetime.

There are more tags of course you could use, but those are the most usual ones. I would advice you to go either through the HeaderDoc or the Doxygen documentation, so you can find extra keywords to use if you want so.

Let’s go to add documentation now to the ViewController.h header file. Go to the top of the file, right before the import command. There, add the next lines:

/*!
 @header ViewController.h

 @brief This is the header file where my super-code is contained.

 This file contains the most importnant method and properties decalaration. It's parted by two methods in total, which can be used to perform temperature conversions.

 @author Your_Name
 @copyright  2015 Your_Name
 @version    15.12.7
 */

You can replace the Your_Name string with your actual name, or your company’s name. Also, it’s always a good idea to use the brief tag instead of just omitting it, as this will enable the documenting systems (you’ll see later in HeaderDoc and Doxygen) to display the short description you add here in the output HTML pages. I remind you once again that instead of the “@” symbol, you can use the backslash, but only for Doxygen. Also, we are not going to see here how the above documentation appears, but we’ll do so a bit later when we’ll produce HTML files.

All the above are great, but the truth is that the default informative comments added by Xcode in each new file you create are pretty good and enough in many cases. You would want to create a file description block when you work with other people in a team and each member must clarify the details of the file(s) he’s in charge for, or when you’re planning to produce complete documentation of the project using HeaderDoc or Doxygen, or lastly, when you’re the sole developer but the project is parted by a big number of files. Anyway, it’s up to you to decide the level of documentation you’re willing to go up to.

Let’s see now how you can document a class or a protocol. Once again, I give you the most usual tags only. Look up in the documentation for more tags.

• @class: Use it to point the starting point of a documentation block regarding a class. It’s a top level tag, and after it you should provide the class name.
• @interface: Same as above.
• @protocol: Just like the above two, just for protocols.
• @superclass: The superclass of the current class.
• @classdesign: Use this tag to mention any special design you follow or apply in the current class (for example, you could mention a Singleton class design, or something like this).
• @coclass: The name of another class that the current one works with.
• @helps: Name the class which the current one works as a helper for.
• @helper: Name any other class(es) that work as helpers for the current one.

Actually, you will rarely need any of the above tags, except maybe for the superclass. The list is much longer, but I find it pointless to add more of them here. Let me underline that the tags starting from the superclass and below, are not recognised by Doxygen, only by HeaderDoc. Also, the Quick Help and Help Popup windows in Xcode display the values next to each tag, but not the tags themselves. So, decide if you’re about to use them or not, always depending on whether you’re going to use a documenting system, and which one.

Let’s see an example by documenting our class in the ViewController.h file. Just right before the interface body opening, add these:

/*!
 @class ViewController

 @brief The ViewController class

 @discussion    This class was designed and implemented to help people covert temperatures between the Fahrenheit and Celsius scales.

 @superclass SuperClass: UIViewController\n
 @classdesign    No special design is applied here.
 @coclass    AppDelegate
 @helps It helps no other classes.
 @helper    No helper exists for this class. 
 */

Now, if you place the caret on the ViewController class name, or you Option+Click on it, you can see how the above description is shown in the Xcode Help.

As you see the tags are not displayed, but in this case it doesn’t consist of a problem.

It’s also great that you can see the class short description as you declare objects of it. To really watch this, open the ViewController.m file and go straight ahead in the viewDidLoad method. In there, start typing so you declare a local ViewController object. You’ll see the short description of the file appearing in the code completion popup window:

In the same way as above you can document a protocol. Add the next lines before the class in the ViewController.h file:

/*!
    @protocol ViewControllerDelegate

    @brief The ViewControllerDelegate protocol

    It's a protocol used as a demo here. In a real application it would be quite useful.
 */
@protocol ViewControllerDelegate

/*!
    Nothing to say here... Just testing documentation.
 */
-(void)thisIsADelegateMethod;

@end

Option+Click on the protocol’s name to see it appearing in the Help Popup window.

As you can see above, we also declared a delegate method. You might think at the moment that is meaningless, however I purposely want this method to be there for demo reasons only; when we’ll use HeaderDoc and Doxygen to export documentation later it will be nice to see it in the exported HTML pages.

Now that we’ve talked about files, classes and protocols, and you have hopefully got the big picture, let’s see a couple more special cases: How to document structs and enumerations. Their common element is that you use the @typedef top level tag in both of them, so you indicate the opening of the documentation block (I remind you that using top level tags is absolutely optional).

For Doxygen specifically, you should use the @struct tag for structs, and the @enum tag for enums, instead of the @typedef.

Let’s see the following code struct. Add it to the ViewController.h file right before the opening line of the interface:

typedef struct {
    int sun;
    int clouds;
    int rain;
    int snow;
} WeatherConditionsInDays;

Now add these few lines above it:

/*!
 @typedef WeatherConditionsInDays

 @brief  A struct about the weather.

 @discussion
 The values of this structure represent how many sunny, cloudy, rainy, and snowy days existed over the last year. If this was a real app, they could be perfectly used.

 @field sun Good weather
 @field clouds  Where's the sun?
 @field rain    Get an umbrella
 @field snow    Watch out... A snowball is coming!
 */

As you see here, there’s a new tag named @field. This tag is handy to describe each single variable of the struct. Again, I must highlight the difference between the HeaderDoc and Doxygen. In HeaderDoc, this tag is acceptable and valid. However, in Doxygen things change as it’s not compatible with this tag. What we could do in this case is to simply comment each variable separately. Doing that will also display the comment for each one when we’ll access them in the implementation file. Let’s see that (note that the @field tags and the comments above variables contain different values so it’s easier to be identified later):

/*!
 @typedef WeatherConditionsInDays

 @brief  A struct about the weather.

 @discussion
 The values of this structure represent how many sunny, cloudy, rainy, and snowy days existed over the last year. If this was a real app, they could be perfectly used.

 @field sun Good weather
 @field clouds  Where's the sun?
 @field rain    Get an umbrella
 @field snow    Watch out... A snowball is coming!
 */
typedef struct {
    /*! Good weather */
    int sun;
    /*! At least it's not raining */
    int clouds;
    /*! Don't forget to get your umbrella */
    int rain;
    /*! Time to go skiiiiiing */
    int snow;
} WeatherConditionsInDays;

If you go now to the ViewController.m file and declare an variable of this struct, then by accessing any of the above values you’ll see the description in the code completion popup window.

Enumerations are handled in the exact same way, so I leave it to you to as an exercise to create an enum type and document it. Easy task to accomplish, isn’t it? Once your enum is ready, use it in the viewDidLoad method to see if your documentation is appeared in any of the Xcode Help options.

Watching For Errors

As you have seen in all the previous examples, next to the @param tag you must always write the parameter’s name, and after that a proper description. Of course, it’s quite possible that you mistype a parameter name, especially if it’s a bit complex, and to create documentation containing errors. However, there’s a way to be protected against that, and I suspect that you didn’t know that Xcode can be your trusty assistant in that.

Indeed, even though Xcode deals with documentation once its written, it can help you by preventing you mistyping any parameter names. All it gets to do that, is to enable a setting. Let’s see what I mean exactly:

In the Project Navigator, click on the Project’s group, and then go straight ahead to the Build Settings tab, as shown in the next figure:

Once you do so, in the Search box just type the comments keyword and wait to see the results right below. One of the returned results is a setting named Documentation Comments, and (normally) its current value is set to NO. All you have to do is to set the YES value, and you’re ready.

Now, let’s go to see how the above setting affects the way we document our code. Open the ViewController.m file, and go to the private class section, where we are about to declare a private method. Here it is:

@interface ViewController ()

-(float)showCurrentTemperatureInCity:(NSString *)targetCityName showInScale:(NSString *)preferredScale;

@end

If we were really going to implement it, this method would return the temperature in the selected city, expressed in the preferred scale (Fahrenheit or Celsius). Now, let’s add a few comments above it:

/*!
    This method returns the current temperature in the selected city, expressed in either Fahrenheit or Celsious degrees.

    @param  targetcityName  The city that the temperature will be returned for.
    @param  preferredScale  Fahrenheit or Celsius.

    @return float   The current temperature of the city.
 */
-(float)showCurrentTemperatureInCity:(NSString *)targetCityName showInScale:(NSString *)preferredScale;

Once you copy-paste the above comments in your Xcode, a warning will appear in the line where the first parameter is documented, telling us that the targetcityName parameter was not found in the function declaration. And guess what? That’s true! Instead of writing the parameter name properly (targetCityName), I wrote it wrongly by not capitalizing the first character of the “city” word (targetcityName). That’s something that in a big project with a lot of comments we would probably not realize, but thankfully Xcode is here to give us a hand and an extra “pair of eyes”.

Now, if you click in the warning triangle icon at the left, you will notice that Xcode auto-suggests the proper parameter name, which you can click so it’s fixed. Alternatively, go and fix it on your own.

With all the above, you don’t need to be afraid of making any typo while writing parameter names during documentation.

Producing Documentation With HeaderDoc

Now that we have covered the essentials about code documentation, let’s move to another important part, and let’s see how we can create HTML files containing the documentation we added to our project. In this section we are going to use HeaderDoc, a pretty nice tool that works great with the documentation written to files. For your reference, I recommend you visit this site and read more about it. In short, I’m just telling you that using HeaderDoc we’re going to export all the documented parts of the project in HTML pages. In small projects doing that might be meaningless, but in large projects or in cases where you deliver your own SDK to others, an accompanying documentation is almost necessary.

The HeaderDoc tool is actually a command-line tool. It supports various switches to configure the exporting process in a high-detail level, and you can find them in the link I gave you above. Here, we’re going to use just one switch, useful to specify the output directory (the directory where the documentation will reside).

Let’s see some action now. Initially, let’s create a directory for the documentation that will be produced. For easy access, I’m choosing to do that in my Desktop, but you can select any other destination you desire, as long as you update the paths you’ll see later on. So, in my Desktop I created a directory named DocDemo, and in there I added two subdirectories: One named HeaderDoc, and one named Doxygen. As you guess, the documentation produced by each tool will be placed to the respective folder.

Next, you must open the Terminal app, so either click on the LaunchPad > Other group > Terminal, or in the Spotlight write the terminal term.

Now, it would be a nice idea to navigate yourself in the project directory using terminal, and you can do that easily following the next steps:

1. In Terminal write the cd command and hit the spacebar. Don’t press the Return key.
2. In Finder, locate the root directory that contains the project.
3. Drag and drop this directory straight to the terminal window, as you see in the next screenshot.

Then hit the Return key in the keyboard, and to verify that you’re in the right folder just use the pwd command (in terminal always).

The HeaderDoc command we’ll use here is named headerdoc2html, and we’ll form it as follows:

headerdoc2html -o OutputDirectory InputDirectory

The OutputDirectory is the directory we created right before, and the input directory is the folder where the project files exist.

Now, let’s use it in real. In your terminal window, write or copy-paste the following part:

headerdoc2html -o 

Note that after the -o switch there’s a space character.

Next, go in Finder and click on the directory name where the documentation will be exported. Following the steps described above, drag and drop it to the terminal. After that, type the name of the input directory followed by a slash. Here’s how the whole command should look like:

headerdoc2html -o /Users/gabriel/Desktop/DocDemo/HeaderDoc DocDemoObjC/

You will see various stuff appearing, but no need to pay special attention to that right now. Once it gets finished, mark and copy the path of the output directory, write the next command in terminal:

gatherheaderdoc 

and paste the path. Press Return and let it run. This command will create a table of contents page, where all commented files, classes and methods will exist in one place.

That’s it. Now go to Finder, and open the masterTOC.html file in your browser. Here’s what you’ll see:

If you click in the ViewController link, here’s the page that you’ll be guided to:

There you can find the description of the file, and the class, the protocol and the struct with links to them along with their brief descriptions. The struct details are shown in the same page.

Notice that the fields contain double values, but that’s only because we added comments both using the @field tag, and above each struct variable. If you want, you can go back in Xcode and delete any of the two. Next, run again the HeaderDoc commands in terminal and get back here.

If you click in the class link, you’ll go to a new page, where you can see its description, the two methods and the one property we declared in the header file.

Now that you’ve seen the results, walk freely around everywhere in the documentation pages and see how everything is being displayed. HeaderDoc usage doesn’t stop here, but that’s what you’ll need in most of the cases.

Producing Documentation with Doxygen

Time to leave HeaderDoc behind us and let’s see how to use a quite widespread documenting system, named Doxygen. Before we see the details concerning it, I should say that Doxygen was not originally designed to parse documentation in Objective-C. However, it is going to perfectly work as it aims to C and C++ style languages mostly, and as you’ll see by yourself, it supports a variety of languages. Besides that, it contains a large amount of documenting tags, and if you decide to write documentation that will eventually be parsed by Doxygen, you can use any of them so as to have greater compatibility.

Doxygen is a third-party application which you must download before use it. There are versions of it for all common operating systems, so it can work for you even if you’re not developing for iOS only. At this point, let me give you three important links:

1. In this link you can find all the resources you need regarding the code documentation.
2. Here you can find all the tags supported by Doxygen, and by clicking to each one you get extra information about its usage.
3. Lastly, you can visit this page to download the Doxygen application.

Before we download it, let me note that you can find much more than what I just mentioned above in the Doxygen website. Actually, as you can see in the next screenshot, there’s a menu panel at the left side, which you can use to dive in various parts of it and find numerous details and how-tos.

Now, pay a visit to the last link I gave you above, and scroll a bit down to the page until you find an area named A binary distribution for Mac OS X 10.5 and later. Click either in the ftp, or in the http link to initiate the package downloading. Depending on your Internet connection speed, it might take a few seconds for the download to complete, as the file is about 55 Mb.

Once the download process is over, open the package. Then, get the Doxygen application and drag it to your Applications directory.

If you don’t want to add it to the Applications directory it’s okay. Just place it anywhere else you want. After all, Doxygen is a fully self-contained application, so to remove it just delete its app file, no matter where you’ll place it.

Assuming now that you’ve copied it in the Applications directory, click in the Launchpad to find it easily. Click it to let it run.

NOTE: If you get a message saying that the application cannot be opened because it’s from an unidentified developer, follow the next steps to overcome it: In Finder, open the Applications directory. Locate the Doxygen app, and then Ctrl+Click it. Select the Open option in the context menu, and in the new dialog window that will be shown, click to the Open button.

Now, leave the Doxygen app aside, and go back to Xcode. We’ll perform two changes in two tags, so everything to be recognised. Make sure to open the ViewController.h file, and in its description block replace the @header top level tag with the @file tag. Also, a modification is needed to the documentation block of the struct, where the @typedef tag must be replaced with the @struct tag. After having done these, let’s leave Xcode again.

If you’ve used Doxygen in the past, then you definitely know what to do. However, I’ll assume it’s your first time in this app, so let me present you the most important steps.

Right next it’s the initial Doxygen window upon first run:

Before I tell you the exact settings you should apply, it’s necessary to say that Doxygen provides two modes of usage: The Wizard which consists of a simple and general way, and the Expert mode, where a huge number of settings can be specified so you customize each detail of the produced documentation.

I’m not going to focus on the Expert mode, because the applied settings there are highly depending on the personal needs of each developer. That means that we’ll stick with the Wizard mode, but prior to this, I think that it worths to take a super-fast walk in the Expert mode. By clicking in the Expert button in the main window area, you instantly see that you are given with a great number of settings in the main panel. You can scroll up and down to go trough all of them, but they’re not just them. At the left side, there’s a smaller panel titled Topics, and by clicking to another topic you access its own settings. If you have the time, visit all of them. You might find useful options that you would like to use in your apps.

Now, let’s focus in the Wizard mode. Make sure to click on the respective button, so you can follow what I describe next. At first, at the top of the window we must specify where Doxygen runs from. Just click in the Select button, and select the Applications directory in your computer, or any other location where you’ve copied the Doxygen app into.

Next, let’s specify the project’s name. In the Project Name: field, set the DocDemo in Objective-C value (or anything else you desire). If you want, also fill the next fields in too. Below that, we must specify the path to our project. Once again, use the Select button and navigate yourself to the root directory of the project. It would be a good idea to click in the Scan recursively, so Doxygen can scan subdirectories too.

Lastly, specify where the produced documentation should be stored. If you remember, we had created the Doxygen subdirectory in the DocDemo directory in Desktop for this purpose. So, click on the Select button next to the Destination Directory field, and pick it.

Next, in the Topics list at the left, click on the Mode option. In the new settings, click in the All Entities option:

Next, again in the Topics list, click on the Output option. Here you can find various exporting options. Feel free to select any kind of output you desire. For this example, I deselected the LaTeX option, I just left the HTML on.

Finally, in the Diagrams options you can just leave the default setting as they are.

It’s time now to produce the documentation. Please, be sure that you’ve set all the options mentioned above before you continue. You did it? Okay, let’s keep going. Click on the Run button (next to the Wizard and Expert buttons), and in the main window area now you will see a new button titled Run doxygen. Click it to let the app start creating the HTML files for you. In the white area you’ll see some output messages, and if something is wrong, that’s the place where you’ll see it.

Anyway, once it’s finished, open Finder and navigate straight ahead to the output directory to see the exported files. You will notice that a bunch of files have been created, and the one you’re looking for is named index.html. Double click it to open it in the browser. Alternatively, if you don’t care to see the exported files, simply click on the Show HTML output in the Doxygen window.

This is the first screen you face by opening the index page:

It just contains the project title we set earlier, the generation timestamp, and a couple of links at the top. Use these links to navigate yourself around. For example, if you click on the Classes link, you’ll get a list of all classes existing in the project. The interesting part here is that next to each class they are displayed the brief descriptions we wrote (only where we wrote them).

Here’s what you see when tapping in the ViewController class:

As you can see, the detailed documentation of the methods and the one public property we have in the project can be found there. Another interesting point is under the Files menu, where all the parsed files are listed, and by selecting the ViewController.h file. In there you find the file description, and everything we declared: The class, the protocol and the struct.

Use the More… links to go to the details of any of the above. There’s also a link titled ”Go to the source code of this file.”, which if it’s tapped, it displays the code of the ViewController.h header file. Note that whatever is written in header files is public, so it can be displayed here. However, don’t expect to find any implementation code at all. That’s for “your eyes only”.

So, I’m pretty sure at this point that you’ve got the grasp of all the above. Navigate in the exported HTML pages, go back in Xcode to make changes in documentation, and re-produce everything. Also, don’t hesitate to set advanced settings and see what happens. In general, play around as much as you want, and familiarize yourself with Doxygen. It’s a great tool that can be used for both small and big projects.

Creating a Demo App in Swift

Let’s turn page now for one more time, and let’s say a few words about documenting your code in Swift. To make things as much clear as possible, let’s create a new demo project, this time in Swift.

So, begin creating one in Xcode, and in the first step of the guide specify the Single View Application as the template of the application. Next, name the project DocDemoSwift, and also be sure that the selected language is the Swift. Proceed, select a directory to save the project, and let Xcode to create it.

Documenting in Swift

Code documentation in Swift is less powerful that in Objective-C, and that’s the reason I left the discussion about it for the end. Unfortunately, neither HeaderDoc nor Doxygen support Swift (at least for now, I can’t say what may happen in the future), and the documentation formatting is now based in the reStructuredText, an open source project for which you can find more info here.

From all the tags we met in the previous parts of this tutorial, there are only two that can be used in this case: The param and return, which actually becomes returns (note the “s” at the end). Also, neither the @ or the backslash symbol is supported. Instead, both of these tags are included in semicolons, for example :param:. After that, the parameter name must be written, followed by its description.

The brief and discussion tags are not used, but the respective parts can be added to the documentation as the tags are inferred, meaning that a short text at the beginning of the documentation block is considered to be the brief description, and bigger text parts after that are the discussion.

The new and interesting thing here is that in the discussion part you can add ordered and unordered lists, as well as fields with descriptions. For example, to add an ordered list you just need to write:

1. First item
2. Second item
3. Third item

For unordered lists, you either use the asterisk (*), or the dash (-) symbol. For example:

* An item
* Another item
* More items

And:

- An item
- Another item
- More items

Note: If you are familiar with the Markdown syntax, then the above are already known to you.

To have fields in the discussion area, you just have to write the field name surrounded by semicolons, and then the description:

:MyField: This is a field example

All the above, including the two tags (param and returns) are enough so you write proper documentation. Even though not as many options as in Objective-C are provided, I believe that all the previous stuff is all you need, so I’ll show you no more.

Let’s go to Xcode now to see an example of all those. Open the ViewController.swift file, and in there define the following method (similar to the Objective-C example):

func toCelsius(fromFahrenheit: Float) -> Float {
    return (fromFahrenheit - 32) / 1.8;
}

Having in mind the prior description about the documentation in Swift code, here’s how the same comments we added in Objective-C version are written here:

/**
It converts temperature degrees from Fahrenheit to Celsius scale.

This method accepts a float value representing the temperature in Fahrenheit scale and it converts it to the Celsius scale.
To use it, simply call toCelsius(50) or self.toCelsius(50)

:param: fromFahrenheit The input value representing the degrees in the Fahrenheit scale.

:returns:   float The degrees in the Celsius scale.
*/
func toCelsius(fromFahrenheit: Float) -> Float {
    return (fromFahrenheit - 32) / 1.8;
}

Note that we use the /** – */ notation here. By looking in the Help popup, here’s the result:

Also, if you start typing the method’s name in the viewDidLoad method, the brief description is appeared in the code completion:

Now, let’s create a super-simple new method that will do nothing at all:

func myHelloMethod(){
    println("Hello there")
}

We are going to document the above method by creating lists and fields. What you’ll see next is clearly an example, so don’t try to find any logic in the comments.

/**
    This method was implemented to do nothing hard, just to say hello.

    Here is a demo of an ordered list:

    1. One
    2. Two
    3. Three
    4. Four

    How about an unordered list?

    * North
    * East
    * South
    * West

    Let's add a couple of fields now:

    :Job: My dreaming job
    :Salary:    My dreaming salary

*/
func myHelloMethod(){
    println("Hello there")
}

By Option+Click in the method’s name, here’s what is being displayed in the Help popup:

All the above is pretty much what you need to document your code in Swift. However, don’t hesitate to try more options after having read the reStructuredText manual (or some of it… it’s huge).

Summary

In this tutorial we’ve managed to see many aspects concerning the code documentation. We talked for both Objective-C and Swift, and went through the most important principles regarding each one. As you found out, in Objective-C you have a ton more options to use, but yet, the provided tools are just fine in Swift as well. What I presented today is not what only exists. There are more you can find and use, but my point was to introduce you the most usual documenting information. What you’ve read here, is what you’ll need in nine out of ten cases. Also, don’t forget the two interesting tools we met, HeaderDoc and Doxygen. Both of them can produce great documentation, and they can become nice “friends” of yours. As a last word, I’d like to highlight once again that documenting your code is really a big deal. You may often doubt about that, but trust me, it worths each second you’ll consume for this task. Help both yourself and others by writing proper documentation, straight into the point, that explains everything you do in your code. If you’re not used to doing that, you’d better start now, even if you’re not a young developer. See you!

Editor’s note: When Facebook released its Paper app, it generated a lot of buzz in the app world. If you’ve used Paper before, the visual news feed reader, you should be amazed by its beautiful and fluid user interface. The design and attention to detail on the app is unmatched. The app refrains from using buttons and menus, but was built to be gesture-driven, to a degree that was uncommonly found in iOS apps at the time of its release. It went beyond Core Animation. The team has built its own animation engine to support all the smooth animations and coordinate animations with touch inputs. When I first tried out the app, I was wondering how some of the animations were implemented. Honestly I didn’t know how. A couple months later, the company open-sourced Pop, the animation engine behind its iOS Paper app. As a Facebook’s engineer described, Pop drives the scrolling, bouncing, and unfolding effects that bring Paper to life. Thanks to Facebook team. With the Pop framework, this means you can create similar animations that were found on Paper in your own apps.

The Pop framework was first released in late April, 2014. So far we haven’t written any tutorials about the framework. Thanks to Hossam who is kind enough to share with us an introduction of POP and show us how to create a few simple animations.

Enter the Pop tutorial.

In this tutorial, we will talk about Facebook POP framework to make great and easy animations in your own iOS apps. Like any other tutorials on AppCoda, I will help you understand and master Pop by examples. We will create four simple animations together to explore the framework.

Pop is an extensible animation engine for both iOS and OS X. In addition to basic animations including Linear, Ease-In, Ease-Out, Ease-In-Ease-Out animations, it supports spring (at the time of its release, spring animation was not supported in iOS), decay and custom animations:

• Spring – dynamic animation that creates a nice bouncing effect.
• Decay – dynamic animation that brings a movement to a smooth halt.
• Custom – because the engine is designed to be extensible, you can create your own custom animations.

The fundamental animation type of Pop is a POPAnimation. You can think of it as the abstract or base class of all POP animations. The Pop interface is implemented as an addition of category on NSObject. This allows any object to be animated.

The Pop API is very developer friendly that lets you easily build some realistic, physics-based interactions. For instance, here is the code snippet for creating a spring animation on a text label:

POPSpringAnimation *sprintAnimation = [POPSpringAnimation animationWithPropertyNamed:kPOPViewScaleXY];
sprintAnimation.toValue = [NSValue valueWithCGPoint:CGPointMake(0.9, 0.9)];
sprintAnimation.velocity = [NSValue valueWithCGPoint:CGPointMake(2, 2)];
sprintAnimation.springBounciness = 20.f;
[self.textLabel pop_addAnimation:sprintAnimation forKey:@"springAnimation"];

Easy, right? Let’s get started and create the demo app. I’m sure you’ll have a better understanding of Pop after going through the project.

Using Pop Framework

If you use CocoaPods, you can just add the following to your project Podfile:

pod ‘pop’, ‘~> 1.0’

For non-CocoaPods project, you can download the Pop framework here and add the “pop” folder to your workspace. Go to your project and ensure the “Other Linker Flags” option is added with -lc++ under Build Settings.

Also set the Header Search Path to the correct folder. For instance, I used to put the “pop” framework under a “Library” folder. You can set the Header Search Path to “$(SRCROOT)/Library”. To use the framework, you can just add the following import statement in your source code:

#import 

Once you added the framework, create a simple table view like below. It’s just a simple table displaying three rows:

If you don’t want to start from scratch, you can download the starter project here.

Example #1: UITableViewCell Animation

For the first example, we will create animations on the table view cells. We will add a basic scale up animation when a user highlights a cell. When releasing, we will scale it back using spring animation.

Go to ExampleCell.m and override the setHighlighted: method using the code snippet below:

- (void)setHighlighted:(BOOL)highlighted animated:(BOOL)animated
{
    [super setHighlighted:highlighted animated:animated];
    if (self.highlighted) {
        POPBasicAnimation *scaleAnimation = [POPBasicAnimation animationWithPropertyNamed:kPOPViewScaleXY];
        scaleAnimation.duration = 0.1;
        scaleAnimation.toValue = [NSValue valueWithCGPoint:CGPointMake(1, 1)];
        [self.textLabel pop_addAnimation:scaleAnimation forKey:@"scalingUp"];
        
        
        
    } else {
        POPSpringAnimation *sprintAnimation = [POPSpringAnimation animationWithPropertyNamed:kPOPViewScaleXY];
        sprintAnimation.toValue = [NSValue valueWithCGPoint:CGPointMake(0.9, 0.9)];
        sprintAnimation.velocity = [NSValue valueWithCGPoint:CGPointMake(2, 2)];
        sprintAnimation.springBounciness = 20.f;
        [self.textLabel pop_addAnimation:sprintAnimation forKey:@"springAnimation"];
    }
}

It is pretty straightforward to use Pop. You first choose a particular type of animation. Like the above example, we pick the POPBasicAnimation when the cell is highlighted and POPSpringAnimation when the user lifts up his/her finger. Once you select the type of animation, the second thing is to provide the animation properties. For both animations, we specify the kPOPViewScaleXY property for scaling the label. Next, we specify toValue which describes your desired end state of the animation. In the above, we set to CGPointMake(1, 1) that scales the object with a value of one. Depending on the type of animation you’re creating, you’ll have to configure addition settings like springBounciness in spring animations that controls the bouncing effect. Lastly, we add the animation to the text label and give it a name (e.g. springAnimation).

Now build and run the app. Highlight any cell and release it to test the animation.

Example #2: Animating a Like Button

Have you used the Facebook Messenger app? I really like the animation of the Send/Like button when you start to type message to a friend. I decided to use Pop to create a similar animation.

First, create a new view controller in the storyboard. In the view controller, create a text field for comments. Then add a Send and Like buttons. You can download the Like button image here and import it to the image asset. Just place the Like button over the Send button. Later we will write some code to display one of the buttons at a time. By default, the Like button will be displayed. When a user keys in a comment, we will hide the Like button and display the Send button with an animation.

Lastly, connect the example list view controller with Facebook Like view controller by using a manual segue. Set the identifier of the segue as “openFB”. Later we’ll use code to trigger the segue.

Once you designed the user interface, create a new class called FacebookButtonAnimationViewController and set it as the custom class of the view controller.

Next, create the outlet variables for both Like and Send buttons, as well as, the text field. Your outlet variable should look like this:

@interface FacebookButtonAnimationViewController ()
@property (weak, nonatomic) IBOutlet UIButton *likeButton;
@property (weak, nonatomic) IBOutlet UIButton *sendButton;
@property (weak, nonatomic) IBOutlet UITextField *msgTextField;

@end

In FacebookButtonAnimationViewController.h, import POP.h and implement the UITextFieldDelegate:

#import 
#import 

@interface FacebookButtonAnimationViewController : UIViewController 

@end

In the viewDidLoad method of FacebookButtonAnimationViewController.m, insert the following line of code to set the delegate of text field and hide the Send button:

self.msgTextField.delegate = self;
self.sendButton.hidden = YES;

Now we will implement the methods for handling the text field. Insert these methods in the same file:

- (BOOL)textField:(UITextField *)textField shouldChangeCharactersInRange:(NSRange)range replacementString:(NSString *)string {
    
    NSString *comment;
    
    if (range.length == 0) {
        comment = [NSString stringWithFormat:@"%@%@", textField.text, string];
    } else {
        comment = [textField.text substringToIndex:textField.text.length - range.length];
    }
    
    if (comment.length == 0) {
        // Show Like
        [self showLikeButton];
    } else  {
        // Show Send
        [self showSendButton];
    }
    
    return YES;
}

The shouldChangeCharactersInRange method is called every time when whenever the user types a new character or delete a character in the text field. If the text field is empty, we display the Like button. On the other hand, if the text field contains any characters, we display the Send button.

Next, we implement both showLikeButton and showSendButton methods:

- (void)showSendButton {
    if (self.sendButton.isHidden) {
        self.likeButton.hidden = YES;
        self.sendButton.hidden = NO;
        
        POPSpringAnimation *sprintAnimation = [POPSpringAnimation animationWithPropertyNamed:kPOPViewScaleXY];
        
        sprintAnimation.velocity = [NSValue valueWithCGPoint:CGPointMake(8, 8)];
        sprintAnimation.springBounciness = 20.f;
        [self.sendButton pop_addAnimation:sprintAnimation forKey:@"sendAnimation"];
    }
}

-(void)showLikeButton {
    self.likeButton.hidden = NO;
    self.sendButton.hidden = YES;
    
    POPSpringAnimation *spin = [POPSpringAnimation animationWithPropertyNamed:kPOPLayerRotation];
    
    spin.fromValue = @(M_PI / 4);
    spin.toValue = @(0);
    spin.springBounciness = 20;
    spin.velocity = @(10);
    [self.likeButton.layer pop_addAnimation:spin forKey:@"likeAnimation"];
}

In the showSendButton method, we hide the Like button and show the Send button, and then apply a spring animation with the kPOPViewScaleXY property on the Send button.

The same technique is used for the Like button but we apply a rotation animation instead. We first create an instance of POPSpringAnimation and then set the “from” and “to” values. The Like button is rotated from 45 degrees (i.e. M_PI/4) to 0 degree with bounciness set to 20.

Lastly, insert the following method in ExamplesListViewController.m to trigger the segue:

-(void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath
{
    switch (indexPath.row) {
        case 0:
            [self performSegueWithIdentifier:@"openFB" sender:self];
            break;
        case 1:
            [self performSegueWithIdentifier:@"openWrongPass" sender:self];
            break;
        case 2:
            [self performSegueWithIdentifier:@"openCustomTransition" sender:self];
            break;
            
        default:
            break;
    }
}

Now it is ready to test the app. Hit the Run button and key in a character in the text field to test the animation.

Example #3: Wrong Password Animation

As a Mac user, you should be very familiar with the password field in Mac OS X. When you type a wrong password during login, the text field shakes. In this example, we’ll use Pop to replicate the animation.

First, go to Interface Builder and add a new view controller. Then add a text field and a Login button. Again, create a manual segue between the Example List View Controller and the new view controller. Set the segue’s identifier to “openWrongPass”. Your user interface should be similar to this:

Next, create a new class called WrongPasswordViewController and set it as the custom class of the new view controller. Create an outlet variable for the text field and name it passwordTextField.

@interface WrongPasswordViewController ()
@property (weak, nonatomic) IBOutlet UITextField *passwordTextField;

@end

Then we create an action method named “login” for the Login button.

As said before, we will apply a “shake” animation on the text field to indicate a wrong password. For demo purpose, we will not verify the password. We will just show the animation whenever the user clicks the Login button.

Implement the login method like this:

- (IBAction)login:(id)sender {
    
    POPSpringAnimation *shake = [POPSpringAnimation animationWithPropertyNamed:kPOPLayerPositionX];
    
    shake.springBounciness = 20;
    shake.velocity = @(3000);
    
    [self.passwordTextField.layer pop_addAnimation:shake forKey:@"shakePassword"];

}

The above code is pretty straightforward. We create the POPSpringAnimation with the kPOPLayerPositionX property. This property simply moves the text field along the X axis.

Lastly, remember to import the POP.h at the beginning of the WrongPasswordViewController.m:

#import 

Cool! Compile and run the app to test the animation.

Example #4: Custom View Controller Transition

In the last example, I will show you how to present a view controller with a custom animation. We will a view controller with a single button “Present”. When a user taps the button, the app presents another view controller modally with a custom animation. Since iOS 7, you can customise the view transition by using the transitioningDelegate of UIViewController. The delegate, which should conform to UIViewControllerAnimatedTransitioning, provides the transition animator that animates the transition of view controllers.

First, create two view controllers in the storyboard and two new classes. Name one class “CustomVCTransitionViewController” and the other “CustomModalViewController”. Set these classes as the custom class of the controllers. For the modal view controller (in red), set the storyboard ID to “customModal”. Further, connect the Example List View Controller with the CustomVCTransitionViewController using a manual segue. Set the identifier of the segue to “openCustomTransition”.

Your UI design should look like this:

You can have a quick test of the app. When you select Custom VC Transition, the CustomVCTransitionController should appear.

Now we’ll implement the CustomVCTransitionViewController to handle the Present button. Insert the following line of code in CustomVCTransitionViewController.h to adopt the UIViewControllerTransitioningDelegate protocol:

@interface CustomVCTransitionViewController : UIViewController 

In CustomVCTransitionViewController.m, add the following lines of code to import the header files:

#import "CustomModalViewController.h"
#import "PresentingAnimationController.h"
#import "DismissingAnimationController.h"
#import 

Then insert the following methods to implement the action method of the Present button and the required methods of the protocol:

- (IBAction)didClickOnPresent:(id)sender {
    
    CustomModalViewController *modalVC = [self.storyboard instantiateViewControllerWithIdentifier:@"customModal"];
    
    
    modalVC.transitioningDelegate = self;
    
    modalVC.modalPresentationStyle = UIModalPresentationCustom;
    
    [self.navigationController presentViewController:modalVC animated:YES completion:nil];
}

#pragma mark - UIViewControllerTransitionDelegate -

- (id )animationControllerForPresentedController:(UIViewController *)presented presentingController:(UIViewController *)presenting sourceController:(UIViewController *)source
{
    return [[PresentingAnimationController alloc] init];
}

- (id )animationControllerForDismissedController:(UIViewController *)dismissed
{
    return [[DismissingAnimationController alloc] init];
}

When the button is tapped, the didClickOnPresent method will be invoked. Here we instantiate the modal view controller and set the transitioning delegate to the current view controller. We also set the modal presentation style to custom. (With the action method, remember to establish a connection between the Present button and the method in storyboard.)

As the class adopts the UIViewControllerTransitioningDelegate protocol, we implement the two required methods. The animationControllerForPresentedController: method returns the transition animator object to use when presenting the modal view controller. Conversely, the animationControllerForDismissedController: method provides the animator object for dismissing a view controller.

We haven’t created both animator classes yet. Now create a new class called PresentingAnimationController, set it as a subclass of NSObject and adopt the UIViewControllerAnimatedTransitioning protocol:

#import 
#import "POP.h"

@interface PresentingAnimationController : NSObject 

In PresentingAnimationController.m, add the following methods:

- (NSTimeInterval)transitionDuration:(id )transitionContext {
    return 0.5f;
}

- (void)animateTransition:(id )transitionContext {
    
    UIView *fromView = [transitionContext viewControllerForKey:UITransitionContextFromViewControllerKey].view;
    fromView.tintAdjustmentMode = UIViewTintAdjustmentModeDimmed;
    fromView.userInteractionEnabled = NO;
    
    UIView *toView = [transitionContext viewControllerForKey:UITransitionContextToViewControllerKey].view;
    toView.frame = CGRectMake(0,
                              0,
                              CGRectGetWidth(transitionContext.containerView.bounds) - 100.f,
                              CGRectGetHeight(transitionContext.containerView.bounds) - 280.f);
    CGPoint p = CGPointMake(transitionContext.containerView.center.x, -transitionContext.containerView.center.y);
    toView.center = p;
    
    [transitionContext.containerView addSubview:toView];
    
    POPSpringAnimation *positionAnimation = [POPSpringAnimation animationWithPropertyNamed:kPOPLayerPositionY];
    positionAnimation.toValue = @(transitionContext.containerView.center.y);
    positionAnimation.springBounciness = 10;
    [positionAnimation setCompletionBlock:^(POPAnimation *anim, BOOL finished) {
        [transitionContext completeTransition:YES];
    }];
    
    POPSpringAnimation *scaleAnimation = [POPSpringAnimation animationWithPropertyNamed:kPOPLayerScaleXY];
    scaleAnimation.springBounciness = 20;
    scaleAnimation.fromValue = [NSValue valueWithCGPoint:CGPointMake(1.2, 1.4)];
    
    [toView.layer pop_addAnimation:positionAnimation forKey:@"positionAnimation"];
    [toView.layer pop_addAnimation:scaleAnimation forKey:@"scaleAnimation"];
    
}

The first method defines the transition duration (i.e. 0.5 seconds). To animate the transition, we implement the animateTransition: method. Here we define how the transition animations are performed. We first retrieve the “fromView” involved in the transition using the viewControllerForKey: method of the transitionContext. Next, we retrieve the “toView”. Once you have these two views, you can apply any animations during the view transition. Here we apply two animations – position animation and scale animation. The position animation slides the view from the top of the screen to the center. The scale animation scales up the view a bit and then scales it back to the normal values.

Next, create a new class named DismissingAnimationController and adopt the UIViewControllerAnimatedTransitioning protocol:

#import 
#import 
#import 

@interface DismissingAnimationController : NSObject 

@end

Similarly, we create the dismissing animation by implementing the required method of the UIViewControllerAnimatedTransitioning protocol:

- (NSTimeInterval)transitionDuration:(id )transitionContext {
    return 0.5f;
}

- (void)animateTransition:(id )transitionContext {
    
    UIView *toView = [transitionContext viewControllerForKey:UITransitionContextToViewControllerKey].view;
    toView.tintAdjustmentMode = UIViewTintAdjustmentModeNormal;
    toView.userInteractionEnabled = YES;
    
    UIView *fromView = [transitionContext viewControllerForKey:UITransitionContextFromViewControllerKey].view;
    
    
    POPBasicAnimation *closeAnimation = [POPBasicAnimation animationWithPropertyNamed:kPOPLayerPositionY];
    closeAnimation.toValue = @(-fromView.layer.position.y);
    [closeAnimation setCompletionBlock:^(POPAnimation *anim, BOOL finished) {
        [transitionContext completeTransition:YES];
    }];
    
    POPSpringAnimation *scaleDownAnimation = [POPSpringAnimation animationWithPropertyNamed:kPOPLayerScaleXY];
    scaleDownAnimation.springBounciness = 20;
    scaleDownAnimation.toValue = [NSValue valueWithCGPoint:CGPointMake(0, 0)];
    
    [fromView.layer pop_addAnimation:closeAnimation forKey:@"closeAnimation"];
    [fromView.layer pop_addAnimation:scaleDownAnimation forKey:@"scaleDown"];
    
}

When dismissing the modal view, we apply two animations – close animation and scale down animation. By combining both animations, we make the modal view disappear or move off screen.

Go back to the CustomModalViewController.m, update the viewDidLoad method and implement the didClickOnClose method:

- (void)viewDidLoad {
    [super viewDidLoad];
    
    // Round corner
    self.view.layer.cornerRadius = 8.f; 
}

- (IBAction)didClickOnClose:(id)sender {
    [self dismissViewControllerAnimated:YES completion:nil];
}

Finally, establish a connection between the Close button with the didClickOnClose method in InterfaceBuilder.

Cool! It’s ready to test the app. Run it and test the view transition.

Summary

In this tutorial, I gave you an introduction of Facebook’s Pop framework. As you can see, the animation engine is pretty easy to use. If you understand the animation techniques covered in the tutorial, you should be able to create your own animation in your apps.

For your reference, you can download the complete Xcode project here. Or you can check out the project on Github.

What do you think about the tutorial? Leave me comment and share your thought.

Hello readers! iOS 8 is at the gates, as only a few weeks remain until the official release of the updated version of the operating system, and along with it, the release of the Swift programming language. So, as you understand, we are preparing to enter into a new era of the iOS SDK, where new wonderful technologies waiting for us to explore them! However, here at Appcoda we decided to dedicate one more tutorial to the existing SDK, using the Objective-C language. My next tutorials will focus on new iOS 8 technologies, and we’ll use the Swift language. Regarding this one, there were many candidate topics to write for, but ultimately the chosen one is about the Gesture Recognizers. So, let’s see a few things about them.

A gesture recognizer is actually an object of the abstract class UIGestureRecognizer. Such an object is related to a view, and monitors for predefined gestures made on that view. Going one level deeper, I would say that gestures are actually touches and movements of one or more fingers that happen on a specific area of the screen, where a view of interest exists there. In the early versions of iOS SDK, gestures recognizers were not provided to developers, so implementing such ways of interaction required a lot of manual work. Thankfully, Apple wrapped up all that manual work and gave it to developers as a single tool, and that way working with gestures became a really easy part of the iOS programming.

The UIGestureRecognizer class as an abstract one, it can’t be used directly. There are specific subclasses of it that are provided for usage, and each one of them deals with a specific kind of gesture. Let’s go through them for a while and let’s see what the respective gestures are for:

1. UITapGestureRecognizer: This class regards the tap gestures made on a view. It can be used to handle single or multiple taps, either with one or more fingers. Tapping is one of the most usual gestures that users make.
2. UISwipeGestureRecognizer: Another important gesture is the swipe, and this class exists just for it. Swiping happens when dragging a finger towards a direction (right, left, top and down). A characteristic example of the swipe gesture exists on the Photos app, where we use our fingers to slide from one photo to another.
3. UIPanGestureRecognizer: The pan gesture is actually a drag gesture. It’s used when it’s needed to drag views from one point to another.
4. UIPinchGestureRecognizer: When you view photos on the Photos app and you use your two fingers to zoom in or out to a photo, then you perform a pinch gesture. As you understand, pinching requires two fingers. An object of this class is usually handy to change the transform of a view, and more specifically its scale. Using pinch gestures for example, you can implement zoom in and out to photos on your own apps.
5. UIRotationGestureRecognizer: In accordance to the previous gesture, rotation is used to rotate a view using two fingers.
6. UILongPressGestureRecognizer: An object of that class monitors for long press gestures happening on a view. The pressing must last long enough in order to be detected, and the finger or fingers should not move a lot around the pressed point otherwise the gesture fails.
7. UIScreenEdgePanGestureRecognizer: This one is similar to the swipe gesture, but with a great difference: The finger movement should always begin from an edge of the screen.

All gesture objects perform an action once a valid gesture is detected. This is either an IBAction method in case the gesture is added through Interface Builder, or a private or public method in case of programmatic implementation. When an action method is called after a gesture has happened, the gesture object always sends itself in case additional info is required when handling the gesture. It’s not necessary to declare the action methods in order to contain the gesture object to their signatures, but personally I recommend you to do so as a better programming practice. For example, both of the following method signatures are valid:

-(void)handleMyTapGesture;
-(void)handleMyTapGestureWithGestureRecognizer:(UITapGestureRecognizer *)gestureRecognizer;

In the second case, the gestureRecognizer argument can provide you with extra info you might need, such as the view that the gesture took place on. In my examples in this tutorial, I’ll use the second method signature when declaring methods for handling gestures.

Looking now from the point of views, a view can contain more than one gesture recognizers. For instance, you can add both pinch and rotation gesture recognizers to an imageview, so you can zoom in/out and rotate the presented image. However, just one gesture at a given time can occur. Gesture recognizers that are related to a view are added to an array of that view, so you can access them as you would do for any object to a normal array. I guess though that you will rarely need to access a gesture recogniser object in such way.

As you will see next to this tutorial, working with gesture recognizers is easy enough, and it consists of a pretty awesome way to provide interaction to your app without using the traditional subviews for performing actions (such as buttons). Before we continue, I should mention that we are going to focus our attention to the first five gesture recognizer classes, while for the last two we’ll just say a couple of words about each one of them. That’s because they have great similarities to other classes, so it would be pointless to discuss about the same stuff twice. Furthermore, I said previously that the gesture recognizers can be added in two ways to views: Either using the Interface Builder, or programmatically. In here I am going to follow the second path, and do everything in code. If you want to read more theoretical stuff about gesture recognizers, then feel free to pay a visit to the official documentation provided by Apple.

Demo App Overview

The way that we are going to work in this tutorial is straightforward enough. First of all, we will create a tabbed application, which will contain five tabs. Each tab will match to a single view controller, and each view controller will be used to demonstrate a new gesture recognizer. Furthermore, we will create five view controller classes to implement the necessary code for every gesture recognizer that we will meet.

The gesture recognizers that we are going to work with are in the following order:

1. Tap gesture recognizer
2. Swipe gesture recognizer
3. Pan gesture recognizer
4. Pinch gesture recognizer
5. Rotation gesture recognizer

For each one of them, we are going to create one or more test views, and then we will implement the necessary code that will make the respective gestures properly work. So, I could say that the demo application of this tutorial will be parted by many small examples, where each one of them targets for the study of a single gesture recognizer.

App Creation and Setup

Let’s begin by creating a new project in Xcode. Launch it, and in the first step of the guide select the Tabbed Application as the template for your project.

Next, set the GesturesDemo as the name of the project, and make sure that the iPhone is the selected device.

Get finished with the guide by selecting a directory to store the project, and you are ready.

Now that the project has been prepared, let’s setup our interface so we can start working with the gesture recognizers at once later. Click on the Main.storyboard file, and let the Interface Builder appear. As you notice, there are two view controllers connected to the tab bar controller already, so we need to add three more. From the Object Library, drag and drop three new View Controller objects to the IB canvas.

Before we connect the view controllers to the tab bar, we must create the necessary view controller classes. Begin by selecting the FirstViewController and SecondViewController classes (both the .h and .m files) on the Project Navigator, and then hit the Delete key on your keyboard. We are not going to use these files, we will create new classes for the gesture recognizers that we’ll work with.

In the confirmation dialog box that shows up, click on the Move to Trash button.

Next, start adding the new classes to the project. The procedure that will be presented right next should be repeated five times in total, until all the necessary classes to have been added to the project. Let’s see everything in details for the first one:

Open the File > New > File… menu, and select to create a new Objective-C class in the guide that appears.

Move to the next step, and in the Subclass of field, make sure that the set value is the UIViewController one. If not, then do it now. Next, name the new class by setting the TapViewController value in the Class field.

Proceed and in the last step click on the Create button to get finished with the guide and let Xcode create and add the new class to the project.

For the next view controllers that you will create, set the following class names:

• SwipeViewController
• PanViewController
• PinchViewController
• RotationViewController

After you have added all of them, here’s how your Project Navigator should look like:

Now we can return to Interface Builder. Firstly, make sure that the Utilities pane is on, because you will need it. Next, select the first view controller scene (let’s start from top to bottom), and show the Identity Inspector in the Utilities pane. In there, in the Class field of the Custom Class section, set the name of the first class you added to the project, the *TapViewController:

Repeat the above step until you set all the custom classes to the remaining view controllers.

Our next move is to connect all the view controllers to the tab bar controller. This is can be done very easily, if you select the tab bar controller and then you open the Connections Inspector to the Utilities pane. In the Triggered Segues section, click on the circle on the right of the view controllers option and drag on top of every not connected view controller, and proceed by connecting them one by one.

Once all the connections have been made, you can set the titles of the bar button items of the view controllers. Starting from the top to bottom once again, select the tab bar item and then open the Attributes Inspector in the Utilities pane. In there, set the proper tab bar title for each view controller, and set the first as the image to all view controllers.

The tab bar item titles are in order:

• Tap
• Swipe
• Pan
• Pinch
• Rotation

Finally, remove the existing content from the first two pre-made view controllers.

Everything is ready now. Optionally, you can add a label as a title to each view controller. If you would like to do that too, then drag a UILabel object to each view controller and set the following attributes:

• Frame: X=20, Y=40, Width=280, Height=40
• Font: System Bold, 20pt
• Alignment: Center

The texts of the labels should be (following the same order as before):

• Tap Gesture
• Swipe Gesture
• Pan Gesture
• Pinch Gesture
• Rotation Gesture

Now that we have setup the base that we’ll work on, we can dive directly in the heart of our topic. However, we’ll return several times here in Interface Builder with an aim to create the needed test views for each gesture recognizer.

Tap Gesture Recognizer

We begin the real exploration of our today’s topic with the tap gesture recognizer, as you assume from the title of this section. In the previous part, you added all the needed view controllers to the project and you connected them with the tab bar controller. Now in this part, we are going to add a view object (UIView) to the Tap view controller scene, which we will use as a test view in order to do our work in code.

At first, make sure that you have the Interface Builder still on by clicking on the Main.storyboard file in the Project Navigator. Next, bring the Tap view controller scene right in front of you, and then grab an UIView object from the Object Library and drag it to the scene’s view. Set the following properties to that view:

• Frame: X=110, Y=234, Width=100, Height=100
• Background Color: R=215, G=116, B=52 (or any other color you like)

Now that the view is in place, we must create an IBOutlet property and connect it with the view. Open the TapViewController.h file and declare the following property:

@interface TapViewController : UIViewController

@property (weak, nonatomic) IBOutlet UIView *testView;

@end

Back on the Main.storyboard file again, go to the Document Outline pane, and Ctrl-Drag from the Tap view controller scene object to the view, as shown below:

In the black popup window, just select the testView property, and you are all set.

Note: We are going to use the above procedure for adding test view objects and for connecting them with IBOutlet properties to the upcoming chapters as well. However, I’m not going to get into much detail again, so if you need you may return back here to follow the steps that were just described.

Now, open the TapViewController.m file. The first thing we must do, is to create an object of the UITapGestureRecognizer class, which we’ll then add to the testView view. Actually, we will create two objects of that class, one for testing single taps, and one for testing double taps. Our work will take place initially to the viewDidLoad method, so let’s get started with the first one.

The next code segment clearly displays how we initialize a gesture recognizer object:

UITapGestureRecognizer *singleTapGestureRecognizer = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(handleSingleTapGesture:)];

Using that way, you can initialize any object of the gesture recognizer subclasses, as long as you replace the name of the class. As you see, we specify a target and an action. The action in this case is a private method that we are about to create in a few seconds.

To assign the above gesture recognizer to our test view, here’s what we should write:

[self.testView addGestureRecognizer:singleTapGestureRecognizer];

The addGestureRecognizer: method is the one and standard way of adding a gesture recognizer object to a view.

Go now to the private section of the interface, and declare the private method we set to the gesture recognizer as follows:

@interface TapViewController ()

-(void)handleSingleTapGesture:(UITapGestureRecognizer *)tapGestureRecognizer;

@end

As I said in the introduction, the gesture recognizer object passes itself to the selector method, and by using this method signature we can use it later in the implementation. We could omit the parameter, but that’s something that I am intentionally going to avoid to the whole tutorial.

Let’s move forward to the method’s definition now. What are we going to do there? Well, nothing hard especially. We will just double the width of the test view when we tap on it once, and we will revert the original width value upon the second tap (an so on). Let’s see it:

-(void)handleSingleTapGesture:(UITapGestureRecognizer *)tapGestureRecognizer{
    CGFloat newWidth = 100.0;
    if (self.testView.frame.size.width == 100.0) {
        newWidth = 200.0;
    }

    CGPoint currentCenter = self.testView.center;

    self.testView.frame = CGRectMake(self.testView.frame.origin.x, self.testView.frame.origin.y, newWidth, self.testView.frame.size.height);
    self.testView.center = currentCenter;
}

The implementation is really simple. At first we check if the initial width of the view is equal to 100.0 points, and if so we make it 200.0, otherwise we keep the initial assigned value (100.0). Next, we keep to a CGPoint structure variable the current center point, we change the width of the view and we center it again.

It’s now time to try out the tap gesture. Run the app, and once it gets launched to either the Simulator or a device, make sure that you are on the first tab. Tap on the view once, and its size will change. Tap once again, and watch it going back to its original state. Simple and cool?

Let’s go back to our work again. As I have already said, a tap gesture can be performed with one or more fingers, and the gesture could require one or more taps. So, let’s see one more example, where this time we will “tell” to the gesture recognizer object that we want two taps to happen, and that two fingers are required in order to perform the predefined action. In the viewDidLoad method, add the next lines:

- (void)viewDidLoad
{
    ...

    UITapGestureRecognizer *doubleTapGestureRecognizer = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(handleDoubleTapGesture:)];
    doubleTapGestureRecognizer.numberOfTapsRequired = 2;
    doubleTapGestureRecognizer.numberOfTouchesRequired = 2;
    [self.testView addGestureRecognizer:doubleTapGestureRecognizer];
}

Here we initialize a new tap gesture recognizer object, and we specify another action method that we’ll implement in a while. The new thing here though is the use of the two properties that allow us to set the number of the required taps and touches (or in other words, the number of fingers). Finally, we add the recognizer object to the testView view.

Note that our test view now contains two gesture recognizer objects.

Now, let’s get finished with the remaining tasks. Go to the private interface section and declare the new private method:

@interface TapViewController ()

...

-(void)handleDoubleTapGesture:(UITapGestureRecognizer *)tapGestureRecognizer;

@end

In its definition, we will change both the width and height of the view by doubling its size. We will follow the same logic as before:

-(void)handleDoubleTapGesture:(UITapGestureRecognizer *)tapGestureRecognizer{
    CGSize newSize = CGSizeMake(100.0, 100.0);
    if (self.testView.frame.size.width == 100.0) {
        newSize.width = 200.0;
        newSize.height = 200.0;
    }

    CGPoint currentCenter = self.testView.center;

    self.testView.frame = CGRectMake(self.testView.frame.origin.x, self.testView.frame.origin.y, newSize.width, newSize.height);
    self.testView.center = currentCenter;
}

Run the app once again. This time, double-tap and use two fingers, otherwise the gesture will fail. Also, try both of the gesture recognizers we created here:

What you have seen in this part of the tutorial, is more or less the way you work with all the gesture recognizers, even though each one of them has something special about it. For now, we have successfully managed to implement and use tap gestures, and that’s quite important!

Swipe Gesture Recognizer

Another quite common and cool gesture recognizer is the swipe. Swiping can be done towards any of the four basic directions (right, left, top, bottom) but not in a diagonal way. The UISwipeGestureRecongnizer class provides a method that allows us to specify the direction, and if none is set, then the right direction is used by default. A swipe gesture recognizer object can monitor and trigger actions for one direction only. That means that if you want a view in your application to support swiping towards two or more directions, then you must create two or more gesture recognizer objects respectively. Beyond all that, note that the action that’s been triggered by the swipe movement starts right after the swiping is over (when the finger actually stops sliding).

In this part we are going to work with the SwipeViewController class that we previously added to the project. In the respective scene in the Interface Builder, we are going to add three view (UIView) objects. The width of all three views will be equal to the screen’s width. The first view will be placed on-screen, while the other two views will be placed at the left and the right side of the first view, and obviously will be out of the visible area. Our goal is to make these views move horizontally using swipe gestures, and to let the hidden views to be revealed by sliding either left or right.

Let’s see everything step by step, and let’s start by opening the Main.storyboard file. Go to the Swipe view controller scene and add the next three view objects by defining at the same time the frame and background color properties:

First View

• Frame: X=0, Y=234, Width=320, Height=100
• Background Color: R=215, G=116, B=52

Second View

• Frame: X=320, Y=234, Width=320, Height=100
• Background Color: Black Color

Third View

• Frame: X=-320, Y=234, Width=320, Height=100
• Background Color: R=0, G=128, B=0

Next, create the following IBOutlet properties to the SwipeViewController.h file:

@interface SwipeViewController : UIViewController

@property (weak, nonatomic) IBOutlet UIView *viewOrange;

@property (weak, nonatomic) IBOutlet UIView *viewBlack;

@property (weak, nonatomic) IBOutlet UIView *viewGreen;

@end

After having done so, go back to the Swipe view controller scene, and make the proper connections. Obviously, the viewOrange property matches to the first view, the viewBlack property matches to the second view, and the viewGreen property matches to the third view.

Now, let’s head to the SwipeViewController.m file, and let’s start creating the gesture recognizers we need one by one. Go to the viewDidLoad method, and initialize such an object for the first view (the one in the middle being in the visible area of the screen). Let’s see that:

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view.

    UISwipeGestureRecognizer *swipeRightOrange = [[UISwipeGestureRecognizer alloc] initWithTarget:self action:@selector(slideToRightWithGestureRecognizer:)];
    swipeRightOrange.direction = UISwipeGestureRecognizerDirectionRight;

}

What we have done with this segment is quite clear: Upon the object initialization we specify the action method that should be called when the swiping will occur, and then we set the direction of the swipe gesture towards right.

Now, let’s create one more gesture recognizer object that will enable us to swipe towards left:

- (void)viewDidLoad
{
    ...

    UISwipeGestureRecognizer *swipeLeftOrange = [[UISwipeGestureRecognizer alloc] initWithTarget:self action:@selector(slideToLeftWithGestureRecognizer:)];
    swipeLeftOrange.direction = UISwipeGestureRecognizerDirectionLeft;
}

Easy, right? What we have only left to do, is to add both of these gesture recognizers to the viewOrange view exactly as shown below:

- (void)viewDidLoad
{
    ...

    [self.viewOrange addGestureRecognizer:swipeRightOrange];
    [self.viewOrange addGestureRecognizer:swipeLeftOrange];
}

The action methods we set to the recognizers above, should perform one simple thing: To slide all views either towards left or towards right, so when a view leaves the visible area of the screen, another one to be appeared. Let’s declare them first and we’ll do the implementation next. In the private interface section add the next lines:

@interface SwipeViewController ()

-(void)slideToRightWithGestureRecognizer:(UISwipeGestureRecognizer *)gestureRecognizer;

-(void)slideToLeftWithGestureRecognizer:(UISwipeGestureRecognizer *)gestureRecognizer;

@end

Let’s see the implementation of the first method straight away:

-(void)slideToRightWithGestureRecognizer:(UISwipeGestureRecognizer *)gestureRecognizer{
    [UIView animateWithDuration:0.5 animations:^{
        self.viewOrange.frame = CGRectOffset(self.viewOrange.frame, 320.0, 0.0);
        self.viewBlack.frame = CGRectOffset(self.viewBlack.frame, 320.0, 0.0);
        self.viewGreen.frame = CGRectOffset(self.viewGreen.frame, 320.0, 0.0);
    }];
}

As you notice, when we swipe towards right, we want the X origin point of each view to be increased by 320.0 pixels and manage that way to move our views to the right. We make this movement look natural simply by wrapping everything into an animation block. Notice also that the movement speed depends on the animation duration, so if you want a slower the slide effect you should increase the animation duration, while if you need them to move faster, then just decrease the duration.

The second action method is going to be similar to this one, with one difference only: The offset on the X axis will be a negative number (equal of course to 320.0 pixels), so the views move to the left. Let’s see this implementation as well:

-(void)slideToLeftWithGestureRecognizer:(UISwipeGestureRecognizer *)gestureRecognizer{
    [UIView animateWithDuration:0.5 animations:^{
        self.viewOrange.frame = CGRectOffset(self.viewOrange.frame, -320.0, 0.0);
        self.viewBlack.frame = CGRectOffset(self.viewBlack.frame, -320.0, 0.0);
        self.viewGreen.frame = CGRectOffset(self.viewGreen.frame, -320.0, 0.0);
    }];
}

Run the app once again, and this time show the contents of the second tab. Swipe towards right or left, and watch the views slide in and out using an animated fashion. However, when a new view appears on-screen, you’ll notice that no swipe gesture works any more. Why that happens?

The answer is simple and lies in the fact that we haven’t created and added swipe gesture recognizers to the other two views. So, why don’t we do that now, and then see if it works?

Go back to the viewDidLoad method, and start by adding the next segment:

- (void)viewDidLoad
{
    ...    

    UISwipeGestureRecognizer *swipeRightBlack = [[UISwipeGestureRecognizer alloc] initWithTarget:self action:@selector(slideToRightWithGestureRecognizer:)];
    swipeRightBlack.direction = UISwipeGestureRecognizerDirectionRight;
    [self.viewBlack addGestureRecognizer:swipeRightBlack];
}

With these commands, we created a new swipe gesture recognizer for a gesture towards right for the black coloured view, and we used the already implemented slideToRightWithGestureRecognizer : as the action method.

Let’s do the same for the green coloured view, but this time we must set the left direction:

- (void)viewDidLoad
{
    ...

    UISwipeGestureRecognizer *swipeLeftGreen = [[UISwipeGestureRecognizer alloc] initWithTarget:self action:@selector(slideToLeftWithGestureRecognizer:)];
    swipeLeftGreen.direction = UISwipeGestureRecognizerDirectionLeft;
    [self.viewGreen addGestureRecognizer:swipeLeftGreen];
}

Okay, let’s give it another try. This time, everything works great!

Keep in mind that for every swipe gesture you want to support, you must create a new gesture recognizer object. Creating just one object and adding it to more than one view isn’t going to work. If you really want a proof of that, simply go to the viewDidLoad method and add the swipeRightOrange and the swipeLeftOrange gesture recognizers to the other two views respectively. Run the app again, and then swipe your finger (or using the mouse on Simulator) just like before. Unfortunately, this time nothing will work, so set everything back to its original state.

Pan Gesture Recognizer

In the last two sections we saw two important gesture recognizers that can give great interaction to your apps. We will continue here by studying another gesture recognizer, the pan or in other words drag. This gesture is handy when you want to allow your users to drag views around the screen. In this part, except for implementing the necessary code that will enable our app to support the pan gesture, we will meet a special method of the UIPanGestureRecognizer class, named velocityInView:. This method returns a CGPoint value, and informs us about how many points per second the dragged view travels in both the horizontal and vertical axis while dragging. This information could be useful in some cases, so we will see how to access it.

Just like before, we’ll start by adding a test view to the Interface Builder. Go to the Main.storyboard file, and then drag a view (UIView) object to the Pan view controller scene. Set the next two attributes of it:

• Frame: X=110, Y=234, Width=100, Height=100
• Background Color: R=215, G=116, B=52 (or any other color you like)

Next, go to the PanViewController.h file and declare an IBOutlet property that you’ll later connect to that view:

@interface PanViewController : UIViewController

@property (weak, nonatomic) IBOutlet UIView *testView;

@end

Return to the Main.storyboard file, and connect the IBOutlet property to the view.

Once you have finished working with the Interface Builder, click on the PanViewController.m file in the Project Navigator. The first step we should do, is to create a pan gesture recognizer and add it to our test view. There’s nothing difficult in this case, so let’s see it:

- (void)viewDidLoad
{
    ...

    UIPanGestureRecognizer *panGestureRecognizer = [[UIPanGestureRecognizer alloc] initWithTarget:self action:@selector(moveViewWithGestureRecognizer:)];
    [self.testView addGestureRecognizer:panGestureRecognizer];
}

Now, let’s declare and implement the method we set as the action that should be taken when the pan gesture will happen. In the private interface section, add this:

@interface PanViewController ()

-(void)moveViewWithGestureRecognizer:(UIPanGestureRecognizer *)panGestureRecognizer;

@end

As I have already said, what we want to do here is to drag the test view while we move our finger on the screen. The easiest approach to that would be to update the center point of the view as long as the panning occurs. Let’s see how that is translated into code:

-(void)moveViewWithGestureRecognizer:(UIPanGestureRecognizer *)panGestureRecognizer{
    CGPoint touchLocation = [panGestureRecognizer locationInView:self.view];

    self.testView.center = touchLocation;

}

Every gesture recognizer contains a method named locationInView:. This method returns a CGPoint value representing the point of the view that the user touched. In our case, by calling this method we manage to get the touched point during dragging, and to make our app aware of the finger’s movement. So, what we only need is to set that touch location as the value for the center point of the test view, and that’s exactly we perform using the second command above.

Run the app now and place your finger or the mouse pointer on the test view. Then start dragging around and notice how the view follows the movement you make.

The approach I presented above is simple for the sake of the tutorial. In a real application, you might want to enrich the movement of the view by adding acceleration or deceleration when you start or stop dragging, or anything else you need. It’s up to you to apply the proper logic in the action method you implement.

At the beginning of this section, I said that there is a special method of the UIPanGestureRecognizer class named velocityInView:. Up to this point we totally ignored it, but now we’ll see how we can access it and get the data it provides. For the sake of the demo, return to the Interface Builder by clicking on the Main.storyboard file. Locate the Pan view controller scene, and add two labels with the following attributes:

Label #1

• Frame: X=20, Y=445, Width=280, Height=21
• Text: Nothing (empty)
• Font size: 14pt

Label #2

• Frame: X=20, Y=479, Width=280, Height=21
• Text: Nothing (empty)
• Font size: 14pt

As you may suspect, we are going to use these two labels to display the velocity in the horizontal and vertical axis respectively. But before we do so, we must create and connect two IBOutlet properties to these labels. So, open the PanViewController.h file and add the next two lines:

@interface PanViewController : UIViewController

...

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

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

@end

Go back to the Interface Builder, and perform the appropriate connections.

Now, open the PanViewController.m file, and go to our private action method named moveViewWithGestureRecognizer:. We will add some code here that will enable us to get the velocity of the drag as a CGPoint value, and then we will extract the velocity on each axis out of this one. Remember that the velocity is expressed in points per second. Let’s see the method:

-(void)moveViewWithGestureRecognizer:(UIPanGestureRecognizer *)panGestureRecognizer{
    ...    

    CGPoint velocity = [panGestureRecognizer velocityInView:self.view];

    self.horizontalVelocityLabel.text = [NSString stringWithFormat:@"Horizontal Velocity: %.2f points/sec", velocity.x];
    self.verticalVelocityLabel.text = [NSString stringWithFormat:@"Vertical Velocity: %.2f points/sec", velocity.y];

}

The value returned by the velocityInView: method is stored to a CGPoint structure. Then by simply accessing the X and Y properties of that structure, we manage to get the horizontal and vertical velocity. To keep things simple here, we just display these values, but in a real application the velocity would be useful if only you would perform calculations based on it.

By running the app again you can see how “fast” the test view is moved around the screen while you drag it.

Pinch Gesture Recognizer

The pinch gesture is useful for changing the transform of a view by scaling it up or down. The most characteristic example of that gesture can be found in the Photos app, where you pinch to zoom in and out. Here we won’t add an image view with an image in it, we’ll just use a simple view. However, what we’ll do here apply to all views (including image views) in which you want to change their scale value. The great difference that the pinch gesture has compared to the previous gesture recognizers, is the fact that it requires two fingers to be used in order to perform the gesture.

As we did in the previous sections, we will begin by adding a test view to the Interface Builder. On the Project Navigator, click on the Main.storyboard file and then locate the Pinch view controller scene. Next, from the Object Library drag a view object (UIView) to the canvas, and set the next attributes:

• Frame: X=85, Y=209, Width=150, Height=150
• Background Color: R=215, G=116, B=52 (or any other color you like)

Now open the PinchViewController.h file, and declare an IBOutlet property:

@interface PinchViewController : UIViewController

@property (weak, nonatomic) IBOutlet UIView *testView;

@end

Finally, in the Interface Builder connect that property to the test view you just added.

Similarly to the previous cases, we’ll begin the implementation in the viewDidLoad method in the PinchViewController.m file. What we only have to do is to initialize a pinch gesture recognizer object, and then add it to the test view:

- (void)viewDidLoad
{
    ...

    UIPinchGestureRecognizer *pinchGestureRecognizer = [[UIPinchGestureRecognizer alloc] initWithTarget:self action:@selector(handlePinchWithGestureRecognizer:)];
    [self.testView addGestureRecognizer:pinchGestureRecognizer];
}

Now, we must declare the handlePinchWithGestureRecognizer: method, and then define it. First, go to the private class section:

@interface PinchViewController ()

-(void)handlePinchWithGestureRecognizer:(UIPinchGestureRecognizer *)pinchGestureRecognizer;

@end

According to what I said in the beginning of this part, we will modify the transform of the test view by changing the scale value. That action will result in a zoom in/out effect, and as you’ll see, it’s just a matter of a single line:

-(void)handlePinchWithGestureRecognizer:(UIPinchGestureRecognizer *)pinchGestureRecognizer{
    self.testView.transform = CGAffineTransformScale(self.testView.transform, pinchGestureRecognizer.scale, pinchGestureRecognizer.scale);

}

In this example we know which is the view that the pinch gesture was applied to (the testView view), so we access it directly. However, there will be times that you will need to access the pinched view in a more generic way. In that case, you can avoid the direct usage of the the view that was pinched as shown above, if you simply use the view property of the pinchGestureRecognizer parameter object. This property is actually the view that the pinch gesture happened to. Therefore, the above command could be written as follows too:

pinchGestureRecognizer.view.transform = CGAffineTransformScale(pinchGestureRecognizer.view.transform, pinchGestureRecognizer.scale, pinchGestureRecognizer.scale);

Now we are almost ready to test it. I’m saying almost, before we need to add one more command that it’s not obvious at the beginning, but you understand that you need it after having tested the above at least once. So, complete the above method by adding this:

-(void)handlePinchWithGestureRecognizer:(UIPinchGestureRecognizer *)pinchGestureRecognizer{
    ...

    pinchGestureRecognizer.scale = 1.0;
}

It’s necessary to reset the scale value of the pinch gesture recognizer object, otherwise the result won’t be the expected one; the scaling will look chaotic. With this simple line, we manage to achieve a smoother behaviour.

Now you can run the app and test the pinch gesture. Act as you do to photos when zooming in and out, and see how our test view reacts to your movements.

Rotation Gesture Recognizer

The rotation gesture recognizer has great similarities to the pinch gesture recognizer, as it requires two fingers in order for the gesture to be successful, and it changes the transform of the view that is applied to by modifying its rotation. Usually, the rotation gesture is used in combination to other gestures, but not only.

In this part we are going to perform almost the same steps we did in the pinch gesture recognizer section. Therefore, open the Interface Builder, and go to the Rotation view controller scene. From the Object Library, drag and drop a view to the canvas with the following attributes:

• Frame: X=85, Y=209, Width=150, Height=150
• Background Color: R=215, G=116, B=52 (or any other color you like)

Next, in the RotationViewController.h file declare the following IBOutlet property…

@interface RotationViewController : UIViewController

@property (weak, nonatomic) IBOutlet UIView *testView;

@end

… and then return to the Interface Builder to connect it to the view.

Going to the RotationViewController.m file now, head to the viewDidLoad directly. As we did to all the previous parts, our coding work will start at this point. Here, we will just create a new rotation gesture recognizer object and we will add it to the test view.

- (void)viewDidLoad
{
    ...

    UIRotationGestureRecognizer *rotationGestureRecognizer = [[UIRotationGestureRecognizer alloc] initWithTarget:self action:@selector(handleRotationWithGestureRecognizer:)];
    [self.testView addGestureRecognizer:rotationGestureRecognizer];
}

As always, our next step is to declare the private method:

@interface RotationViewController ()

-(void)handleRotationWithGestureRecognizer:(UIRotationGestureRecognizer *)rotationGestureRecognizer;

@end

Finally, let’s implement it. Here, we will use the CGAffineTransformRotate method to change the rotate value of the transform of the test view. As you will see in the next code, the rotation property of the rotationGestureRecognizer gets its initial value so as to avoid unexpected behaviour.

-(void)handleRotationWithGestureRecognizer:(UIRotationGestureRecognizer *)rotationGestureRecognizer{
    self.testView.transform = CGAffineTransformRotate(self.testView.transform, rotationGestureRecognizer.rotation);

    rotationGestureRecognizer.rotation = 0.0;
}

Run the app now, and make sure to select the last tab of the tab bar controller. Then use two fingers to rotate the view to either a clockwise or counter-clockwise direction.

Other Gesture Recognizers

Beyond the gesture recognizers we met in the previous parts of the tutorial, there are two more that I’m going to just mention. We won’t see their details for two reasons: They are used more rarely and have similarities to gesture recognizers that we have already seen. So, let’s go through them shortly.

The first one is the long press gesture recognizer, and the respective class is the UILongPressGestureRecognizer*. As its name suggests, an object of that class monitors for press on a view that lasts for a some period, and not as long as a tap lasts. This class contains three important properties:

• minimumPressDuration: With this one, you specify the minimum time period that should elapse until the gesture to be considered valid.
• numberOfTouchesRequired: By using this property, you specify how many fingers are required for the gesture. Usually just one finger is fine, but it’s up to you to decide.
• allowableMovement: This property defines an area that the fingers should move during pressing. When using that gesture, the fingers must remain as stable and steady to the touch point as possible, otherwise the gesture fails.

So, if you want to use that gesture recognizer, always keep in mind that you must set valid values to the above properties.

The second gesture recognizer that I will just mention, is the screen edge pan gesture recognizer. The UIScreenEdgePanGestureRecognizer class is new in iOS 7, and it works just like the swipe gesture recognizer, with one great difference though: The finger movement should begin near the edge of the screen. An example of this one can be found in the Safari app, where you can move your finger from the left edge of the screen towards right to go to the previous page. Also, navigation controller supports this gesture recognizer by default. There’s one special property that should be set before this gesture recognizer is used, named edges. Using it, you must specify the edge from which the gesture should begin.

Summary

When there is a lack of experience in working with gesture recognizers, then it’s possible to look intimidating to many developers. However, as you have seen in this tutorial, this is more than a 100% false. Dealing with gesture recognizers is more than easy and quite straightforward. When used in applications, they attach a more advanced level of user interaction and user experience ultimately. Each example of this tutorial has been really simple, but that’s what exactly what you need to know even when developing larger applications. Anyway, if you are new to all this, or if you have been feeling uncomfortable with gesture recognizers, then I really hope to have helped you to understand them. Don’t be scared to add gestures to your apps, and of course, experiment as much as possible. Lastly, use the comments area to share your thoughts with us, or just… make a gesture!

For your reference, you can download the complete Xcode project from here.

In programming, one of the most commonly accepted facts is that the flow of a program depends on the value of the various variables and properties you use. You just have to think how many times during an application development you have to check for your properties’ values, and based on them to drive the execution of the code to one or another way. Even more, think of how many times you need to check if an object has been added to an array, or if it has been removed from it. So, being aware of the changes that happen to the properties of your classes is a vital part of the programming process.

There are various ways that let us be notified when a property gets changed. For example, if you have a method to set a property’s value, or you just override a setter method, you can send a notification (NSNotification) to notify an observer about that change, and then perform the proper actions based on the value that was set. If you are familiarized with notifications, then using them would not be a problem at all if you would want to use them for being aware about changes in properties, but the truth is that doing so for a great number of properties would require to send and observe for a great number of notifications as well, and that could lead to a lot of extra code writing.

Nevertheless, there is a much better way to observe for changes in properties, and Apple uses it a lot in its own software. That way is not used a lot by programmers because it seems hard to be learnt, however this is not true. Once you get to know it, you’ll probably love it and you’ll see that it’s much effortless and easier to track down changes on single properties or collections, such as arrays. This method is called Key-Value Observing, but is mostly known as KVO.

Key-Value Observing (KVO) is related directly to another powerful and important mechanism, named Key-Value Coding, or KVC. Actually, any property you want to observe for changes must be Key-Value Coding compliant, but we will talk more about that later. The important thing for now is to make clear that both of them provide a really powerful and efficient way to write code, and knowing how to handle them can definitely turn you into a more skilled and advanced programmer.

My goal in this tutorial is to walk you through the basics of both of them, and to show you step by step how they can be used. Covering all the aspects regarding these topics in one tutorial is not possible to happen, however after you have finished this one you will be able to manage them efficiently, and you will know what to look for if you need more details on them.

Before we take off and start examining their insides, I should necessarily mention that we will begin our journey from the Key-Value Coding mechanism. It’s necessary to know what it is and how it is used before we proceed to the Key-Value Observing mechanism, as the first is prerequisite for the second. So, if you are ready, let’s get started!

Demo App Overview

As always, this section is dedicated to the description of what the demo app is all about. So, I will start talking about it, highlighting a special characteristic the app will have. That is the fact that we won’t do any visual work at all, neither we will work with the Simulator or a device. Actually, the results of our implementation will be displayed on the console only.

Being more detailed, the contents of this tutorial are best suited to a command line tool application, as our topic concerns a clearly programming concept, for which we won’t create one sample app from scratch. Instead, we will be moving by implementing many small examples that demonstrate exactly the point of each discussed aspect of our topic, and we will use NSLog commands to output the results of our work. Nevertheless, we are still going to create a single view iOS application, but we’ll use no views or subviews to input and output any kind of data. The default view controller’s view will just remain empty.

The reason that made me choose an empty iOS application instead of a command line application is simple: I want you to feel comfortable by working to a familiar environment. KVC and KVO are surely new concepts for many of you, so I would like you to focus on these only. I wouldn’t like to distract you by making you to work for first time to a command line application. Methods like viewDidLoad, viewWillAppear:, etc., are definitely much more familiar to you (even though I must admit that I would prefer to create a command line app).

So, as I said we will be using only NSLog commands to output the results of our work. Besides that, we are going to create a couple of classes for the sake of the tutorial. The first one will exist for demonstration reasons only, while the second class can be used as a reusable code to your own apps. Generally speaking, by keeping things simple, it will be easier for you to get the point of the Key-Value Coding and Key-Value Observing.

Creating the Sample App

So, the first step is to create a new project, therefore go and launch Xcode and select to create a new project. To the guide that appears, select the Single View Application template, in the Application category under the iOS section.

Proceed to the next step, and in the Product Name field set the KVCODemo name. Leave everything else as it is, and go to the last step, where you should choose a directory to save the project, and you’re done.

The project is now ready!

Key-Value Coding

Here is the definition of the Key-Value Coding according to Apple’s official documentation:

Key-value coding is a mechanism for accessing an object’s properties indirectly, using strings to identify properties, rather than through invocation of an accessor method or accessing them directly through instance variables.

What does this mean? Well, let’s see it through some simple examples:

Let’s suppose that we have a property named firstname, and we want to assign the value John to it. Normally, what we would write in code to do it is this:

self.firstname = @"John";

or this:

_firstname = @"John";

Quite familiar, right? Now, using the KVC mechanism the above assignment would look like the next one:

[self setValue:@"John" forKey:@"firstname"];

If you look closely, this looks similar to the way we set values to dictionaries, or when converting scalar values and structs to NSValue objects. As you see, we set the value John for the key firstname. One more example:

[someObject.someProperty setText:@"This is a text"];

Using KVC:

[self setValue:@"This is a text" forKeyPath:@"someObject.someProperty.text"];

In both of these examples, instead of directly setting the value (first example) to the property or use the setter method (second example) of the property, we simply match values to keys or keypaths (more about keys and keypaths in just a moment). As you assume, because we use keys and values, the above technique is called Key-Value Coding.

So, returning to Apple’s definition, you notice that we use strings (the keys) to indirectly access the properties we want to assign values to, instead of doing so directly. On the other hand now, to get values from KVC properties, we would write something like that:

NSLog(@"%@", [self valueForKey:@"firstname"];

Now that you have started getting into the point, let’s discuss about some important stuff before we see an actual example on Xcode. First of all, there is an informal protocol, named NSKeyValueCoding, and your class (or classes) must comply with it if you want to use KVC. If your class is a subclass of the NSObject though, then you are already set, because NSObject complies to that protocol.

Besides that, as you saw in the above two examples we used two different methods to set the values to properties. The first one is the setValue:forKey: and the second is the setValue:forKeyPath:. The difference is that the first method expects a key (which is a string value), while the second expects a keypath (also a string value). So, what is a key and what a keypath?

Simply put, the key specifies a single property, the one we want to set a value to or get one from, so its name should be similar to the property’s one. In our example, we had the firstname property, and that was exactly the key we used when we set its value using the KVC.

A keypath is always formed using the dot syntax, so it’s not a single word, and represents all the properties of an object that should be traversed until the desired one is found (speaking totally non-technically so as to make things clear, I would say that the keypath looks for the subproperty of the subproperty of the … (and so on) … of an object). For example, the someObject.someProperty.text keypath we set to the second example above refers to the text property of the someProperty of the someObject object.

With all that said, it’s time to go to Xcode and see some more examples there. Don’t worry if things look still obscure to you, everything will become lighter as we move on.

On Xcode, begin by creating a new class. To do so, open the File > New > File… menu, and in the window that appears select the Objective-C class as the template for our new file.

Next, go to the second step and set the NSObject value to the Subclass of field. In the Class textfield, specify the Children value as the name of the new class.

Get finished with the guide, and let Xcode to create the new class and add the couple new files to the project. In the class we just created we are going to add properties regarding the name and the age of a hypothetic person’s children, and the way we will use it is perfect to demonstrate all the major aspects of the Key-Value Coding.

Now, open the Children.h file and modify it as shown next. As you’ll see, we add only two properties, one for the name and one for the age of the child represented by an instance of that class.

@interface Children : NSObject

@property (nonatomic, strong) NSString *name;

@property (nonatomic) NSUInteger age;

@end

Next, open the Children.m file, and initialise the above two properties:

@implementation Children

- (instancetype)init
{
    self = [super init];
    if (self) {
        self.name = @"";
        self.age = 0;
    }
    return self;
}   

@end

It is time to see KVC in action now. Open the ViewController.m file and at the top of it import the header of the Children class:

#import "Children.h"

Next, declare three objects of the Children class to the private class section as it’s shown below:

@interface ViewController ()

@property (nonatomic, strong) Children *child1;

@property (nonatomic, strong) Children *child2;

@property (nonatomic, strong) Children *child3;

@end

Then, head to the viewDidLoad method, where we will initialise the first object:

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view, typically from a nib.

    self.child1 = [[Children alloc] init];
}

If we assign values to the name and age properties of the child1 object, and then show them on the debugger as follows…

- (void)viewDidLoad
{
    ...

    self.child1.name = @"George";
    self.child1.age = 15;

    NSLog(@"%@, %d", self.child1.name, self.child1.age);

}

… then we will get the expected output:

George, 15

Now, let’s try to use the Key-Value Coding method to do the same thing. If you want, either comment out or delete the previous lines in the viewDidLoad, just make sure to leave the child1 object initialisation intact.

- (void)viewDidLoad
{
    ...

    [self.child1 setValue:@"George" forKey:@"name"];
    [self.child1 setValue:[NSNumber numberWithInteger:15] forKey:@"age"];

    NSString *childName = [self.child1 valueForKey:@"name"];
    NSUInteger childAge = [[self.child1 valueForKey:@"age"] integerValue];

    NSLog(@"%@, %d", childName, childAge);

}

In the first couple of rows we set the desired values to both properties using the setValue:forKey: method. Pay attention to the fact that the age is a number, therefore it cannot be passed directly as an argument to that method. Instead, we must convert it to a NSNumber object first. Besides that, watch that the key strings are the same to the properties’s names.

Next, we perform the exact opposite task. We extract the values out of the properties using the valueForKey: method, and we assign them to two local variables. Focusing on the age again, notice that we want to get an unsigned integer value, so we convert the returned data type from NSNumber to NSInteger.

Finally, we display everything to the debugger. The output in this case is similar to the previous one:

George, 15

That’s great, but you may ask yourself if it actually worths it to write the extra lines. Well, as you’ll find out next when we’ll talk about the Key-Value Observing, yes it is.

Now, replace this line…

[self.child1 setValue:@"George" forKey:@"name"];

… with this one:

[self.child1 setValue:@"George" forKey:@"namee"];

In case you read too fast and you don’t see the modification, there’s an extra “;e”; letter to the key string. If you run the app once again then… Boom! The app crashes! Here’s a screenshot from the debugger:

The actual message before all that bunch with the technical information says:

Terminating app due to uncaught exception 'NSUnknownKeyException', reason: '[ setValue:forUndefinedKey:]: this class is not key value coding-compliant for the key name.'

This crash message is quite explanatory. In simple words, it’s telling us that the app crashed because no property found matching to the key namee. Okay, no big deal as we can go back to our code and fix this error. However, let’s see the bottom line here: When writing KVC-compliant code it’s really important to take care so the key strings actually match to the property names, otherwise the app will simply fall apart. This is not a case when dealing directly with properties, as there’s no chance to do any mistake on their names; the compiler would throw an error in such a case which would drive us to fix it.

With all the above, we have managed to see how to write KVC-styled code, and how to set and get values using keys. Also, we have seen and underlined what happens if a key name is mistyped. Now, let’s extend our example a bit more, and let’s see how we can work with keypaths. For starters, go to the Children.h file, and add the next property to the class:

@interface Children : NSObject

...

@property (nonatomic, strong) Children *child;

@end

With this, we can represent in code the child of a child (and so on). Return to the ViewController.m file, in the viewDidLoad method. Now, add the next lines that initialize the related objects and assign their initial values:

- (void)viewDidLoad
{
    ...

    self.child2 = [[Children alloc] init];

    [self.child2 setValue:@"Mary" forKey:@"name"];
    [self.child2 setValue:[NSNumber numberWithInteger:35] forKey:@"age"];
    self.child2.child = [[Children alloc] init];
}

Nothing new here, we just initialize the child2 object of our custom class, we set the values of the name and the age properties, and we then initialize its child object.

The point now is how we can set values to the properties of the child object using the KVC style. According to what we said in the introduction of this tutorial, we must use the setValue:forKeyPath: method to do so. The key that we will provide is going to be a string with the dot syntax to point out the property of the object we want to change. In code:

- (void)viewDidLoad
{
    ...

    [self.child2 setValue:@"Andrew" forKeyPath:@"child.name"];
    [self.child2 setValue:[NSNumber numberWithInteger:5] forKeyPath:@"child.age"];
}

It’s not difficult, right? Now, simply by adding the next NSLog command, let’s see if the assignment was successful:

- (void)viewDidLoad
{
    ...

    NSLog(@"%@, %d", self.child2.child.name, self.child2.child.age);
}

Output:

Andrew, 5

Perfect! Now, what if the child of the child has a child too? Let’s see this case too (the commands are given altogether):

- (void)viewDidLoad
{
    ...

    self.child3 = [[Children alloc] init];
    self.child3.child = [[Children alloc] init];
    self.child3.child.child = [[Children alloc] init];

    [self.child3 setValue:@"Tom" forKeyPath:@"child.child.name"];
    [self.child3 setValue:[NSNumber numberWithInteger:2] forKeyPath:@"child.child.age"];

    NSLog(@"%@, %d", self.child3.child.child.name, self.child3.child.child.age);

}

The output is:

Tom, 2

Great! So, now you know how to deal with both keys and keypaths, and how to write KVC compliant code. If you want, feel free to write more examples and see what results you get back.

Observing for Property Changes

Now that you know the basics of the Key-Value Coding let’s move on and let’s focus on the Key-Value Observing (KVO). Here we will see what actions should be taken in order to be able to track down changes on properties. First of all, let me introduce you as a list the steps needed to implement KVO:

1. The class of which you want to observe its properties must be KVO compliant. That means:
   • The class must be KVC compliant according to what we have already seen in the introduction and in the previous section.
   • The class must be able to send notifications either automatically, or manually (we will see more about that later).
2. The class that will be used to observe the property of another class should be set as observer.
3. A special method named observeValueForKeyPath:ofObject:change:context: should be implemented to the observing class.

Let’s see everything one by one. The most important thing when we want to observe for changes of a property, is to make our class observe for these changes. This is done more or less with as with the casual notifications (NSNotifications), but using another method. This method is the addObserver:forKeyPath:options:context. In order to become more specific, I will use our previous example where we used the Children class. In this class we had three properties, the name, the age and the child which was of type Children as well. To observe for the first two of them, here’s what is only needed (add the viewWillAppear: method and then write the next lines to it, in the ViewController.m file):

-(void)viewWillAppear:(BOOL)animated{
    [super viewWillAppear:animated];

    [self.child1 addObserver:self forKeyPath:@"name" options:NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld context:nil];
    [self.child1 addObserver:self forKeyPath:@"age" options:NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld context:nil];    
}

The parameters the above method accepts are:

• addObserver: This is the observing class, usually the self object.
• forKeyPath: I guess you can understand what’s this for. It is the string you used as a key or a key path and matches to the property you want to observe. Note that you specify here either a single key, or a key path.
• options: By setting a value other than 0 (zero) to this parameter, you specify what the notification should contain. You can set a single value, or a combination of NSKeyValueObservingOptions values, combining them using the logical or (|). In the above example, we ask from the notifications to contain both the old and the new value of the properties we observe.
• context: This is a pointer that can be used as a unique identifier for the change of the property we observe. Usually this is set to nil or NULL. We’ll see more about this later.

Now that we have made our class able to observe for any changes in the above two properties, we must implement the observeValueForKeyPath:ofObject:change:context: method. Its implementation is mandatory, and it has one great disadvantage. That is the fact that is called for every KVO change, and if you observe many properties then you must write a lot of if statements so as to take the proper actions for each property. However, this can be easily overlooked as the benefits of the KVO are greater than this limitation.

Now, let’s implement it.

-(void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context{

    if ([keyPath isEqualToString:@"name"]) {
        NSLog(@"The name of the child was changed.");
        NSLog(@"%@", change);
    }

    if ([keyPath isEqualToString:@"age"]) {
        NSLog(@"The age of the child was changed.");
        NSLog(@"%@", change);
    }

}

As you see, we do nothing special here (for the sake of the demonstration). What we only do, is to determine the property that was changed based on the keyPath parameter, and then to display just a single message along with the dictionary containing the changes that took place. In a real application, you apply all the needed logic to handle all the changes in each case.

Time to test it, don’t you think? In the viewWillAppear: method, add the next line:

-(void)viewWillAppear:(BOOL)animated{
    ...

    [self.child1 setValue:@"Michael" forKey:@"name"];
}

Let’s run the app and let’s see what will be displayed on the debugger:

The name of the child was changed.
{
    kind = 1;
    new = Michael;
    old = George;
}

Super! After we have set a new value to the name property of the child1 object, we received the notification, and the messages we asked for to be displayed were shown on the debugger. As you see, both the previous and the new value are included in the dictionary.

Now, let’s change the age property of the child1 object to see if the notification will arrive:

-(void)viewWillAppear:(BOOL)animated{
    ...

    [self.child1 setValue:[NSNumber numberWithInteger:20] forKey:@"age"];
}

And when we run it:

The age of the child was changed.
{
    kind = 1;
    new = 20;
    old = 15;
}

So, everything seems to be working great. From the change dictionary you can extract any value you want (if needed), but the most important of all is that it’s super-easy to be notified about changes in properties. If all these look new to you, don’t worry. It’s all just a matter of habit!

We are going to make everything much more interesting now, simply by adding one more observer for the age property of the child2 object. After that, we will assign a new value to that property.

-(void)viewWillAppear:(BOOL)animated{
    ...

    [self.child2 addObserver:self forKeyPath:@"age" options:NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld context:nil];

    [self.child2 setValue:[NSNumber numberWithInteger:45] forKey:@"age"];
}

If we run the app, the output will be this:

The name of the child was changed.
{
kind = 1;
new = Michael;
old = George;
}

The age of the child was changed.
{
    kind = 1;
    new = 20;
    old = 15;
}

The age of the child was changed.
{
    kind = 1;
    new = 45;
    old = 35;
}

As you notice, we receive two notifications regarding changes to the age property. But that seems confusing, because even though we know the object that each notification belongs to, programmatically we can do nothing to determine the object that sent the notification. So, how do we face that, and how can we programmatically be a 100% sure about the object that the changed property belongs to?

The answer to the above question is one: We will make use of the context argument of the addObserver:forKeyPath:options:context: method. I have already mentioned before that the purpose of the context is to uniquely identify a change on a property, so it’s the best tool we have at our disposal. As I have said, the context is a pointer, and it actually points to itself, so the way that is declared is the following:

static void *someContext = &someContext;

Note that the context value for each observed property must be a global variable, because it has to be accessible from both the addObserver… and the observeValueForKeyPath… methods. Let’s get back to our example, and let’s add a couple of context values. In the ViewController.m file, go at the very top of it, just right before the @interface ViewController () line. There, add the next two commands:

static void *child1Context = &child1Context;
static void *child2Context = &child2Context;

Alternatively, instead of declaring these two as global variables, you could use them as properties of your class, but I consider the first way to be much simpler.

Now, we just have to modify the code in the viewWillAppear: method by setting the proper context value to the addObserver:forKeyPath:options:context: calls. Here it is in one piece:

-(void)viewWillAppear:(BOOL)animated{
    [super viewWillAppear:animated];

    [self.child1 addObserver:self forKeyPath:@"name" options:NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld context:child1Context];
    [self.child1 addObserver:self forKeyPath:@"age" options:NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld context:child1Context];

    [self.child1 setValue:@"Michael" forKey:@"name"];
    [self.child1 setValue:[NSNumber numberWithInteger:20] forKey:@"age"];

    [self.child2 addObserver:self forKeyPath:@"age" options:NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld context:child2Context];

    [self.child2 setValue:[NSNumber numberWithInteger:45] forKey:@"age"];
}

Finally, we have to modify the observeValueForKeyPath:ofObject:change:context: appropriately, so we can programmatically determine the object that sends the notification.

-(void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context{

    if (context == child1Context) {
        if ([keyPath isEqualToString:@"name"]) {
            NSLog(@"The name of the FIRST child was changed.");
            NSLog(@"%@", change);
        }

        if ([keyPath isEqualToString:@"age"]) {
            NSLog(@"The age of the FIRST child was changed.");
            NSLog(@"%@", change);
        }
    }
    else if (context == child2Context){
        if ([keyPath isEqualToString:@"age"]) {
            NSLog(@"The age of the SECOND child was changed.");
            NSLog(@"%@", change);
        }
    }
}

I said before that the drawback of using this method is that you have to write a bunch of if statements, and now you can see this fact. Anyway, you can clearly understand how easy it is to identify a property that was changed based on the context and the key path. Running the app once again, we get the next output:

The name of the FIRST child was changed.
{
    kind = 1;
    new = Michael;
    old = George;
}

The age of the FIRST child was changed.
{
    kind = 1;
    new = 20;
    old = 15;
}

The age of the SECOND child was changed.
{
    kind = 1;
    new = 45;
    old = 35;
}

Much better now! We modified and messages in such way, so they are more explanatory and of course, we managed to programmatically specify each changed property.

Lastly and before we reach at the end of this chapter, it’s also quite important at some point to remove the observers you add. There is not a recipe on where you should do that. For instance, in many cases it would be useful to do that in the observeValueForKeyPath:ofObject:change:context:, after you have handled a received notification. In other cases, you should do so upon the dismissal of a view controller. Generally, it’s up to your application’s structure the decision you will make about that. In this example, we will do it in the viewWillDissapear: method. Here it is:

-(void)viewWillDisappear:(BOOL)animated{
    [super viewWillDisappear:animated];

    [self.child1 removeObserver:self forKeyPath:@"name"];
    [self.child1 removeObserver:self forKeyPath:@"age"];
    [self.child2 removeObserver:self forKeyPath:@"age"];
}

So, now you know the most important steps you should make when you want to apply Key-Value Observing logic to your application. As you found out, the rules that should be followed are simple, and all the hard work of monitoring for changes and sending notifications is done by iOS itself. However, there are more details we should discuss about, but the knowledge you acquired up to this point is the most significant.

Automatic and Manual Notifications

By default, the system sends a notification every time a property gets changed when you observe using KVO. This is suitable in most cases, however there are times that we don’t want to get a notification once a change has happened, but after a bunch of changes have taken place in multiple properties or at a later time. Thankfully, iOS SDK provides us with some quite convenient methods that gives us control over the notifications, so we can manually send them whenever it’s actually needed. Before we get into more details, let me just say that using the method you’ll see right next is not mandatory. On the contrary, you may implement it if and when it is really necessary.

Getting into the point now, in order to control the notifications that are sent upon property changes, you must implement the automaticallyNotifiesObserverForKey: class method. The parameter it accepts is a string representation of the key of the property for which you need to control the notification, and it returns a boolean value. In case that you don’t want a notification to be sent after the observed property’s value has been changed, then the method must return NO. In any other case, you should let iOS decide about the notifications (you’ll see how in the example that follows).

In practice, let’s suppose that we don’t want a notification to be posted when the name property of the Children class get changed. With that in mind, here’s the implementation of that method in the Children class (Children.m file):

+(BOOL)automaticallyNotifiesObserversForKey:(NSString *)key{
    if ([key isEqualToString:@"name"]) {
        return NO;
    }
    else{
        return [super automaticallyNotifiesObserversForKey:key];
    }
}

I believe that the method is quite straightforward. In the else clause, we call the same method using the super class in order to let iOS handle all the keys that we haven’t explicitly added here, and the value that we get back is the one that we return at the end.

If you run the app at this point, you’ll find out that no message regarding the name changing is appeared on the debugger. Of course, this is what we desire, so we’ve managed to achieve our goal. But, have we really done it?

Well, as you understand by returning NO in the above method for the specific key, we’ve only managed to stop the relevant notifications from being sent. And of course, this doesn’t mean manual notifications, it means no notifications at all! In order to send a notification when we decide so, we must use two other methods. These are the willChangeValueForKey: and the didChangeValueForKey:. When using them, the willChangeValueForKey: must be called first, then the new value must be assigned to the property, while the didChangeValueForKey: should be called at the end.

Back in the action again, go to the ViewController.m file and then to the viewWillAppear: method. Next, replace this line:

[self.child1 setValue:@"Michael" forKey:@"name"];

with these three:

[self.child1 willChangeValueForKey:@"name"];
self.child1.name = @"Michael";
[self.child1 didChangeValueForKey:@"name"];

If you run the app now, the message regarding the name change is appeared on the debugger, and that means that we’ve sent the notification manually with success!

The name of the FIRST child was changed.
{
    kind = 1;
    new = Michael;
    old = George;
}

Actually, the notification is sent after the didChangeValueForKey: method is invoked, therefore if you don’t want to send the notification right after the value assignment, simply get this line:

[self.child1 didChangeValueForKey:@"name"];

and place it right to the point that is appropriate for the notification to be sent. For example, if we add the above call at the end of the viewWillAppear: method, then the name change messages will be the last appearing on the debugger when you run the app:

The age of the FIRST child was changed.
{
    kind = 1;
    new = 20;
    old = 15;
}

The age of the SECOND child was changed.
{
    kind = 1;
    new = 45;
    old = 35;
}

The name of the FIRST child was changed.
{
    kind = 1;
    new = Michael;
    old = George;
}

That’s what exactly we have been expecting from the app! As you can see, we’ve managed to control the notification sending point, and all that with a little effort! Note that between the willChangeValueForKey: and the didChangeValueForKey: methods, you can have more than one property values assigned.

The willChangeValueForKey: and the didChangeValueForKey: methods are not mandatory to be used as shown above. They can be implemented in the Children class (or in your own class) as well. In order to see such an example, we will override the setter method of the name property. Before doing so, just comment our or remove these lines in the viewWillAppear: method so we won’t face any problem later on:

[self.child1 willChangeValueForKey:@"name"];
self.child1.name = @"Michael";
[self.child1 didChangeValueForKey:@"name"];

Now, open the Children.m file, and add the following implementation.

-(void)setName:(NSString *)name{
    [self willChangeValueForKey:@"name"];
    _name = name;
    [self didChangeValueForKey:@"name"];
}

Back to the ViewController.m now, add the next one as the last command to the viewWillAppear: method:

-(void)viewWillAppear:(BOOL)animated{
    ...

    self.child1.name = @"Michael";
}

Finally, run the app once again. What are you watching on the debugger? The messages about the name property of course after the rest of the notification messages!

The age of the FIRST child was changed.
{
    kind = 1;
    new = 20;
    old = 15;
}

The age of the SECOND child was changed.
{
    kind = 1;
    new = 45;
    old = 35;
}

The name of the FIRST child was changed.
{
    kind = 1;
    new = Michael;
    old = George;
}

Awesome, but most importantly, by using the willChangeValueForKey:, the didChangeValueForKey: or by overriding the setter method of the name property, we managed to set the new value directly to it as we would normally do, and to still have the KVO working! Pretty useful, right?

Working With Arrays

Arrays is a special case in Key-Value Coding and Key-Value Observing, as there are extra actions that should be performed before you successfully manage to observe for changes made on them. Actually, there are a lot of details regarding the arrays, but here we’ll see just the basics and most important things you need to know so you can work with them.

The first thing that you should know is that arrays are not KVC compliant, therefore dealing with them is not as simple as with single properties. There are certain methods regarding the arrays that should be implemented in order to make them KVC compliant, and ultimately to be able to observe any changes on them. So, let’s talk about them.

For the sake of the tutorial we will discuss about mutable arrays. However, immutable arrays are handled the same way, except for the fact that fewer methods are needed to be implemented. So, let’s suppose that we have a mutable array named myArray. The methods that should be implemented are similar to those we use for inserting, removing, and counting objects usually to an array, but with some differences on their naming (you will get the meaning of that pretty soon). A minimum number of methods is required to be written, so let’s see them:

• countOfMyArray
• objectInMyArrayAtIndex:
• insertObject:inMyArrayAtIndex:
• removeObjectFromMyArrayAtIndex:

All of those methods look familiar, don’t they? The new here is that in their names we append the name of our array. Notice that even though the array is named myArray, when it is used in the methods the first letter becomes capital (MyArray). It’s obvious that in a real implementation, the MyArray name is replaced by the name of the actual array. Beyond that, there are a few more methods that could be implemented in order to increase performance and flexibility, but here we will stay on them. Of course, when talking about immutable arrays, the last two methods should not be implemented.

There are both good and bad news when making an array KVC compliant. The good news is that Xcode suggests you each method’s name once you start typing, so you don’t have necessarily to remember them. The bad news however is that you should implement all those methods for every single array you have in your class and you want to observe. Don’t worry though, as I am going to show you a technique at the next section that could get you out of trouble very easily.

Now, it’s time to go to practice, and to see how everything we discussed so far is actually applied in code. For our purposes, we will add a new mutable array to the Children class that is supposed to contain the names of the siblings of a child. Go to the Children.h file, and add the next declaration:

@interface Children : NSObject

...

@property (nonatomic, strong) NSMutableArray *siblings;

@end

Next, open the Children.m file, and in the init method initialize the array:

- (instancetype)init
{
    self = [super init];
    if (self) {
        ...

        self.siblings = [[NSMutableArray alloc] init];
    }
    return self;
}

Now we are ready to focus on the methods that should be implemented. Go back to the Children.h file, and add the following method declarations. I would recommend to type them instead of copy-paste them, in order for you to see how Xcode suggests them to you.

@interface Children : NSObject

...

-(NSUInteger)countOfSiblings;

-(id)objectInSiblingsAtIndex:(NSUInteger)index;

-(void)insertObject:(NSString *)object inSiblingsAtIndex:(NSUInteger)index;

-(void)removeObjectFromSiblingsAtIndex:(NSUInteger)index;

@end

Notice how the siblings array name is used in the above declarations, and that the first letter is always capital. There is one comment that I would like to do here, and that is that for the insertObject:inSiblingsAtIndex: method, Xcode does not set the type of the objects to the parameters automatically, but it let’s you type them according to the kind of data you are going to have in your array. In other words, if you start typing it Xcode will suggest you this:

-(void)insertObject:( *)object inSiblingsAtIndex:()index

…and you manually have to go and set the proper types of the parameters. As I said, in our case we are going to add the names of the siblings, so we will set the NSString type. Alternatively, in the first parameter you can specify the id keyword (without the asterisk), which is suitable for any type of data you may have.

Let’s implement them now. Open the Children.m file, and add the next code segment. As you will see, what it is written is pretty simple and straightforward.

-(NSUInteger)countOfSiblings{
    return self.siblings.count;
}


-(id)objectInSiblingsAtIndex:(NSUInteger)index{
    return [self.siblings objectAtIndex:index];
}


-(void)insertObject:(NSString *)object inSiblingsAtIndex:(NSUInteger)index{
    [self.siblings insertObject:object atIndex:index];
}


-(void)removeObjectFromSiblingsAtIndex:(NSUInteger)index{
    [self.siblings removeObjectAtIndex:index];
}

That’s it! Now the siblings array is KVC compliant, so we can track down any changes that happen to it as we normally do with every other property. Of course, we will add and remove data using only the above methods.

Open the ViewController.m file, and go to the viewWillAppear: method. The first step in KVO is to always observe for the desired property, so add the next line at the end of the method (we will observe only for changes to the siblings array of the child1 object):

-(void)viewWillAppear:(BOOL)animated{
    ...    

    [self.child1 addObserver:self forKeyPath:@"siblings" options:NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld context:nil];

}

Now, let’s add some objects to the array, and then remove one of them:

-(void)viewWillAppear:(BOOL)animated{
    ...

    [self.child1 insertObject:@"Alex" inSiblingsAtIndex:0];
    [self.child1 insertObject:@"Bob" inSiblingsAtIndex:1];
    [self.child1 insertObject:@"Mary" inSiblingsAtIndex:2];
    [self.child1 removeObjectFromSiblingsAtIndex:1];
}

Perfect! Not only we implemented the methods needed to make our array KVC compliant, we also used them to add and remove objects. There’s one step remaining, and that is to handle the received notification to the observeValueForKeyPath:object:change:context: method. Here’s the additional code needed to display on the console the changes that arrive with each notification:

-(void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context{

    ...
    else{
        if ([keyPath isEqualToString:@"siblings"]) {
            NSLog(@"%@", change);
        }
    }
}

Time to test it… Here are the results displayed on the console:

{
    indexes = "[number of indexes: 1 (in 1 ranges), indexes: (0)]";
    kind = 2;
    new =     (
        Alex
    );
}

{
    indexes = "[number of indexes: 1 (in 1 ranges), indexes: (1)]";
    kind = 2;
    new =     (
        Bob
    );
}

{
    indexes = "[number of indexes: 1 (in 1 ranges), indexes: (2)]";
    kind = 2;
    new =     (
        Mary
    );
}

{
    indexes = "[number of indexes: 1 (in 1 ranges), indexes: (1)]";
    kind = 3;
    old =     (
        Bob
    );
}

The results are in accordance to our actions. We performed three insertions and one deletion, and that’s what exactly the above messages describe. In the first three cases, there is no previous value to display, so only the new one is shown. In the last case, it’s shown only the old value, while there’s not a new one as we just remove an object.

A General Approach on Arrays

Applying KVC and KVO to arrays is not that difficult ultimately according to what we have seen to the previous section, however it requires some extra coding, and if you have several arrays that you need to observe, then the amount of code writing gets increased. Obviously, it would be great if we could minimize that effort, and at the same time to be able to KVO on arrays. Well, actually there is a simple but nice technique. What I will show you in this section is a method that I’ve been using in my projects repeatedly for a long time, and after some research on the web I found out that similar techniques are recommended by others too. So, let’s go for it.

The big idea on the approach that I will present here, is to create and use an extra class that contains just a mutable array and it implements the necessary methods for making it KVC compliant. Once it’s ready, objects of this class can be used to any other classes instead of arrays. The benefits from all that are multiple:

• The necessary methods we implemented in the previous section don’t have to be written more than once.
• You can use objects of that class everywhere instead of normal mutable arrays.
• Most importantly, it is reusable, meaning that you implement it once and you use it to many projects!

In other words, think of it as a mechanism that provides you an advanced version of the mutable arrays. Let’s work on it.

Begin by adding a new class to the project. Go to the File > New > File… menu, and in the guide that appears select the Objective-C class option as the template. To the next step, make sure that the Subclass of field contains the NSObject value, and set the KVCMutableArray as the name of the class to the Class field. Get finished with the guide and wait until the new files are added to the project.

Go to the KVCMutableArray.h file, and add the next array declaration:

@interface KVCMutableArray : NSObject

@property (nonatomic, strong) NSMutableArray *array;

@end

Now, let’s create an init method, where we will initialize the array. To do so, open the KVCMutableArray.m file and add the next code segment:

- (instancetype)init
{
    self = [super init];
    if (self) {
        self.array = [[NSMutableArray alloc] init];
    }
    return self;
}

Great! This array is going to be the container for all of our data, so its role is very important. Now we have it declared and initialized, we can move to the methods that will make it KVC compliant. Firstly, go to the KVCMutableArray.h file and do the proper declarations:

@interface KVCMutableArray : NSObject

...

-(NSUInteger)countOfArray;

-(id)objectInArrayAtIndex:(NSUInteger)index;

-(void)insertObject:(id)object inArrayAtIndex:(NSUInteger)index;

-(void)removeObjectFromArrayAtIndex:(NSUInteger)index;

-(void)replaceObjectInArrayAtIndex:(NSUInteger)index withObject:(id)object;

@end

Notice that I added a new method, the replaceObjectInArrayAtIndex:withObject:, so our class is even more powerful. Besides that, our approach is more general here, so in the insertObject:inArrayAtIndex: method we specified the id instead of a specific data type or class. Once again, notice how the name of the array is used to the methods.

Now, open the KVCMutableArray.m file, and implement them:

-(NSUInteger)countOfArray{
    return self.array.count;
}


-(id)objectInArrayAtIndex:(NSUInteger)index{
    return [self.array objectAtIndex:index];
}


-(void)insertObject:(id)object inArrayAtIndex:(NSUInteger)index{
    [self.array insertObject:object atIndex:index];
}


-(void)removeObjectFromArrayAtIndex:(NSUInteger)index{
    [self.array removeObjectAtIndex:index];
}

-(void)replaceObjectInArrayAtIndex:(NSUInteger)index withObject:(id)object{
    [self.array replaceObjectAtIndex:index withObject:object];
}

All implementations are very simple, so our work here is over. The new class is ready!

Let’s assume now that in the Children class we want to add and observe a new array, which will contain the names of the cousins of a child. It’s obvious that instead of a normal mutable array, we will use an object of the KVCMutableArray class. Without wasting more time, let’s open the Children.h file, and let’s declare a new property:

@interface Children : NSObject

...

@property (nonatomic, strong) KVCMutableArray *cousins;

@end

Xcode will become grumpy, so go at the top of the file and import this:

#import "KVCMutableArray.h"

We are fine here, so open the Children.m file and initialize the new object:

- (instancetype)init
{
    self = [super init];
    if (self) {
        ...

        self.cousins = [[KVCMutableArray alloc] init];
    }
    return self;
}

And finally, the big step. It’s time to try it, so open the ViewController.m file and at the end of the viewWillAppear: method add the next lines:

-(void)viewWillAppear:(BOOL)animated{
    ...

    [self.child1 addObserver:self forKeyPath:@"cousins.array" options:NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld context:nil];

    [self.child1.cousins insertObject:@"Antony" inArrayAtIndex:0];
    [self.child1.cousins insertObject:@"Julia" inArrayAtIndex:1];
    [self.child1.cousins replaceObjectInArrayAtIndex:0 withObject:@"Ben"];
}

Firstly, notice the keypath value we use. Remember that what we want to observe is the array of the KVCMutableArray class, and not the object itself, so we use the dot syntax to specify that. Secondly, to insert new objects we call the custom KVC compliant method we implemented, and lastly we make use of the new method to replace the first object.

The final step:

-(void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context{

    ...
    else{
        ...

        if ([keyPath isEqualToString:@"cousins.array"]) {
            NSLog(@"%@", change);
        }
    }
}

Ready to test it? If we run it, here are the results we get on the console:

{
    indexes = "[number of indexes: 1 (in 1 ranges), indexes: (0)]";
    kind = 2;
    new =     (
        Antony
    );
}

{
    indexes = "[number of indexes: 1 (in 1 ranges), indexes: (1)]";
    kind = 2;
    new =     (
        Julia
    );
}

{
    indexes = "[number of indexes: 1 (in 1 ranges), indexes: (0)]";
    kind = 4;
    new =     (
        Ben
    );
    old =     (
        Antony
    );
}

Excellent! It is what exactly we have been wanted to see. Both new objects are inserted to the array, and the replacement successfully takes place at the end.

So, it seems that the new class we implemented here is a new great tool, which you can wrap up and get with you when you are done with the tutorial. You see how really easy it is to observe for changes on arrays, and all that with almost no effort at all!

Summary

Both Key-Value Coding and Key-Value Observing are mechanisms that allow you to create more powerful, more flexible and more efficient applications. These mechanisms are not adopted by a great number of developers, and that’s a pity, because even though they look weird at the beginning, at the end it’s proved to be very easy to be handled. In this tutorial I made an effort to provide you with a detailed introduction to both the KVC and KVO concepts. What you have learnt here is good enough to let you work with them in your projects, but there is more advanced information you could look up if you want so. It would be impossible to cover everything into one tutorial, but the most you need is here. So, having this post as a guide, I hope you’ll manage to use the demonstrated techniques to your projects too, and of course, you can add the last class we created in the previous section to your programming toolbox. Happy Key-Value programming!

For your reference, here is the complete Xcode project for your download.

One of the most important tasks that a developer has to deal with when creating applications is the data handing and manipulation. Data can be expressed in many different formats, and mastering at least the most known of them consists of a key ability for every single programmer. Speaking for mobile applications specifically now, it’s quite common nowadays for them to exchange data with web applications. In such cases, the way that data is expressed may vary, but usually is preferred either the JSON or the XML format.

iOS SDK provides classes for handling both of them. For managing JSON data, there is the NSJSONSerialization class. This one allows to easily convert a JSON data into a Foundation object (NSArray, NSDictionary), and the other way round. For parsing XML data, iOS offers the NSXMLParser class, which takes charge of doing all the hard work, and through some useful delegate methods gives us the tools we need for handling each step of the parsing.

Focusing a bit on each class separately, there’s not much to say about the NSJSONSerialization class, except for the fact that is very simple and straightforward to be used. There are some simple rules that should follow, but further than that it takes all the hassle away from us when some JSON conversion is needed. In order to convert a JSON value into a Foundation form, it has to be a NSData object. The returned converted object is either an array (NSArray), or a dictionary (NSDictionary). Their contained objects however can be instances of NSString, NSNumber, NSNull, and of course NSArray and NSDictionary. The NSJSONSerialization class provides ways for checking if a JSON data is valid before doing any conversion, so you can use it in order to make sure before performing any conversion. On the other hand now, when you need to turn a Foundation object into JSON, you should have in mind that the produced object is always of NSData type. As you assume from what I said until now, it looks like managing JSON as a string doesn’t seem to be an option, but that’s not true. As you’ll find out later in this tutorial, we can have the JSON expressed as a NSString object, simply by doing a small kind of trick.

Going to NSXMLParser class now, I have to say that is a very convenient one and makes the parsing of XML data a piece of cake. It’s responsible for doing the actual parsing work, and it lets us know about each item that is found during parsing through delegate methods. It provides a great number of such methods, but that doesn’t mean that all of them must be implemented to an app. The ones that will be selected for implementation depend on how the parsed data should be handled.

So, as you guess my goal in this tutorial is to teach you how to work with JSON and XML data, and how to handle it so you can use it in your applications. At this point, I should point out two facts: At first, I presume that you know what JSON and XML is, and how data is formed in both formats. If you don’t feel very confident about any of them, then this is a good time to find and read a bit more about them. At second, even though I’m going to show you the basics on both of them, be sure that what you’ll learn is going to be more than enough to help you in your apps and to put you on the right track when you’ll need to find extra support or assistance.

Furthermore, in this tutorial you’ll see a couple of other interesting things too: How to easily fetch data from the web using the NSURLSession class, and how to use the MFMailComposeViewController class to present the standard mail view controller of iOS for sending e-mails. In the rest of this tutorial you will find out why and how we will use them.

Lastly, as always I recommend and encourage you to visit the official documentation by Apple to get more info on every topic we’ll discuss here. Having said that, let’s go to see an overview of the demo app that we’ll implement in this tutorial, as we have a lot of stuff to do next.

Demo App Overview

While I was trying to decide where I should get JSON and XML data from for the purpose of this tutorial, I ended up to a website that could provide me with both kind of data, so I considered it as the best option. That is the GeoNames website. It contains an enormous geographical database, an API for accessing its web services, and all that for free. Personally, I think of it as the #1 source when dealing with geographical data, so we’ll work with it. If you are not aware about it yet, then take a few minutes and pay a visit to it.

From this website we’ll get two different kind of data. The first one, is detailed information about a country. Not for a specific country, but for any country we’ll set in our app (we’ll talk more about that in a while). The data we’ll fetch will be in JSON format. The second, is the neighbour countries of the one we pick for getting its details, but this time the data will be in XML format. Both cases is what exactly we need for this tutorial. Examples of the JSON and XML data we’ll get through our demo app you can find here (country details) and here (neighbour countries).

Let me say a couple of things now regarding the app itself. First of all, we won’t create a new project from scratch. Instead, you’ll download a starter app where I’ve done some basic implementation. That app contains two view controllers, plus the standard iOS email view controller which we’ll present it through code. In the first one we will display the details of a country, while in the second we will list the neighbour countries. We will use the mail view controller (MFMailComposeViewController class) just to make our application more complete, but no e-mail is required to be actually sent.

More specifically now, in the first view controller (named ViewController) already exists a textfield, in which you’ll write the name of the country you want to get information for. I already have implemented the functionality of the textfield, so our work will begin by the time you want to download data after having tapped the Search button on the keyboard. Because the URL we’ll use for downloading the data regarding the typed country requires a two-letter country code parameter and not the whole name of the country, I’ve added to the project two text files. In the first one you’ll find all country names, while in the second one you’ll see the respective two-letter country code (for example, country name=ITALY, country code=IT). When tapping on the Search button, in the textFieldShouldReturn: delegate method of the textfield I have already added the logic for looking up the country code based on the given country. In case that no country matching to the typed one is found, then an alert view with a respective message appears. Beyond all that, there are also two more subviews in the first view controller: A label (UILabel) in which we’ll display the country name and its code after having retrieved and converted the data, and a table view for showing some details regarding the country.

The last cell of the above table view won’t contain any piece of information regarding the selected country, but it will be used to take us to the second view controller. Before loading it, we will pass a unique id value regarding the country, and using that id we will get the neighbour countries. The second view controller (named NeighboursViewController) contains just a table view which we’ll use to list the fetched data.

In the first view controller the data we’ll download will be in JSON format. Using the NSJSONSerialization class we’ll convert and add it to a dictionary (NSDictionary) object, and also we will convert some data back to JSON that we will set as the e-mail body in the mail view controller. In the second view controller we will get the data in XML format, and using the NSXMLParser class of the iOS SDK we will parse them and we will add them into an array.

As I have already said in the beginning of the tutorial, through the next parts you will be acquainted with both classes and you’ll see how to handle both JSON and XML data.

Register an Account on GeoNames

Let’s get started by paying a visit to the GeoNames website for creating a new account. If you want to know more about that, feel free to navigate yourself around and see what it offers. A very interesting part of it, is the Web Services Overview where you can find a list all of the provided services. By clicking on a service you can see details about it and how to use it, while you can have live examples of JSON and XML data returned to you by clicking on the respective links.

Anyway, after having seen the website, go and click on the Login link at the top-right side of the index page:

In the next page you’ll find two forms, one for logging in and one for creating a new account. The second one is what we need. Fill the form in, and then click on the create account button. Make sure to remember the user name you provide, as we’ll need it in a while.

A confirmation e-mail will be sent to your e-mail address. Wait a couple of minutes until you receive it, and then open it to activate your account. A page similar to the next one will open:

There’s one more step required before you’re finished here. That is to enable your account for using the free web services, and in order to do that, you must login to your GeoNames account. So, log yourself in, locate the respective link and just click it. You can now log out and go straight ahead to the project.

In order to do any call on the GeoNames API, it’s necessary to provide a valid username, such as the one you just created. Without it, no results will be returned when querying the GeoNames database, instead you’ll receive just an error message back from the server. To avoid that, simply open the AppDelegate.m file, and at the top of it locate the next lines:

#warning Set your Geonames username in the kUsername constant.
NSString *const kUsername = @"YOUR_USERNAME_HERE";

Remove or comment my custom warning that exists there, and set your username in place of the “YOUR_USERNAME_HERE” value. After doing so, you’re ready to use the GeoNames services properly.

A Convienient Class Method

The data that will be displayed in our sample app are going to be downloaded in real time using the GeoNames web services. To perform all downloads, we’ll use the NSURLSession class, which was first introduced on iOS 7 and tends to replace the NSURLConnection class. The downloading process is going to be repeated in two different view controllers, and it would be a really bad programming practice if we would write the same code twice. Instead, we’ll create a small, class method, in which we’ll add all the code needed to fetch the data we want, and we’ll call it every time we need it. We are going to make it a class method, so we can instantly call it without initializing extra objects. I should note that I purposely didn’t include this method in the starter app, as I believe that working with the NSURLSession class is a very important task, and always beneficial, even if we won’t focus on it too much.

So, let’s get started by going to the AppDelegate.h file first, and by declaring the method as shown below:

@interface AppDelegate : UIResponder 

@property (strong, nonatomic) UIWindow *window;


+(void)downloadDataFromURL:(NSURL *)url withCompletionHandler:(void(^)(NSData *data))completionHandler;

@end

There are three noticeable things here. The first one is that we begin with the plus (+) symbol instead of the minus, as this is a class method. Next, as you can see it accepts two parameters: The first one is the URL that we’ll get the data from. The second one, is a completion handler that the method will invoke after having fetched the desired data.

In order to get the data we need, we’ll use a NSURLSessionDataTask task. That class, which is a child of the NSURLSessionTask abstract class, it requires two preliminary steps before putting it in action: To instantiate a NSURLSessionConfiguration and a NSURLSession object. In that task, we’ll provide the URL of the method’s parameter. Also, the method we’ll use has a completion handler block which is called after the data has been downloaded or if any error has occurred. In there we’ll handle the error if exists (we’ll simply log it to the console), and we’ll also show the HTTP status code if is other than 200 (meaning that something went wrong). In any case though, we’ll invoke the completion handler of the parameter, and we’ll pass the returned data as a NSData object. Let’s see all that in code now, in the AppDelegate.m file:

+(void)downloadDataFromURL:(NSURL *)url withCompletionHandler:(void (^)(NSData *))completionHandler{
    // Instantiate a session configuration object.
    NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];

    // Instantiate a session object.
    NSURLSession *session = [NSURLSession sessionWithConfiguration:configuration];

    // Create a data task object to perform the data downloading.
    NSURLSessionDataTask *task = [session dataTaskWithURL:url completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {

        if (error != nil) {
            // If any error occurs then just display its description on the console.
            NSLog(@"%@", [error localizedDescription]);
        }
        else{
            // If no error occurs, check the HTTP status code.
            NSInteger HTTPStatusCode = [(NSHTTPURLResponse *)response statusCode];

            // If it's other than 200, then show it on the console.
            if (HTTPStatusCode != 200) {
                NSLog(@"HTTP status code = %d", HTTPStatusCode);
            }

            // Call the completion handler with the returned data on the main thread.
            [[NSOperationQueue mainQueue] addOperationWithBlock:^{
                completionHandler(data);
            }];
        }
    }];

    // Resume the task.
    [task resume];
}

Even though everything is quite easy to be understood, and the comments help even more on that, I would just like to underline the use of the next couple of lines:

[[NSOperationQueue mainQueue] addOperationWithBlock:^{
                completionHandler(data);
            }];

The task runs asynchronously in a background thread, but it’s necessary to call our completion handler on the main thread of the app and not on the thread of the task, so as we ensure that any visual updates after having fetched the data will occur on the proper time. Therefore, we add the completion handler call as an operation to the main thread, using the NSOperationQueue class. If you’re curious about what could happen if we wouldn’t use that operation block, then try to make the completion handler call out of that block after we have the app implemented. You’ll find out that the interface doesn’t get updated properly, and unpredictable delays in the app execution occur.

Finally, notice that we use this command:

[task resume];

for making the task start working.

Now that we have this useful method ready, we can see how we can handle JSON data and convert it to a manageable form.

Downloading a Country’s Info as JSON Data

In this part we are going to do one of the most important tasks in this tutorial: We are going to download the data for a country of which the name we type in the textfield of on the ViewController view controller, and then we are going to convert the returned JSON from a NSData object into to a NSDictionary object.

We’ll see everything in details, but first, let’s declare a private method in the ViewController.m file. Go to the private class section and add the next line:

@interface ViewController ()

...

-(void)getCountryInfo;

@end

Before its implementation, let’s call it. The point that we should do that, is right after the user has tapped on the Search button of the keyboard, and the two-letter country representation has been found. So, go to the textFieldShouldReturn: delegate method, and locate the next line:

self.countryCode = [self.arrCountryCodes objectAtIndex:index];

Then, right below it, add the method call:

[self getCountryInfo];

The if clause that contains the first line should now look like this:

if (index != -1) {
        // Get the two-letter country code from the arrCountryCodes array.
        self.countryCode = [self.arrCountryCodes objectAtIndex:index];

        // Download the country info.
        [self getCountryInfo];
    }

Now, let’s move ahead to the implementation of the getCountryInfo method. At first, we must specify the URL that we’ll get the data from. The URL is this:

http://api.geonames.org/countryInfoJSON

and we’re going to use it for making a GET request. We must provide two parameter values in the above URL, the username of the GeoNames services, and the country we want to look up info for, expressed as a two-letter string (for that we’ll use the countryCode property already existed in the ViewController class). Let’s see that:

-(void)getCountryInfo{
    // Prepare the URL that we'll get the country info data from.
    NSString *URLString = [NSString stringWithFormat:@"http://api.geonames.org/countryInfoJSON?username=%@&country=%@", kUsername, self.countryCode];
    NSURL *url = [NSURL URLWithString:URLString];


}

If you NSLog the above URLString value now, you’ll see something like this:

http://api.geonames.org/countryInfoJSON?username=XXXXXXXX&country=GR

(Where XXXXXXXX is your username)

Now, we can call the downloadDataFromURL:withCompletionHandler: class method we previously implemented. In this, we’ll provide the URL we formed in the above code snippet, and we’ll implement the completion handler block:

-(void)getCountryInfo{
    ...

    [AppDelegate downloadDataFromURL:url withCompletionHandler:^(NSData *data) {
        // Check if any data returned.
        if (data != nil) {

        }
    }];

}

Notice that is always necessary to check if the returned data is other than nil. In case of error, no data will exist and the data object will be nil, so be careful.

For first time, we are about to use the NSJSONSerialization class in order to convert the fetched JSON data into a Foundation object, so we can handle it. Usually, a JSON converted object matches either to a NSArray object, or to a NSDictionary object. In the most cases you can know and tell what object the JSON will be converted to, as in almost every app you can find out the form of the JSON data you’ll fetch. In the rare cases you don’t know how the JSON data is formed and what Foundation object to expect after the conversion, see right next how to determine this.

Before I show you how to find out the class of the converted JSON, let me introduce the method that does all the magical work. That is the JSONObjectWithData:options:error:. The first parameter of that method, is the NSData data downloaded from the web. What this method returns, is an id Foundation type.

Returning to what I was saying before and using this method, simply by writing this (in any app):

NSLog(@"%@", [[NSJSONSerialization JSONObjectWithData:data options:kNilOptions error:&error] class]);

you can see in the console the actual class of the converted JSON data. In our case, if we run the app using the above NSLog command, we’ll see the following:

__NSCFDictionary

That means that by converting the returned JSON data we’ll get a NSDictionary object. That’s great and really interesting!

There’s one more way to determine the kind of the returned data. We can open a browser (Safari, Chrome or anything else you use), and set the URL in the address line:

By pressing the Return key, you’ll see the JSON string right in front of you:

The above screenshot might not be so clear, therefore I’m copying-pasting the returned JSON here as well:

{"geonames":[{"continent":"EU","capital":"Athens","languages":"el-GR,en,fr","geonameId":390903,"south":34.8020663391466,"isoAlpha3":"GRC","north":41.7484999849641,"fipsCode":"GR","population":"11000000","east":28.2470831714347,"isoNumeric":"300","areaInSqKm":"131940.0","countryCode":"GR","west":19.3736035624134,"countryName":"Greece","continentName":"Europe","currencyCode":"EUR"}]}

The initial curly brace ({) indicates a dictionary object. The bracket ([) indicates an array. Next, there’s another curly brace, meaning another dictionary. In simple words, the above JSON says: We have a dictionary, in which there’s an array with one object only, and that object is another dictionary containing all the data we want (dictionary > array > dictionary).

So, what we have to do is this: First, we’ll convert the returned JSON data into a NSDictionary object. Then, we will check if any error has occurred during conversion, and if not we’ll extract the array from that dictionary using the key geonames. Finally, we’ll extract the second, desired dictionary from the first index of that array. Speaking in code this time, here’s what I just said:

-(void)getCountryInfo{
    ...

    [AppDelegate downloadDataFromURL:url withCompletionHandler:^(NSData *data) {
        // Check if any data returned.
        if (data != nil) {
            // Convert the returned data into a dictionary.
            NSError *error;
            NSMutableDictionary *returnedDict = [NSJSONSerialization JSONObjectWithData:data options:kNilOptions error:&error];

            if (error != nil) {
                NSLog(@"%@", [error localizedDescription]);
            }
            else{
                self.countryDetailsDictionary = [[returnedDict objectForKey:@"geonames"] objectAtIndex:0];
            }
        }
    }];

}

Initially, we convert the JSON data to the returnedDict dictionary. Next, we get the array and the dictionary of the first index of that array, and we assign it to the countryDetailsDictionary property. Regarding the error object in the above implementation, it’s our duty to check if it’s nil or not, and to take the proper actions. For the sake of the simplicity, we just log the description of the error, if any occurs of course.

For now, it would be nice if we could see the fetched data even on the console, therefore complete the above method as shown right next:

-(void)getCountryInfo{
    ...

    [AppDelegate downloadDataFromURL:url withCompletionHandler:^(NSData *data) {
        // Check if any data returned.
        if (data != nil) {
            // Convert the returned data into a dictionary.
            NSError *error;
            NSMutableDictionary *returnedDict = [NSJSONSerialization JSONObjectWithData:data options:kNilOptions error:&error];

            if (error != nil) {
                NSLog(@"%@", [error localizedDescription]);
            }
            else{
                self.countryDetailsDictionary = [[returnedDict objectForKey:@"geonames"] objectAtIndex:0];
                NSLog(@"%@", self.countryDetailsDictionary);
            }
        }
    }];

}

Running the app now, will return something like the next output:

{
    areaInSqKm = "131940.0";
    capital = Athens;
    continent = EU;
    continentName = Europe;
    countryCode = GR;
    countryName = Greece;
    currencyCode = EUR;
    east = "28.2470831714347";
    fipsCode = GR;
    geonameId = 390903;
    isoAlpha3 = GRC;
    isoNumeric = 300;
    languages = "el-GR,en,fr";
    north = "41.7484999849641";
    population = 11000000;
    south = "34.8020663391466";
    west = "19.3736035624134";
}

So, we’ve successfully managed to download JSON data and to convert it to a NSDictionary object. That was a very important job, but we have more to do. Next, we’ll display all that data.

Populating the Converted JSON Data

Now that we have the data we want on our hands, it’s time to display it. There are two subviews for showing data: A label for the country title along with its two-letter code, and a table view for the rest of it. As you see, there’s a lot of data that is being returned, but we are not going to use all of it. Actually, we will show only the following (besides the country name):

• Capital
• Continent
• Population
• Area in Square Km
• Currency
• Languages

Let’s get started by the easy one, the country name. While being in the getCountryInfo method and in the else case, add the next line to display the country name to the label existing right below the textfield:

// Set the country name to the respective label.
                self.lblCountry.text = [NSString stringWithFormat:@"%@ (%@)", [self.countryDetailsDictionary objectForKey:@"countryName"], [self.countryDetailsDictionary objectForKey:@"countryCode"]];

This will display something like: ITALY (IT).

In the same else case, add the next two lines as well, in order to reload the data in the table view and make it appear (initially the table view is hidden):

// Reload the table view.
                [self.tblCountryDetails reloadData];

                // Show the table view.
                self.tblCountryDetails.hidden = NO;

After the above couple of modifications, your else case in the completion handler block should look like this:

 else{
                // Set the country name to the respective label.
                self.lblCountry.text = [NSString stringWithFormat:@"%@ (%@)", [self.countryDetailsDictionary objectForKey:@"countryName"], [self.countryDetailsDictionary objectForKey:@"countryCode"]];

                // Reload the table view.
                [self.tblCountryDetails reloadData];

                // Show the table view.
                self.tblCountryDetails.hidden = NO;
            }

Our work in this method is over, so let’s focus on the table view. Initially, go to the tableView:numberOfRowsInSection: and change the return 0; command to this:

-(NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section{
    return 7;
}

We want 7 rows to exist in our table view. We’ll use the first six rows to display the data I mentioned above, and in the last row we’ll have a cell that will let us get navigated into a new view controller, where we’ll get the neighbour countries of the selected one.

Next, we’ll work in the tableView:cellForRowAtIndexPath: method. As you see, there’s the following initial implementation, where the cell is dequeued or created if it does not exist:

-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath{
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"cell"];
    if (cell == nil) {
        cell = [[UITableViewCell alloc] initWithStyle:UITableViewCellStyleSubtitle reuseIdentifier:@"Cell"];
        cell.accessoryType = UITableViewCellAccessoryNone;
        cell.selectionStyle = UITableViewCellSelectionStyleNone;
    }

    return cell;
}

Notice that both the accessory type and the selection style are set to None for all cells.

Our work here is quite easy. We’ll use a switch statement, in which we will check the index of each row. Depending on this value, we will extract the proper data from the countryDetailsDictionary dictionary and we’ll assign it to the cell’s text label. At the same time, we’ll add a short descriptive text as a subtitle on each cell. Let’s see it:

-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath{
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"cell"];
    if (cell == nil) {
        cell = [[UITableViewCell alloc] initWithStyle:UITableViewCellStyleSubtitle reuseIdentifier:@"Cell"];
        cell.accessoryType = UITableViewCellAccessoryNone;
        cell.selectionStyle = UITableViewCellSelectionStyleNone;
    }

    switch (indexPath.row) {
        case 0:
            cell.detailTextLabel.text = @"Capital";
            cell.textLabel.text = [self.countryDetailsDictionary objectForKey:@"capital"];
            break;
        case 1:
            cell.detailTextLabel.text = @"Continent";
            cell.textLabel.text = [self.countryDetailsDictionary objectForKey:@"continentName"];
            break;
        case 2:
            cell.detailTextLabel.text = @"Population";
            cell.textLabel.text = [self.countryDetailsDictionary objectForKey:@"population"];
            break;
        case 3:
            cell.detailTextLabel.text = @"Area in Square Km";
            cell.textLabel.text = [self.countryDetailsDictionary objectForKey:@"areaInSqKm"];
            break;
        case 4:
            cell.detailTextLabel.text = @"Currency";
            cell.textLabel.text = [self.countryDetailsDictionary objectForKey:@"currencyCode"];
            break;
        case 5:
            cell.detailTextLabel.text = @"Languages";
            cell.textLabel.text = [self.countryDetailsDictionary objectForKey:@"languages"];
            break;
        case 6:
            cell.textLabel.text = @"Neighbour Countries";
            cell.accessoryType = UITableViewCellAccessoryDisclosureIndicator;
            cell.selectionStyle = UITableViewCellSelectionStyleDefault;
            break;

        default:
            break;
    }

    return cell;
}

Pay special attention to the last case, where we add the cell that will take us to the neighbour countries list. For this cell only, we set the disclosure indicator as the accessory type and the default selection style. That’s because we want it to prompt us to tap it, and to be highlighted when is tapped.

Now you can run the app and see it functioning properly for the first time. Type a country’s name in the text field, and wait until you see its details on the table view. Always remember that these details are fetched in real time from a web server as JSON data, and our app is the one that makes it possible to view that data!

Creating a JSON

Further than just converting JSON data into a Foundation object (NSArray, NSDictionary), the NSJSONSerialization class can also help us convert data stored in Foundation objects to JSON format. In the previous sections we managed to implement the first case and make our app work great. Now, we will see how to produce JSON data.

If you look closely in the view controller when running the app, there is a Compose bar button item at the right side of the navigation bar:

Using this button we will perform two things: The first one is to create a JSON string using the NSJSONSerialization class. This string will contain just the country data displayed on our view controller, excluding all the data that we don’t use. The second is to send that string via e-mail, so we’ll make the standard iOS mail view controller appear.

Our work will take place in the sendJSON: IBAction method. We’ll begin by creating a new dictionary (NSDictionary) that will contain only the values we want:

- (IBAction)sendJSON:(id)sender {
    // Create a dictionary containing only the values we care about.
    NSDictionary *dictionary = @{@"countryName": [self.countryDetailsDictionary objectForKey:@"countryName"],
                                 @"countryCode": [self.countryDetailsDictionary objectForKey:@"countryCode"],
                                 @"capital": [self.countryDetailsDictionary objectForKey:@"capital"],
                                 @"continent": [self.countryDetailsDictionary objectForKey:@"continentName"],
                                 @"population": [self.countryDetailsDictionary objectForKey:@"population"],
                                 @"areaInSqKm": [self.countryDetailsDictionary objectForKey:@"areaInSqKm"],
                                 @"currency": [self.countryDetailsDictionary objectForKey:@"currencyCode"],
                                 @"languages": [self.countryDetailsDictionary objectForKey:@"languages"]
                                 };

}

Now the most important part: We’ll convert that dictionary into JSON data. That’s just a matter of one line:

- (IBAction)sendJSON:(id)sender {
    ...

    // Convert the dictionary into a JSON data object.
    NSData *JSONData = [NSJSONSerialization dataWithJSONObject:dictionary options:NSJSONWritingPrettyPrinted error:nil];

}

The above does all the magical work. However, we have a problem here: The converted object is a NSData object, and if you try to display its contents you’ll get something like that:

<7b0a2020 20224174 20224575 20226361 20226375 22475222 22617265 30303022 31303030 31333139 47726565 63792220 65732220 67756167 70697461 22636f75 6e747279 436f6465 22203a20 2c0a2020 226c616e 3a202265 6c2d4752 2c656e2c 6672222c 0a202022 636f756e 7472794e 616d6522 203a2022 6365222c 636f6e74 696e656e 7422203a 726f7065 222c0a20 7272656e 3a202245 5552222c 706f7075 6c617469 6f6e2220 3a202231 61496e53 714b6d22 34302e30 6c22203a 68656e73 220a7d>

Of course, this is not readable by humans, so how can we show and send the actual JSON string? Well, we’ll do a small trick, which is shown below:

- (IBAction)sendJSON:(id)sender {
    ...

    // Convert the JSON data into a string.
    NSString *JSONString = [[NSString alloc] initWithData:JSONData encoding:NSUTF8StringEncoding];

}

As you see, we simply convert the NSData object into a NSString object using the above way. This is safe to do, as we already know that a JSON value is a string value. If we use a NSLog command at this point, here’s what we’ll see on the console:

{
  "countryCode" : "GR",
  "languages" : "el-GR,en,fr",
  "countryName" : "Greece",
  "continent" : "Europe",
  "currency" : "EUR",
  "population" : "11000000",
  "areaInSqKm" : "131940.0",
  "capital" : "Athens"
}

That’s great! It’s what exactly we want, and by seeing this we can be sure that our dictionary was successfully converted into a JSON string. Now, let’s make our example more complete, by making it capable of sending the above JSON string via e-mail. To make our work easier, I’ve already imported the necessary library (MFMailComposeViewController), and have adopted the respective protocol (MFMailComposeViewControllerDelegate) regarding the e-mail view controller, so we just need to present it here.

One basic thing you should always have in mind when using the MFMailComposeViewController class for displaying the e-mail view controller, is that you should check if the device can actually send e-mails. We’ll perform that check here, and then we’ll do these:

1. We’ll initialize a MFMailComposeViewController object and we’ll make the ViewController class its delegate.
2. We’ll set the subject of the e-mail.
3. We’ll set the body of the e-mail, which obviously is the JSON string we earlier produced.
4. We’ll present the view controller.

Let’s see all that:

- (IBAction)sendJSON:(id)sender {
    ...

    if ([MFMailComposeViewController canSendMail]) {
        MFMailComposeViewController *mailViewController = [[MFMailComposeViewController alloc] init];
        mailViewController.mailComposeDelegate = self;

        [mailViewController setSubject:@"Country JSON"];

        [mailViewController setMessageBody:JSONString isHTML:NO];

        [self presentViewController:mailViewController animated:YES completion:nil];
    }
}

The IBAction method is now ready. Notice that the mailComposeController:didFinishWithResult:error: delegate method of the * MFMailComposeViewControllerDelegate* protocol has already been implemented, so no more action is required from us.

Go and test the app once again. You’ll find out that the mail view controller is appeared (modally), and the JSON string is automatically set as the body of the e-mail.

Downloading the Neighbour Countries

As you have seen up to here, handling JSON data is really easy with the NSJSONSerialization class. Now, it’s time to move to the second part of the app, where we’ll download data regarding the neighbour countries of the selected one, but this time it’s going to be in XML format. Through the next sections you’ll see how you can use the NSXMLParser class for parsing XML data, and you’ll find out how easy it is to end up with the needed logic for extracting the data.

In order to download the neighbours of the selected country, it’s necessary to provide to the URL that we’ll call a unique value regarding the country, named geonameId. That value was returned along with the rest of the data, and if you look closely to the dictionary contents we previously logged in the debugger, you’ll find it there. So, first of all, we must make the ViewController class send the geonameId value to the NeighboursViewController, and then proceed to the rest of the work. Open the NeighboursViewController.h and declare the following property:

@interface NeighboursViewController : UIViewController 

...

@property (nonatomic, strong) NSString *geonameID;

@end

As you assume, in this property we’ll pass the value we want. Now, back to the ViewController.m file, go to the prepareForSegue:sender: method. This one is called before the new view controller actually gets loaded, so it’s the best place to set the geonameId value to the geonameID property. Add the next code segment:

-(void)prepareForSegue:(UIStoryboardSegue *)segue sender:(id)sender{
    if ([segue.identifier isEqualToString:@"idSegueNeighbours"]) {
        NeighboursViewController *neighboursViewController = [segue destinationViewController];
        neighboursViewController.geonameID = [self.countryDetailsDictionary objectForKey:@"geonameId"];        
    }
}

Having this property set, we are able to proceed to our work. Let’s continue by downloading the neighbour countries data, as we previously did with the country’s details data. Go to the NeighboursViewController.m file, in the private class section, and declare the next method:

@interface NeighboursViewController ()

-(void)downloadNeighbourCountries;

@end

We want the neighbour countries data to be downloaded when the view controller gets loaded, so go to the viewDidLoad method and call it:

- (void)viewDidLoad
{
    ...

    // Download the neighbour countries data.
    [self downloadNeighbourCountries];
}

Now, let’s see its implementation. The first thing we have to do is to specify the URL that we’ll get the data from. Once we have it formed, we’ll call the downloadDataFromURL:withCompletionHandler: class method to perform the actual download. Let’s see everything up to this point:

-(void)downloadNeighbourCountries{
    // Prepare the URL that we'll get the neighbour countries from.
    NSString *URLString = [NSString stringWithFormat:@"http://api.geonames.org/neighbours?geonameId=%@&username=%@", self.geonameID, kUsername];

    NSURL *url = [NSURL URLWithString:URLString];

    // Download the data.
    [AppDelegate downloadDataFromURL:url withCompletionHandler:^(NSData *data) {
        // Make sure that there is data.
        if (data != nil) {

        }
    }];
}

Simple as that! In the next part we are going to begin parsing the data in the above if clause, and we’ll implement all the necessary delegate methods of the parser that will help us to extract the exact data we need.

Parsing the XML Data

In order to parse an XML file or XML data in general, iOS SDK provides the NSXMLParser class. This one performs all the hard work on the background by going through all the data (by parsing them), and it provides us with some really useful delegate methods. Using them, we can have full control over parsing and handle any data found, in any way we want. In this example, we’ll use some of those delegate methods, and we’ll add all the data we are interested in to an array.

Being more specific, let me introduce you the delegate methods of the NSXMLParser class we’ll use, and what each of them is for. For clarification reasons only, I need to say that every XML data that’s about to be parsed, is considered as an XML document by iOS. Keep that in mind when reading next.

The delegate methods now:

1. parserDidStartDocument: This one is called when the parsing actually starts. It’s obvious that is called just once per XML document.
2. parserDidEndDocument: This one is the complement of the first one, and is called when the parser reaches the end of the XML data.
3. parser:parseErrorOccurred: This delegate method is called when an error occurs during the parsing. The method contains an error object, which you can use to define the actual error.
4. parser:didStartElement:namespaceURI:qualifiedName:attributes: This one is called when the opening tag of an element is found.
5. parser:didEndElement:namespaceURI:qName: On the contrary to the above method, this is called when the closing tag of an element is found.
6. parser:foundCharacters: This method is called during the parsing of the contents of an element. Its second argument is a string value containing the character that was just parsed.

Now that you know the delegate methods we’re about to use in our sample app, let’s discuss a bit about the logic that we’ll follow. Well, as it’s quite possible that multiple results will be returned after a call on the GeoNames API, it’s obvious that we’ll have to insert the parsed data into an array. But, what exactly are we going to add to this array?

To answer the above question, we just have to pay a visit to the GeoNames website and perform an API call using the browser, so we see what is being returned when asking for neighbour countries. There’s no simpler option than using the example link of the website, which takes us to a page with the following results:

Among all the values that been returned, we are going to use just two of them in our app: The toponymName and the name of the neighbour country.

With that in mind, we could say that for every neighbour country that will be parsed, we could add the above two values into a dictionary, and then add each dictionary to the array. In order to make this general idea more specific, let me say what we’ll do in each delegate method, in the order they were previously presented:

1. parserDidStartDocument: In this one we’ll initialize the array that will contain all the data regarding the neighbour countries.
2. parserDidEndDocument: As this method signals the end of the parsing, we’ll simply reload the table view, and we will display our data.
3. parser:parseErrorOccurred: This is just a sample app, so we won’t handle the error, we’ll only log it on the console.
4. parser:didStartElement:namespaceURI:qualifiedName:attributes: A quite important method, as we will initialize the dictionary in which we’ll store the toponym and the country name when the element is equal to the “” value. Moreover, we’ll assign the name of the current element to a property, as we’ll need to know it when parsing characters.
5. parser:didEndElement:namespaceURI:qName: When the closing “” tag is found, the dictionary containing the two values of interest will be added to the array. Besides that, when parsing either the “” or the “” closing tags, the respective found values will be added to the dictionary.
6. parser:foundCharacters: When the current element is equal to “” or to “” then we’ll store the found characters into a mutable string. The value of that string is the one we’ll add to the dictionary when the closing tag of the respective element is parsed.

Enough with theory though, let’s start writing some code. At the private section of the class, add the following properties:

@interface NeighboursViewController ()

...

@property (nonatomic, strong) NSXMLParser *xmlParser;

@property (nonatomic, strong) NSMutableArray *arrNeighboursData;

@property (nonatomic, strong) NSMutableDictionary *dictTempDataStorage;

@property (nonatomic, strong) NSMutableString *foundValue;

@property (nonatomic, strong) NSString *currentElement;


@end

• The xmlParser property is the one that we’ll use to parse the XML data.
• The arrNeighboursData property is the array that will contain all of the desired data after the parsing has finished.
• The dictTempDataStorage property is the dictionary in which we’ll temporarily store the two values we seek for each neighbour country until we add it to the array.
• The foundValue mutable string will be used to store the found characters of the elements of interest.
• The currentElement string will be assigned with the name of the element that is parsed at any moment.

Now, go to the downloadNeighbourCountries method, and add the code shown below in the completion handler block:

-(void)downloadNeighbourCountries{
    // Prepare the URL that we'll get the neighbour countries from.
    NSString *URLString = [NSString stringWithFormat:@"http://api.geonames.org/neighbours?geonameId=%@&username=%@", self.geonameID, kUsername];

    NSURL *url = [NSURL URLWithString:URLString];

    // Download the data.
    [AppDelegate downloadDataFromURL:url withCompletionHandler:^(NSData *data) {
        // Make sure that there is data.
        if (data != nil) {
            self.xmlParser = [[NSXMLParser alloc] initWithData:data];
            self.xmlParser.delegate = self;

            // Initialize the mutable string that we'll use during parsing.
            self.foundValue = [[NSMutableString alloc] init];

            // Start parsing.
            [self.xmlParser parse];
        }
    }];
}

With these four lines in the block, we initialize the parser object, we set our class as its delegate, we initialize the mutable string that we’ll use for storing the parsed values and finally we start parsing. Note that I have already adopted a required protocol, the NSXMLParserDelegate.

Let’s start working on the delegate methods now, and let’s see them in the order the were presented above. The first one:

-(void)parserDidStartDocument:(NSXMLParser *)parser{
    // Initialize the neighbours data array.
    self.arrNeighboursData = [[NSMutableArray alloc] init];
}

As I have already said, this delegate method signals the beginning of the parsing, so we initialize our array. The next one:

-(void)parserDidEndDocument:(NSXMLParser *)parser{
    // When the parsing has been finished then simply reload the table view.
    [self.tblNeighbours reloadData];
}

After the parsing has finished, we simply reload the data on the table view. For the time being nothing happens, but we’ll work on that at the next section. Next:

-(void)parser:(NSXMLParser *)parser parseErrorOccurred:(NSError *)parseError{
    NSLog(@"%@", [parseError localizedDescription]);
}

Nothing difficult here too, as we simply display the error description on the console.

-(void)parser:(NSXMLParser *)parser didStartElement:(NSString *)elementName namespaceURI:(NSString *)namespaceURI qualifiedName:(NSString *)qName attributes:(NSDictionary *)attributeDict{

    // If the current element name is equal to "geoname" then initialize the temporary dictionary.
    if ([elementName isEqualToString:@"geoname"]) {
        self.dictTempDataStorage = [[NSMutableDictionary alloc] init];
    }

    // Keep the current element.
    self.currentElement = elementName;
}

Two things happen here: If the parser is about to start parsing the data of a new country, then we initialize the dictionary. The second is that we store the current element name (you’ll see why in the last delegate method).

-(void)parser:(NSXMLParser *)parser didEndElement:(NSString *)elementName namespaceURI:(NSString *)namespaceURI qualifiedName:(NSString *)qName{

    if ([elementName isEqualToString:@"geoname"]) {
        // If the closing element equals to "geoname" then the all the data of a neighbour country has been parsed and the dictionary should be added to the neighbours data array.
        [self.arrNeighboursData addObject:[[NSDictionary alloc] initWithDictionary:self.dictTempDataStorage]];
    }
    else if ([elementName isEqualToString:@"name"]){
        // If the country name element was found then store it.
        [self.dictTempDataStorage setObject:[NSString stringWithString:self.foundValue] forKey:@"name"];
    }
    else if ([elementName isEqualToString:@"toponymName"]){
        // If the toponym name element was found then store it.
        [self.dictTempDataStorage setObject:[NSString stringWithString:self.foundValue] forKey:@"toponymName"];
    }

    // Clear the mutable string.
    [self.foundValue setString:@""];
}

This delegate method is called when the closing tag of an element has been parsed. If the element is equal to the “geoname” value, then we know that the data of a country was parsed, so we can add the dictionary to the array. Also, if the element is any of the two we care about, then we store the found value to the dictionary. At the end, we clear the mutable string from any contents, so it will be ready for new values to be appended to it. The last one:

-(void)parser:(NSXMLParser *)parser foundCharacters:(NSString *)string{
    // Store the found characters if only we're interested in the current element.
    if ([self.currentElement isEqualToString:@"name"] ||
        [self.currentElement isEqualToString:@"toponymName"]) {

        if (![string isEqualToString:@"\n"]) {
            [self.foundValue appendString:string];
        }
    }
}

Here you can see why the currentElement property is needed for. In case that the current element is any of the two we are interested in, then we keep the actual values found between the opening and closing tags. If you notice, you’ll see that I check for the new line string (“\n”), and if the found string is other than that, then I’m appending it to the foundValue property. That’s because after having tested the app, I noticed that a new line string was parsed before the country name, so this is just a workaround to that problem.

Our app now is capable to download XML data, and to parse it successfully. What we have only left, is to display it.

Populating the Parsed Data

In the starter app you downloaded, there’s already a table view with an initial implementation, waiting for us to do the proper modifications and display our data. As you may have guessed, the datasource of the table view is going to be the arrNeighboursData array. We’ll begin working on the data display by going first to the tableView:numberOfRowsInSection: method. In this one, replace this:

-(NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section{
    return 0;
}

With this:

-(NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section{
    return self.arrNeighboursData.count;
}

By doing that, the table view will return as many rows as the neighbour countries are.

Next, let’s go to the tableView:cellForRowAtIndexPath: method and let’s display our data. Before I give you the implementation, let me remind you that a dictionary object exists in every single position of the array. Let’s see the method now:

-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath{
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"cell"];
    if (cell == nil) {
        cell = [[UITableViewCell alloc] initWithStyle:UITableViewCellStyleSubtitle reuseIdentifier:@"Cell"];
        cell.accessoryType = UITableViewCellAccessoryNone;
        cell.selectionStyle = UITableViewCellSelectionStyleNone;
    }

    cell.textLabel.text = [[self.arrNeighboursData objectAtIndex:indexPath.row] objectForKey:@"name"];
    cell.detailTextLabel.text = [[self.arrNeighboursData objectAtIndex:indexPath.row] objectForKey:@"toponymName"];

    return cell;
}

As you see, in the text label of the cell we assign the name of the country, and we set the toponym name to the subtitle label.

Everything is ready now, so you can go and try the app. After you have typed a country name in the initial view controller, tap on the Neighbour Countries cell to make the app download and parse the neighbour countries of the one you chose. Then, wait until the new data appear on the table view we just set up.

Summary

Performing simple but crucial operations over JSON and XML data, is proved to be a relatively simple job. NSJSONSerialization and NSXMLParser classes are both very handy and powerful, and once you know how to use them you can work with the two respective data formats fast and painlessly. As you found out while you were reading this tutorial, I didn’t get into many, hard details of each class. I did this on purpose, as my primary target was to give you a way to start working with them, not to turn you into experts at once. In many cases, what I showed you here is just enough to let you handle any data your app is about to manage, but even in the opposite case, you now know the tools you should use.

For your reference, you can download the complete Xcode project from here.

As always, I hope you found this tutorial useful. Until next time, leave us your thoughts or anything else you wish to share with us!

One of the not so well-known frameworks existing on iOS (and Mac OS), is the Event Kit framework. This framework has one purpose only, to let us access the calendars, the events and the reminders of a device, and work with them. If you have ever been wondered about how you can create custom events through your app, or how to set reminders without using the Reminders app, then the Event Kit is the answer you’re looking for. Through this tutorial, you will have the chance to meet it, as you’ll get to know the most important aspects of it.

Before we start working with it, I think it would be useful to mention a few facts about the Event Kit framework. What actually the framework does, is to provide access to the Calendar and Reminders apps, and make your own app capable of retrieving information, or adding new. Behind of both of these apps, there is the same database, named Calendar Database. What you can do with the framework is to create, edit and delete both events and reminders. Events are displayed in the Calendar app, while reminders are (obviously) displayed in the Reminders app. Further than that, you are given the ability to create or delete calendars, and furthermore, to perform more advanced tasks, such as settings alarms for an upcoming event or reminder, or making them recurring.

When using the Event Kit framework, you should always have in mind that the user must grant access to either Calendar or Reminders apps. Upon the first launch of an app that uses the framework, an alert view asking for the user consent must appear, and it’s up to users to decide whether your app will be able to work with any of the above resources. After all, asking for user permissions is something that always happen in cases of frameworks that deal with other apps or resources of the iOS. Therefore, you should check if user has granted access, and then make the related to Event Kit features available.

As always, I recommend you to go through the Apple documentation as well for getting a greater level of understanding on the topic. Having said all that, let’s move on to make our introduction to the sample app of this tutorial.

Demo App Overview

Unlike to the most of the tutorials, in this one we are not going to create an app from the scratch. On the contrary, you should get a starter app from here in which I’ve already made an initial preparation. All the necessary view controllers, connections, and the basic structure have been created and configured. What we have to do, is to apply all the logic lying behind the app.

Before I present you all the aspects of the starter app, let me say a few words about what we’ll do in this tutorial. My goal is to make you familiar with the most important Event Kit classes, and the most important tasks of them. There are three major entities that one can work with: Calendar, events and reminders. There are great similarities on event and reminder handling, therefore we’ll focus only on events. We’ll see how to create, load, delete and display events, but not just that. We’ll also see how to add alarms to an event, and how to make a repeated, or in other words a recurring event. Further than that, we’ll focus on calendars too. We’ll learn how to create a new calendar, how to load and display existing calendars, and how to delete them. Everything will be presented in great details, performing one step at the time.

A couple of words about the starter app now. First of all, I must say that the sample app is a navigation based one. For managing all the aspects of the Event Kit framework, we’ll create a new class in which we’ll keep adding extra functionalities as we’ll move forward to the implementation. Regarding the view controllers, here’s in short which they are:

• ViewController: This is the default view controller created automatically with the project. In this one, we’ll display all the events of a selected calendar.
• CalendarsViewController: In this one, we’ll display all the local calendars existing on the device or the Simulator. Also, besides than simply showing calendars, we’ll be able to add new or delete existing ones.
• EditEventViewController: This is a quite important one, as we’ll do much of our work here. This is the place where we’ll edit a new event, we’ll set alarms and make our events recurring.
• DatePickerViewController: It’s clearly an auxiliary view controller. We won’t do anything on that, but we’ll use it to pick dates when it’s needed.

Lastly, you’ll find out that you’ll be able to test the app almost at every step of the development. You can do so either on Simulator, or on a real device.

Let’s see some action now, as we have a lot of work to do.

The EventManager Class

Let’s get started by creating a new class which we’ll use to manage the various Event Kit related tasks. We will name this class EventManager, and through it we’ll perform all the saving, loading, deleting and more operations.

On Xcode, go to the File > New > File… menu, and wait for the guide to appear. Then, select the Objective-C class option as the template for the new file, in the Cocoa-Touch category under the iOS section.

Click on the Next button, and at the second step make sure that in the Subclass of field the NSObject value is set. If not, then start typing it and Xcode will suggest it. In the Class field set the name of our class, which is EventManager as we already said.

Click on the Next button once again, and finally click on the Create to get finished.

After the pair of the new files appear on the Project Navigator, click on the EventManager.h file to edit it. During the implementation of the project, we are going to declare various properties and methods in here. However, the most important property and the one that we’ll start with, is an object of the EKEventStore class. This class is responsible in the Event Kit for handling almost everything: events, reminders, alarms, etc. As you’ll find out later, most of the important tasks will be performed using that property. Having said that, here’s the declaration:

@interface EventManager : NSObject

@property (nonatomic, strong) EKEventStore *eventStore;

@end

When using frameworks that deal with iOS features or built-in apps, such as the Calendar, the Reminders, or the Photos app, it’s necessary to get user permissions for accessing and modifying the resources you want. That happens with the Event Kit framework too. When our app will be launched for first time, a message asking for permissions will be shown to the user, and our app will be able to access the necessary resources (such as calendars) if only the user allows so. If there’s no user consent, then a wall will exist between the app and the wanted resources, and nothing will work. In our app, such a message should appear when the ViewController view controller gets loaded, where the events of a calendar will be listed. To let us know whether the user has granted access or not, we will use a boolean value. That value will be saved to the user defaults (NSUserDefaults) dictionary, and it will be retrieved upon subsequent launches of the app. So, let’s declare it:

@interface EventManager : NSObject
...
@property (nonatomic) BOOL eventsAccessGranted;

@end

Now, open the EventManager.m file to implement the init method of the class. At the moment, we’ll do just two things:

1. We will initialize the eventStore object.
2. We will check if a key for the eventsAccessGranted exists in the user defaults dictionary, and if so, we’ll load its value.
   • (instancetype)init
     {
     self = [super init];
     if (self) {
     self.eventStore = [[EKEventStore alloc] init];

     NSUserDefaults *userDefaults = [NSUserDefaults standardUserDefaults];
     
     // Check if the access granted value for the events exists in the user defaults dictionary.
     if ([userDefaults valueForKey:@"eventkit_events_access_granted"] != nil) {
         // The value exists, so assign it to the property.
         self.eventsAccessGranted = [[userDefaults valueForKey:@"eventkit_events_access_granted"] intValue];
     }
     else{
         // Set the default value.
         self.eventsAccessGranted = NO;
     }        
     

     }
     return self;
     }

As you see in the code snippet above, I used the * eventkit_events_access_granted* key name, but that’s something you can change if you don’t like it. Later, we’ll add a few more stuff in the init method.

Now let’s go to see how the EventManager class can be used. It’s quite important to always have in mind that the initialization of the eventStore object is a time-consuming process. Therefore, Apple strictly recommends to use one instance of that class for performing app-wide tasks, and not to initialize a new object every time that a feature of the Event Kit framework should be used. Following that rule, we are going to declare and initialize such an object in the AppDelegate class, and we are going to use it in all the view controllers of our app.

Open the AppDelegate.h file, and at the very top of it add the next line:

#import "EventManager.h"

Then, declare a new property, named eventManager:

@interface AppDelegate : UIResponder 

@property (strong, nonatomic) UIWindow *window;

@property (nonatomic, strong) EventManager *eventManager;

@end

Click on the AppDelegate.m file on the Project Navigator now, and go to the applicationDidBecomeActive: delegate method. In this one we’ll initialize the eventManager object:

- (void)applicationDidBecomeActive:(UIApplication *)application
{
    // Restart any tasks that were paused (or not yet started) while the application was inactive. If the application was previously in the background, optionally refresh the user interface.

    self.eventManager = [[EventManager alloc] init];

}

At this point, the first implementation of the EventManager class is over, but we’ll keep adding new code along our way. Also, by declaring the eventManager property in the AppDelegate class, we’ll be able to access it from anywhere in the app and manage all the Event Kit related tasks.

Asking for User Consent

In the previous section we declared a boolean value that we will use for knowing at any given time whether the user has allowed access to the events of the device. Now, before we go any further, let’s see how we can ask for user consent, and how the user response will be stored to the user defaults dictionary. Up to this point, we’ve added code to retrieve the value of that boolean property, however we haven’t done anything for storing it, so we’ll do that here as well.

Begin by opening the ViewController.m file, and by going to the top of the file. We’ll ask user to grant access to the events, using a private method. In this private method we’ll add the necessary code, and we’ll call it from the viewDidLoad method after a small period of time. The delay is necessary, because the event store object requires some time until it gets initialized. At the private class section, add the following declaration:

@interface ViewController ()

...

-(void)requestAccessToEvents;

@end

Next, implement it as shown right next:

-(void)requestAccessToEvents{
    [self.appDelegate.eventManager.eventStore requestAccessToEntityType:EKEntityTypeEvent completion:^(BOOL granted, NSError *error) {
        if (error == nil) {
            // Store the returned granted value.
            self.appDelegate.eventManager.eventsAccessGranted = granted;
        }
        else{
            // In case of error, just log its description to the debugger.
            NSLog(@"%@", [error localizedDescription]);
        }
    }];
}

The requestAccessToEntityType:completion: method above, expects to be provided with the proper entity type that we’re asking access to. There are two values that can be set: Either EKEntityTypeEvent when asking for access to events, or EKEntityTypeReminders when asking for access to reminders. The completion handler is called after the user has made a choice, and the returned granted value is assigned to the respective boolean property of our class. In case that any error occurs, we simply display its description on the debugger.

Now that this method is ready, let’s call it in the viewDidLoad:

- (void)viewDidLoad
{
    ..

    // Request access to events.
    [self performSelector:@selector(requestAccessToEvents) withObject:nil afterDelay:0.4];

}

By implementing the above stuff we manage to show a default, pre-made alert view to the user the first time the view controller is loaded, but we’re unable to store the response yet. As you may have noticed, we didn’t call any methods at all for storing the eventsAccessGranted property to the user defaults dictionary, we just assigned the user response to it. So, how are we going to succeed it?

The solution is simple, as we just have to override the setter method of the boolean property. In there, we’ll set the property’s value, and we’ll save it to the user dictionary too. Following that way, we don’t have to write any extra method just for saving the boolean value.

Go to the EventManager.m file, and add the next method implementation for the eventAccessGranted property:

-(void)setEventsAccessGranted:(BOOL)eventsAccessGranted{
    _eventsAccessGranted = eventsAccessGranted;

    [[NSUserDefaults standardUserDefaults] setValue:[NSNumber numberWithBool:eventsAccessGranted] forKey:@"eventkit_events_access_granted"];
}

Notice that we use the _eventsAccessGranted member variable that automatically gets synthesized, instead of the self.eventsAccessGranted property, as that’s the proper way to set its value.

Now, the app is able to store the boolean values to the user info dictionary every time a new value is assigned to them.

The next figure illustrates the alert view asking for user consent when the app runs for the first time.

Listing Calendars

In order to work with calendars, it’s necessary to load the CalendarsViewController view controller and push it to the navigation stack. In the starter app all the necessary connections between the view controllers have been already made, and we only need to add one command for letting it appear. However, we should always check whether the user has allowed access to the events, and if not we shouldn’t load the calendars view controller when the Calendars bar button item gets tapped.

To do that, open the ViewController.m file, and find the showCalendars: IBAction method definition. In it, add the following code:

- (IBAction)showCalendars:(id)sender {
    if (self.appDelegate.eventManager.eventsAccessGranted) {
        [self performSegueWithIdentifier:@"idSegueCalendars" sender:self];
    }
}

That’s great, as the calendars view controller will appear now if only the user has granted access to the events of the device.

Let’s focus now on how to display all existing event calendars. Before we proceed, I must make clear that there are various types of calendars (such as local, on iCloud, etc). For the sake of the simplicity however, we’ll work only with local calendars, meaning with calendars that are stored on the device.

In order to list existing (local) calendars, it’s required to have data to show. Therefore, we’ll begin here by implementing a custom method on the EventManager class, and in there we’ll get all the local calendars from the event store object. Initially, go to the EventManager.h file, and declare the next method:

@interface EventManager : NSObject

...

-(NSArray *)getLocalEventCalendars;

@end

That’s the first one of a series of methods that we’re about to implement in this tutorial. Now, open the EventManager.m file, and define it:

-(NSArray *)getLocalEventCalendars{
    NSArray *allCalendars = [self.eventStore calendarsForEntityType:EKEntityTypeEvent];
    NSMutableArray *localCalendars = [[NSMutableArray alloc] init];

    for (int i=0; i
Let's discuss it a bit. At first, you notice that we get an array with all calendars of any type using the calendarsForEntityType: method of the event store object and by specifying the EKEntityTypeEvent as the kind of the calendars we want to get. Note that this array contains calendars of all types, so we must get only the local ones. For that reason, we initialize a mutable array, and using a loop we check the type of each returned calendar. Every local calendar found in the first array is stored to the mutable one, which is returned at the end. Inside the loop, each calendar (the current calendar) is stored to a EKCalendar object temporarily. As you understand, the EKCalendar class represents a calendar in the Event Kit framework.
Our work here is over for now, so let's head directly to the CalendarsViewController.m file. The first thing we have to do here, is to declare a private array in which they are going to be stored all the calendars retrieved in the above method. So, go to the private section of the class and declare one. Along with it, declare a private method as well, which we'll use for loading the calendars:
@interface CalendarsViewController ()

...

@property (nonatomic, strong) NSArray *arrCalendars;

-(void)loadEventCalendars;

@end

Let's implement the loadEventCalendars method:
-(void)loadEventCalendars{
    // Load all local event calendars.
    self.arrCalendars = [self.appDelegate.eventManager getLocalEventCalendars];

    // Reload the table view.
    [self.tblCalendars reloadData];
}

What we did in the above snippet is really simple. We just made a call to the new method of the EventManager class, we assigned all found calendars to the arrCalendars array, and we reloaded the table view. The last command is necessary if you want to show the loaded data to the table view.
The above method should be called, and that's something that we'll do in the viewDidLoad method:
- (void)viewDidLoad
{
    ...

    // Load all local event calendars.
    [self loadEventCalendars];
}

Now, let's work a bit with the table view methods. At first, let's specify how many rows should be returned, therefore change the next method as shown:
-(NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section{
    return self.arrCalendars.count;
}

Note that later we'll modify it again, but for now we're fine. What we must do next, is to display the title of each loaded local calendar. Go to the tableView:cellForRowAtIndexPath: method, and replace the return nil; command with the following few lines:
-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath{
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"idCellCalendar"];

    EKCalendar *currentCalendar = [self.arrCalendars objectAtIndex:indexPath.row];

    cell.textLabel.text = currentCalendar.title;

    return cell;
}

Each calendar of the arrCalendars array is firstly assigned to an EKCalendar object, and then its title is set to the textLabel of the cell. If you run the app now, any existing calendars in the device will be listed in our app.

The purpose of this view controller, besides than demonstrating how to create and list calendars, is to let us select one for adding events, so before we finish our work in this section we must indicate the selected calendar on the table view, and store it as well. Actually, each calendar has a unique identifier string, so instead of storing a calendar object when users selects one, we'll just save its identifier. That's simpler to do, and by using the identifier we can retrieve the respective calendar from the event store object.
The selected calendar identifier will be assigned to a new property that we'll add to the EventManager class, therefore go to the EventManager.h file and declare the next one:
@interface EventManager : NSObject

...

@property (nonatomic, strong) NSString *selectedCalendarIdentifier;

@end

Before we go back to the CalendarsViewController class, we must perform two tasks: The first one is to override the setter method of this property, so the identifier gets saved to the user defaults dictionary upon value assignment, and the second is to load it in the init method. Let's see them:
-(void)setSelectedCalendarIdentifier:(NSString *)selectedCalendarIdentifier{
    _selectedCalendarIdentifier = selectedCalendarIdentifier;

    [[NSUserDefaults standardUserDefaults] setObject:selectedCalendarIdentifier forKey:@"eventkit_selected_calendar"];
}

There is nothing especially hard here, so let's go to the init method to load that value, if exists.
- (instancetype)init
{
    self = [super init];
    if (self) {
        ...       

        // Load the selected calendar identifier.
        if ([userDefaults objectForKey:@"eventkit_selected_calendar"] != nil) {
            self.selectedCalendarIdentifier = [userDefaults objectForKey:@"eventkit_selected_calendar"];
        }
        else{
            self.selectedCalendarIdentifier = @"";
        }
    }
    return self;
}

If the eventkit_selected_calendar key exists in the user defaults dictionary then we load the identifier of the selected calendar, otherwise we set the empty string as the value of the selectedCalendarIdentifier property.
Back to the CalendarsViewController now, and in the tableView:cellForRowAtIndexPath: table view method. Continuing its implementation, initially we'll set the accessory type of the cell to None, meaning no accessory type will exist. Then, we'll check if the selectedCalendarIdentifier property has a value other than the empty string, and if so, we'll set the checkmark accessory type to the cell that the respective calendar's identifier matches to that property's value. However, if the empty string has been set as the value of the selectedCalendarIdentifier property, then we'll select by default the first calendar listed on the table view. Here it is:
-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath{
    ...

    cell.accessoryType = UITableViewCellAccessoryNone;

    if (self.appDelegate.eventManager.selectedCalendarIdentifier.length > 0) {
        if ([currentCalendar.calendarIdentifier isEqualToString:self.appDelegate.eventManager.selectedCalendarIdentifier]) {
            cell.accessoryType = UITableViewCellAccessoryCheckmark;
        }
    }
    else{   
        if (indexPath.row == 0) {
            cell.accessoryType = UITableViewCellAccessoryCheckmark;
        }
    }

    return cell;
}

If you run the app now, you'll see that the first calendar displayed on the table view is selected by default. If you try to tap on any other calendar (if any exists), you'll see that the selection doesn't change. Let's fix that.
Add the tableView:didSelectRowAtIndexPath: table view method, along with the next three lines:
-(void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath{
    // Deselect the tapped row.
    [[tableView cellForRowAtIndexPath:indexPath] setSelected:NO];

    // Keep the identifier value of the selected calendar.
    self.appDelegate.eventManager.selectedCalendarIdentifier = [[self.arrCalendars objectAtIndex:indexPath.row] calendarIdentifier];

    // Reload the table view.
    [self.tblCalendars reloadData];
}

With the first one, the tapped row is deselected. The second one is the most important, as we actually store the identifier of the selected calendar. Finally, we reload the table view so the checkmark accessory type to be displayed next to the selected calendar's title.
Feel free to try the app again. This time you'll see that your selection gets changed (as long as you have more than one calendar).
Creating a Calendar
If you go to the Main.storyboard file and in the Calendars View Controller scene, you will notice that there's a prototype cell there which contains a textfield. So far we haven't used it, but we're going to do so here. Actually, we will use the textfield for typing a title for a new calendar, which in turn will be stored to the collection of the local calendars.
Besides that, if you run the app and load the CalendarsViewController view controller, you'll see that at the right side of the navigation bar there is an Edit bar button item. When it's tapped, we want to set the table view in editing mode, and display the cell with the textfield as well. Because of the editing mode of the table view, at the left side of each cell is going to appear the red minus button, which if tapped it will reveal the Delete button of the respective cell. Also, in the first row a green plus button will appear instead of the red one, as in this row the textfield will appear. Let's see everything step by step.
Initially, go to the editCalendars IBAction method definition, and add the next couple of lines:
- (IBAction)editCalendars:(id)sender {
    // Set the table in editing mode.
    [self.tblCalendars setEditing:!self.tblCalendars.isEditing animated:YES];

    // Reload the table view.
    [self.tblCalendars reloadData];

}

As I said, we want the cell with the textfield to be the first one displayed on the table view when editing. That means that we have to modify the tableView:cellForRowAtIndexPath: method so as to check whether the table view is in editing mode or not, and finally to properly act. Right below you are given the implementation of that method as it should be after doing all the necessary changes:
-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath{
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"idCellCalendar"];

    if (self.tblCalendars.isEditing) {
        if (indexPath.row == 0) {
            cell = [tableView dequeueReusableCellWithIdentifier:@"idCellEdit"];

            UITextField *textfield = (UITextField *)[cell viewWithTag:10];
            textfield.delegate = self;
        }
    }

    if (!self.tblCalendars.isEditing || (self.tblCalendars.isEditing && indexPath.row != 0)) {
        NSInteger row = self.tblCalendars.isEditing ? indexPath.row - 1 : indexPath.row;

        EKCalendar *currentCalendar = [self.arrCalendars objectAtIndex:row];

        cell.textLabel.text = currentCalendar.title;

        if (!self.tblCalendars.isEditing) {
            cell.accessoryType = UITableViewCellAccessoryNone;

            if (self.appDelegate.eventManager.selectedCalendarIdentifier.length > 0) {
                if ([currentCalendar.calendarIdentifier isEqualToString:self.appDelegate.eventManager.selectedCalendarIdentifier]) {
                    cell.accessoryType = UITableViewCellAccessoryCheckmark;
                }
            }
            else{

                if (indexPath.row == 0) {
                    cell.accessoryType = UITableViewCellAccessoryCheckmark;
                }
            }
        }
    }

    return cell;
}

Notice the following:

If editing, then we access the textfield using its tag value, which I set to 10. Also, we make our class the delegate of the textfield (keep in mind that I already have adopted the UITextFieldDelegate protocol, otherwise the respective line would issue a warning).
The row index of the selected cell is not constant, as when being in editing mode the first row contains the cell with the textfield. Therefore, we dynamically calculate the row index with this line: NSInteger row = self.tblCalendars.isEditing ? indexPath.row - 1 : indexPath.row;.

Further than modifying the above method, we must implement the tableView:editingStyleForRowAtIndexPath: too. With this one, the appropriate buttons will be placed at the left side of each cell, as I described earlier.
-(UITableViewCellEditingStyle)tableView:(UITableView *)tableView editingStyleForRowAtIndexPath:(NSIndexPath *)indexPath{
    if (indexPath.row == 0) {
        return UITableViewCellEditingStyleInsert;
    }
    else{
        return UITableViewCellEditingStyleDelete;
    }
}

Finally, we shouldn't forget that one more row should be displayed when being in editing mode. Therefore, modify the next method as shown exactly:
-(NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section{
    if (!self.tblCalendars.isEditing) {
        return self.arrCalendars.count;
    }
    else{
        return self.arrCalendars.count + 1;
    }
}

If you want, go and give the app a try. You'll notice that when tapping on the Edit button of the navigation bar, the table view enters in editing mode. However, when tapping on the Done button of the keyboard (if you type), or in the green (insert) button, nothing works yet.
What we want from both the Done button of the keyboard and the green button is to create a new calendar using the title typed in the textfield. Instead of writing the same thing twice, we'll create a private method to do that. Go to the private class section and declare the next method:
@interface CalendarsViewController ()

...

-(void)createCalendar;

@end

Let's see its implementation step by step now. The first thing we should do is to hide the keyboard. To do that, we need to access the textfield, but it is a subview of a cell and there isn't an IBOutlet property connected to it, so how do we handle it? Here's is the answer:
UITextField *textfield = (UITextField *)[[self.tblCalendars cellForRowAtIndexPath:[NSIndexPath indexPathForRow:0 inSection:0]] viewWithTag:10];
    [textfield resignFirstResponder];

Next, we must make sure that the user has actually typed a title, otherwise we shouldn't proceed:
// In case that no text was typed in the textfield then do nothing.
    if (textfield.text.length == 0) {
        return;
    }

When creating a new calendar, two values must be set: The title and the source of the calendar. The source is actually the type of the calendar, and in our case it's the Local source. Before we see how we specify the source of the calendar, let's create a new calendar object and let's set its title:
// Create a new calendar.
    EKCalendar *calendar = [EKCalendar calendarForEntityType:EKEntityTypeEvent
                                                  eventStore:self.appDelegate.eventManager.eventStore];

    // Set the calendar title.
    calendar.title = textfield.text;

In the first line you can see that we specify the Event as the entity type of the calendar, and we provide our event store object as the second parameter.
The source of the calendar cannot be assigned directly. Instead, we must go through all the available sources of the event store object using a loop, and when the Local source is found it should be assigned to our calendar. Here it is:
// Find the proper source type value.
    for (int i=0; i
With the above lines a new calendar is being created indeed, but it's not permanently stored. Here's how we can save it:
NSError *error;
    [self.appDelegate.eventManager.eventStore saveCalendar:calendar commit:YES error:&error];

    // If no error occurs then turn the editing mode off, store the new calendar identifier and reload the calendars.
    if (error == nil) {
        // Turn off the edit mode.
        [self.tblCalendars setEditing:NO animated:YES];

        // Store the calendar identifier.
        [self.appDelegate.eventManager saveCustomCalendarIdentifier:calendar.calendarIdentifier];

        // Reload all calendars.
        [self loadEventCalendars];
    }
    else{
        // Display the error description to the debugger.
        NSLog(@"%@", [error localizedDescription]);
    }

In case that no error occurs, then we turn off the editing mode of the table view, we save the identifier of the newly created calendar and finally we reload all calendars so they properly be displayed to the table view. But wait a minute, what's that saveCustomCalendarIdentifier: method?
As you have probably guessed, that's one more method we'll implement in the EventManager class, but before doing so, it's important to tell you what is for. So, it is used to store the identifier strings of the calendars we create in our demo app to the user defaults dictionary. That's not necessary in a real app to happen, but in our case I want to let us know what calendars were created by our app and what not. Later, when we'll have the calendar deletion feature implemented, nobody would like to delete a calendar other than those created by our app, even by mistake. In other words, we store the newly created calendar identifiers for safety reasons.
Before we proceed, let me give you the createCalendar method in one piece:
-(void)createCalendar{
    // Hide the keyboard. To do so, it's necessary to access the textfield of the first cell.
    UITextField *textfield = (UITextField *)[[self.tblCalendars cellForRowAtIndexPath:[NSIndexPath indexPathForRow:0 inSection:0]] viewWithTag:10];
    [textfield resignFirstResponder];

    // In case that no text was typed in the textfield then do nothing.
    if (textfield.text.length == 0) {
        return;
    }


    // Create a new calendar.
    EKCalendar *calendar = [EKCalendar calendarForEntityType:EKEntityTypeEvent
                                                  eventStore:self.appDelegate.eventManager.eventStore];

    // Set the calendar title.
    calendar.title = textfield.text;

    // Set the calendar source.
    calendar.source = EKSourceTypeLocal;


    // Save and commit the calendar.
    NSError *error;
    [self.appDelegate.eventManager.eventStore saveCalendar:calendar commit:YES error:&error];

    // If no error occurs then turn the editing mode off, store the new calendar identifier and reload the calendars.
    if (error == nil) {
        // Turn off the edit mode.
        [self.tblCalendars setEditing:NO animated:YES];

        // Store the calendar identifier.
        [self.appDelegate.eventManager saveCustomCalendarIdentifier:calendar.calendarIdentifier];

        // Reload all calendars.
        [self loadEventCalendars];
    }
    else{
        // Display the error description to the debugger.
        NSLog(@"%@", [error localizedDescription]);
    }
}

Let's focus now on the saveCustomCalendarIdentifier: method. At first, go to the EventManager.h file to declare it:
@interface EventManager : NSObject

...

-(void)saveCustomCalendarIdentifier:(NSString *)identifier;

@end

Before we implement it, let's give it some thought. As I said, its purpose is to store the identifiers of the newly created calendars, but how can we handle a bunch of them, not only when saving, but when loading them or later when deleting calendars? The best solution that we have at our disposal it to use an array, in which we'll add all identifiers, and then we'll store that array to the user defaults dictionary. 
That array doesn't have to be a public one, so go to the EventManager.m file and declare it privately:
@interface EventManager()

@property (nonatomic, strong) NSMutableArray *arrCustomCalendarIdentifiers;

@end

As you see it's a mutable array, because we want to be able to add and (later) remove objects.
Now, we can implement the method:
-(void)saveCustomCalendarIdentifier:(NSString *)identifier{
    [self.arrCustomCalendarIdentifiers addObject:identifier];

    [[NSUserDefaults standardUserDefaults] setObject:self.arrCustomCalendarIdentifiers forKey:@"eventkit_cal_identifiers"];
}

At first we add the new identifier string to the array, and then we save the array to the user defaults dictionary.
Let's go back to the CalendarsViewController.m file, and let's call the createCalendar method. The first place that should be called from is the textFieldShouldReturn: textfield delegate method:
-(BOOL)textFieldShouldReturn:(UITextField *)textField{
    [self createCalendar];

    return YES;
}

The second place that we should call it from is when tapping on the green insert button, but we must implement another table view method to do that:
-(void)tableView:(UITableView *)tableView commitEditingStyle:(UITableViewCellEditingStyle)editingStyle forRowAtIndexPath:(NSIndexPath *)indexPath{
    if (editingStyle == UITableViewCellEditingStyleInsert) {
        [self createCalendar];
    }
    else{

    }
}

So simple... In the else we'll add some code later, but for the time being we're perfect.
Give the app a shot again, and try to create a new calendar. If you followed everything step by step, then you can create a new calendar and also see it in the Calendars app of the device/Simulator.

Deleting a Calendar
To delete a calendar, the red Delete button of the respective cell must become visible, and that can be done in two ways: Either by tapping on the red minus button when being in editing mode, or by swiping on the respective cell towards left. When the Delete button gets tapped, it's our duty to check if the calendar that's about to be deleted is a custom one created by our app, or it's a calendar created by the Calendar or any other app. In the second case, we shouldn't allow users to delete it, therefore we'll show a relevant message. However, in cases that a calendar can be removed indeed, then we'll first ask for confirmation and then we'll proceed to the actual deletion.
We'll see everything in details, and the place we'll start from is the one we left off at the previous section. In the tableView:commitEditingStyle:forRowAtIndexPath: we have an empty else case, and the code we'll add there is executed when the user taps on the Delete button. Let's see the method fully implemented this time before we proceed:
-(void)tableView:(UITableView *)tableView commitEditingStyle:(UITableViewCellEditingStyle)editingStyle forRowAtIndexPath:(NSIndexPath *)indexPath{
    if (editingStyle == UITableViewCellEditingStyleInsert) {
        [self createCalendar];
    }
    else{
        // Keep the row index of the calendar that's about to be deleted.
        self.indexOfCalendarToDelete = indexPath.row - 1;

        // Show the confirmation alert view.
        [self confirmCalendarDeletion];
    }
}

In the else clause, we added just two lines. In the first one, we store to a property (that doesn't exist yet) the row index of the cell that contains the calendar that's about to be deleted. Note that when editing, the first row contains the cell with the textfield, and the calendar listing starts from the index 1. However, the first calendar index in the arrCalendars array is 0, and in order to have a match we decrease the row index by one.
In the second line we call a custom method, which doesn't exist yet too. In this one, we'll display the proper message using an alert view. At the moment, Xcode is showing a couple of errors, and that's because we refer to objects that do not exist, so let's declare them. Go to the private class section, and add the next lines:
@interface CalendarsViewController ()

...
@property (nonatomic) NSUInteger indexOfCalendarToDelete;

-(void)confirmCalendarDeletion;

@end

Let's see the implementation of the confirmCalendarDeletion method now:
-(void)confirmCalendarDeletion{
    // Check if the selected calendar is a custom one and can be actually deleted.
    NSString *identifier = [[self.arrCalendars objectAtIndex:self.indexOfCalendarToDelete] calendarIdentifier];
    if (![self.appDelegate.eventManager checkIfCalendarIsCustomWithIdentifier:identifier]) {
        // The selected calendar was not created by our app, so we shouldn't delete it.
        // Show a message to the user.
        [[[UIAlertView alloc] initWithTitle:@"EventKitDemo"
                                    message:@"You are not allowed to delete this calendar."
                                   delegate:nil
                          cancelButtonTitle:nil
                          otherButtonTitles:@"Okay", nil] show];
    }
    else{
        // The calendar can be deleted, but first ask for confirmation.
        // Ask for delete confirmation.
        UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"EventKitDemo"
                                                        message:@"Are you sure you want to delete the selected calendar?"
                                                       delegate:self
                                              cancelButtonTitle:@"Cancel"
                                              otherButtonTitles:@"Yes, delete", nil];

        [alert show];
    }
}

The logic here is simple: At first we get the identifier string of the calendar that's about to be deleted. In the respective line, you can see how we use the indexOfCalendarToDelete property. In order to find out whether the calendar is a custom one (created by our app) or not, we use another method of the EventManager class that we'll implement in a while. If the identifier doesn't match to any of the saved ones (remember that we previously saved the identifier of every new calendar), then we display a message to the user telling that deleting the selected calendar is not allowed. Otherwise, we ask for confirmation. Notice that we set our class as the delegate of the alert view. I have already adopted the UIAlertViewDelegate protocol in the starter app, so Xcode doesn't show a warning.
Let's implement the checkIfCalendarIsCustomWithIdentifier: method now. Initially, go to the EventManager.h class to declare it:
@interface EventManager : NSObject

...

-(BOOL)checkIfCalendarIsCustomWithIdentifier:(NSString *)identifier;

@end

Next, its implementation:
-(BOOL)checkIfCalendarIsCustomWithIdentifier:(NSString *)identifier{
    BOOL isCustomCalendar = NO;

    for (int i=0; i
If the calendar is found in the arrCustomCalendarIdentifiers array, then the YES value is returned, otherwise the returned value is NO. Before we go back to the CalendarsViewController class, we must take care of one more thing: That is to load the identifiers array from the user defaults dictionary when an EventManager object is initialized. Go to the init method and add the next lines:
- (instancetype)init
{
    self = [super init];
    if (self) {
        ...       

        // Load the custom calendar identifiers (if exist).
        if ([userDefaults objectForKey:@"eventkit_cal_identifiers"] != nil) {
            self.arrCustomCalendarIdentifiers = [userDefaults objectForKey:@"eventkit_cal_identifiers"];
        }
        else{
            self.arrCustomCalendarIdentifiers = [[NSMutableArray alloc] init];
        }
    }
    return self;
}

In case that no identifiers array is found in the user defaults dictionary, then we simply initialize the array.
Back to the CalendarsViewController now, let's handle the user's response to the deletion confirmation. In the following code, we first check if the user agrees to delete the calendar. Then, we get the proper calendar from the arrCalendars array, and we remove it using the event store object of the EventManager class. Next, if no problem arises, we check if the deleted calendar was the selected one in the table view (the one with the checkmark). If that's the case, then we set the empty string value to the selectedCalendarIdentifier property of the eventManager object, and finally we remove the deleted calendar's identifier from the identifiers collection array. Note that the last action is taken using one more custom method that we'll create in a while in the EventManager class. Here's the implementation:
-(void)alertView:(UIAlertView *)alertView clickedButtonAtIndex:(NSInteger)buttonIndex{
    // Delete the selected calendar if user selected so.
    if (buttonIndex == 1) {
        NSString *identifier = [[self.arrCalendars objectAtIndex:self.indexOfCalendarToDelete] calendarIdentifier];

        EKCalendar *calendarToDelete = [self.arrCalendars objectAtIndex:self.indexOfCalendarToDelete];

        NSError *error;
        if ([self.appDelegate.eventManager.eventStore removeCalendar:calendarToDelete commit:YES error:&error]) {
            // Check if the calendar that's about to be deleted is the selected one.
            if ([self.appDelegate.eventManager.selectedCalendarIdentifier isEqualToString:identifier]) {
                // In this case, set the empty string as the selectedCalendarIdentifier property's value.
                self.appDelegate.eventManager.selectedCalendarIdentifier = @"";
            }

            // Remove the current identifier from the collection of the custom calendar identifiers.
            [self.appDelegate.eventManager removeCalendarIdentifier:identifier];

            // Load the calendars once again.
            [self loadEventCalendars];
        }
        else{
            // Simply log the error description.
            NSLog(@"%@", [error localizedDescription]);
        }
    }
}

The actual job is being done using the removeCalendar:commit:error: method of the event store object.
Now, back to the EventManager.h class, let's declare the next one:
@interface EventManager : NSObject

...

-(void)removeCalendarIdentifier:(NSString *)identifier;

@end

The implementation is simple:
-(void)removeCalendarIdentifier:(NSString *)identifier{
    [self.arrCustomCalendarIdentifiers removeObject:identifier];

    [[NSUserDefaults standardUserDefaults] setObject:self.arrCustomCalendarIdentifiers forKey:@"eventkit_cal_identifiers"];
}

If you run the app now, you'll be able to delete your calendars.

Creating a Simple Event
In order to create an event, here is what we need to provide Event Kit with:

A title
A start date
An end date
A calendar

Up to now, we have seen how to deal with calendars and how to select one, so we just have to do the necessary implementation for adding a title and the couple of dates to an event. Almost of our work here is going to take place in the EditEventViewController class, but not only. As we previously did, we're going to enrich the EventManager class even more by adding new necessary methods and properties that will help us in our mission.
The EditEventViewController view controller is supposed to be pushed to the navigation stack when tapping on the add button (Plus) of the navigation bar. However, we should make it work only when the user has granted us access to the events stored in the device. Going into action, open the ViewController.m file, and locate the createEvent: IBAction method. Add the next simple code segment in order to make the EditEventViewController view controller able to be shown:
- (IBAction)createEvent:(id)sender {
    if (self.appDelegate.eventManager.eventsAccessGranted) {
        [self performSegueWithIdentifier:@"idSegueEvent" sender:self];
    }
}

The style of the table view existing in the EditEventViewController view controller is grouped, and the table view will contain initially sections (later we'll add a third section too). In the first section we are going to have the necessary cells for managing the basic data an event needs, while in the second section we are going to add some alarms. However, in this part we're going to focus on the first section only, we won't deal with alarms yet.
Open the EditEventViewController.m file and go to the private class section. The first thing we're about to do here, is to declare and initialize a few properties that we'll use for storing the event data (title, dates). Add the next lines:
@interface EditEventViewController ()

...

@property (nonatomic, strong) NSString *eventTitle;

@property (nonatomic, strong) NSDate *eventStartDate;

@property (nonatomic, strong) NSDate *eventEndDate;

@end

Now, go to the viewDidLoad method and do the following initializations:
- (void)viewDidLoad
{
    [super viewDidLoad];
    ...    
    // Set initial values.
    self.eventStartDate = nil;
    self.eventEndDate = nil;
}

Let's focus now a bit on the tableView:cellForRowAtIndexPath: table view method. As you see in the starter app, I have already added the following piece of code...
-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath{
    UITableViewCell *cell = nil;

    if (indexPath.section == 0) {
        // If the cell is nil, then dequeue it. Make sure to dequeue the proper cell based on the row.
        if (cell == nil) {
            if (indexPath.row == 0) {
                cell = [tableView dequeueReusableCellWithIdentifier:@"idCellTitle"];
            }
            else{
                cell = [tableView dequeueReusableCellWithIdentifier:@"idCellGeneral"];
            }
        }
    }
    else{
        if (cell == nil) {
            cell = [tableView dequeueReusableCellWithIdentifier:@"idCellGeneral"];
        }
    }

    return cell;
}

... which simply dequeues the proper cell in the first section and then it returns it. No logic still applied here, and that's something we'll do right now. As you see, for the first row is dequeued the cell that contains the textfield, while for the other two rows is dequeued the cell with the label. What we want to do here is quite straightforward: For the first row, we'll get the textfield and we'll set the value of the eventTitle property. For the other two cells, we'll either display the event's start and end dates, or we'll show a message that prompts the user to pick a date. Note that the each date object should be converted into a string object for being able to be assigned to the cell's label. Right below you're given the same table view method, where it has been added everything I just described:
-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath{
    UITableViewCell *cell = nil;

    if (indexPath.section == 0) {
        // If the cell is nil, then dequeue it. Make sure to dequeue the proper cell based on the row.
        if (cell == nil) {
            if (indexPath.row == 0) {
                cell = [tableView dequeueReusableCellWithIdentifier:@"idCellTitle"];
            }
            else{
                cell = [tableView dequeueReusableCellWithIdentifier:@"idCellGeneral"];
            }
        }


        switch (indexPath.row) {
            case 0:
                // The title of the event.
            {
                UITextField *titleTextfield = (UITextField *)[cell.contentView viewWithTag:10];
                titleTextfield.delegate = self;
                titleTextfield.text = self.eventTitle;
            }
                break;

            case 1:
                // The event start date.
                if (self.eventStartDate == nil) {
                    cell.textLabel.text = @"Select a start date...";
                }
                else{
                    cell.textLabel.text = [self.appDelegate.eventManager getStringFromDate:self.eventStartDate];
                }
                break;

            case 2:
                // The event end date.
                if (self.eventEndDate == nil) {
                    cell.textLabel.text = @"Select an end date...";
                }
                else{
                    cell.textLabel.text = [self.appDelegate.eventManager getStringFromDate:self.eventEndDate];
                }
                break;

            default:
                break;
        }
    }
    else{
        if (cell == nil) {
            cell = [tableView dequeueReusableCellWithIdentifier:@"idCellGeneral"];
        }        
    }

    return cell;
}

The new addition here is the getStringFromDate: method, which we must implement in the EventManager class. For starters, go to the EventManager.h file and declare it:
@interface EventManager : NSObject

...

-(NSString *)getStringFromDate:(NSDate *)date;

@end

Next, open the EventManager.m file and define it as follows:
-(NSString *)getStringFromDate:(NSDate *)date{
    NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
    dateFormatter.locale = [NSLocale currentLocale];
    [dateFormatter setDateFormat:@"d MMM yyyy, HH:mm"];
    NSString *stringFromDate = [dateFormatter stringFromDate:date];
    return stringFromDate;
}

The dateFormatter object is the one here that performs the actual job. Using it, we set the format of the string, and then we convert the given date using that format into a string, which is finally returned. Simple but efficient.
Back to the EditEventViewController.m file again, we want to let our users to be able to pick a start and end date for the event, so we must make the table view respond when tapping on any of the date rows. If you've taken a look in the interface of the app, then you saw that there's a view controller named DatePickerViewController with a date picker in it. I created for general use and just for picking a date, and in the Interface Builder the necessary connections have already been made. What we want to do now is to display that view controller, and to do so we need to add the next table view method:
-(void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath{
    if (indexPath.section == 0 && (indexPath.row == 1 || indexPath.row == 2)) {
        [self performSegueWithIdentifier:@"idSegueDatepicker" sender:self];
    }
}

The DatePickerViewController class has a delegate method, which is called every time a date is selected, and it is already defined in our file. In there, we must store the picked date to the appropriate date property. In order to find out what date property we should use for assigning the selected date to (eventStartDate or eventEndDate), we'll check which cell is currently selected. Then, we'll properly assign the date. Here it is:
-(void)dateWasSelected:(NSDate *)selectedDate{
    // Based on the selected cell, specify what the selected date is purposed for.
    NSIndexPath *indexPath = [self.tblEvent indexPathForSelectedRow];

    if (indexPath.section == 0) {
        // In this case, it's either the event start or end date.
        if (indexPath.row == 1) {
            // The event start date.
            self.eventStartDate = selectedDate;
        }
        else{
            // The event end date.
            self.eventEndDate = selectedDate;
        }
    }

    // Reload the table view.
    [self.tblEvent reloadData];
}

With the couple previous steps, we've managed to make our users able to select both the start and the end date of the event, and then display them to the table view. What we haven't still done is to store the typed title, so let's do it now in the textFieldShouldReturn: textfield delegate method:
-(BOOL)textFieldShouldReturn:(UITextField *)textField{
    self.eventTitle = textField.text;
    [textField resignFirstResponder];

    return YES;
}

At this point, our view controller can successfully display and accept new event data, so we have only left to create and save the new event. That task will take place in the saveEvent: IBAction method. Notice that before saving the event, it's necessary to check if all the required values have been given by the user. If the title or any of the dates is missing, then we just return from the method without saving at all.
Let's see the method:
- (IBAction)saveEvent:(id)sender {
    // Check if a title was typed in for the event.
    if (self.eventTitle.length == 0) {
        // In this case, just do nothing.
        return;
    }

    // Check if a start and an end date was selected for the event.
    if (self.eventStartDate == nil || self.eventEndDate == nil) {
        // In this case, do nothing too.
        return;
    }

    // Create a new event object.
    EKEvent *event = [EKEvent eventWithEventStore:self.appDelegate.eventManager.eventStore];

    // Set the event title.
    event.title = self.eventTitle;

    // Set its calendar.
    event.calendar = [self.appDelegate.eventManager.eventStore calendarWithIdentifier:self.appDelegate.eventManager.selectedCalendarIdentifier];

    // Set the start and end dates to the event.
    event.startDate = self.eventStartDate;
    event.endDate = self.eventEndDate;


    // Save and commit the event.
    NSError *error;
    if ([self.appDelegate.eventManager.eventStore saveEvent:event span:EKSpanFutureEvents commit:YES error:&error]) {
        // Call the delegate method to notify the caller class (the ViewController class) that the event was saved.
        [self.delegate eventWasSuccessfullySaved];

        // Pop the current view controller from the navigation stack.
        [self.navigationController popViewControllerAnimated:YES];
    }
    else{
        // An error occurred, so log the error description.
        NSLog(@"%@", [error localizedDescription]);
    }

}

In order to create a new event, we use the EKEvent class of the Event Kit framework. After we have provided it with the proper values, we save and commit it at the same time, using once again the event store object of the EventManager class. As you notice, if the saving is successful, we call the delegate method eventWasSuccessfullySaved to notify the caller class that our job here is ready. The caller in our case is the ViewController class, and we'll implement the delegate method there in a while. For now, we just call it in advance.
Test the app now if you want and try to create a new event. Even though nothing will appear after creating an event in our app yet, you can see if a new event has been actually created by opening the Calendar app of the device or the Simulator. If you find it there, then congratulations, you just managed to create your first event!

Displaying Events
The job we have to do here is quite simple and straightforward. In order to display the events for the selected calendar we must perform actually two tasks: To load and show them in the table view existing in the ViewController class. We're going to create a new method in the EventManager class to load them, but before we do so, let's make some initial steps in the ViewController.m file.
First of all, it's necessary to declare an array property. In this array we'll keep all the events after we have them loaded, and from this array the table view will retrieve its data. Furthermore, we'll create a simple private method, which will be used to load the events and to refresh the table view.
Let's get started by going to the private class section. In there, write the next couple of lines:
@interface ViewController ()

...

@property (nonatomic, strong) NSArray *arrEvents;

-(void)loadEvents;

@end

Now, let's go to the EventManager class, in order to create a new public method that we'll use to load the events for the selected calendar. Open the EventManager.h file, and declare the next method:
@interface EventManager : NSObject

...

-(NSArray *)getEventsOfSelectedCalendar;

@end

As you notice, we are going to return an array from the method, so we assign the results to the private array property we previously declared in the ViewController class.
Before we go into definition, let me mention something first. To retrieve the events for a calendar, it's required to use predicates (NSPredicate object). In the predicate we'll create, we must specify the time period we want to get events for. For demo reasons only, we'll specify a two-year time period, meaning a year before and a year after the current date. In your applications, apply your own logic depending on the requirements of your apps, and specify the proper predicates. Besides that, keep in mind that the returned events are not sorted in chronological order. Therefore, in the method we'll implement right next, you'll see that we apply some sorting so we get all events in order. As a last note, the Event Kit framework method we'll use to get the events for the specified time period also accepts an array of calendars. In our app, we work with just one calendar at the time, so we'll add only the currently selected calendar to that array. Let's see the method now:
-(NSArray *)getEventsOfSelectedCalendar{
    // Specify the calendar that will be used to get the events from.
    EKCalendar *calendar = nil;
    if (self.selectedCalendarIdentifier != nil && self.selectedCalendarIdentifier.length > 0) {
        calendar = [self.eventStore calendarWithIdentifier:self.selectedCalendarIdentifier];
    }

    // If no selected calendar identifier exists and the calendar variable has the nil value, then all calendars will be used for retrieving events.
    NSArray *calendarsArray = nil;
    if (calendar != nil) {
        calendarsArray = @[calendar];
    }


    // Create a predicate value with start date a year before and end date a year after the current date.
    int yearSeconds = 365 * (60 * 60 * 24);
    NSPredicate *predicate = [self.eventStore predicateForEventsWithStartDate:[NSDate dateWithTimeIntervalSinceNow:-yearSeconds] endDate:[NSDate dateWithTimeIntervalSinceNow:yearSeconds] calendars:calendarsArray];

    // Get an array with all events.
    NSArray *eventsArray = [self.eventStore eventsMatchingPredicate:predicate];

    // Sort the array based on the start date.
    eventsArray = [eventsArray sortedArrayUsingSelector:@selector(compareStartDateWithEvent:)];

    // Return that array.
    return eventsArray;
}

Let's head back to the ViewController.m file, and let's implement the loadEvents method:
-(void)loadEvents{
    if (self.appDelegate.eventManager.eventsAccessGranted) {
        self.arrEvents = [self.appDelegate.eventManager getEventsOfSelectedCalendar];

        [self.tblEvents reloadData];
    }
}

Note that we firstly check if the user has granted access to the events. The usage of the getEventsOfSelectedCalendar method is quite simple. At the end, we reload the table view data.
After we have this method defined, we must call it too. That should happen in two places: The first one is the viewDidLoad method, and the second one is the delegate method of the EditEventViewControllerDelegate protocol. Let's see that:
- (void)viewDidLoad
{
    ...

    // Load the events with a small delay, so the store event gets ready.
    [self performSelector:@selector(loadEvents) withObject:nil afterDelay:0.5];
}

Note that we don't call the loadEvents method at once, but after a half of a second. This is done on purpose, because if you remember the event store object requires some time in order to get initialized. Next, the call in the delegate method:
-(void)eventWasSuccessfullySaved{
    // Reload all events.
    [self loadEvents];
}

Up to here everything is fine, but don't forget that we must display the data of the loaded events as well. Let's begin by going to the tableView:numberOfRowsInSection table view method. In there, replace the return 0; command with the next one:
-(NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section{
    return self.arrEvents.count;
}

We need as many rows as the number of the events. Next, let's see the tableView:cellForRowAtIndexPath: table view method. What we'll do here is easy, so here it is:
-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath{
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"idCellEvent"];

    // Get each single event.
    EKEvent *event = [self.arrEvents objectAtIndex:indexPath.row];

    // Set its title to the cell's text label.
    cell.textLabel.text = event.title;

    // Get the event start date as a string value.
    NSString *startDateString = [self.appDelegate.eventManager getStringFromDate:event.startDate];

    // Get the event end date as a string value.
    NSString *endDateString = [self.appDelegate.eventManager getStringFromDate:event.endDate];

    // Add the start and end date strings to the detail text label.
    cell.detailTextLabel.text = [NSString stringWithFormat:@"%@ - %@", startDateString, endDateString];

    return cell;
}

You see that we assign each object of the arrEvents array to an EKEvent object, and then we access the values we want. The prototype cell of this table view contains both a main label and a subtitle label. In the first one, we set the title of the event. In the second, we assign the start and end dates of the event, after having them converted to string objects, and after having concatenated them into one string value.
Go and try the app once again. This time, all the events from any calendar you select are displayed, and even more, when creating a new event is shown to the list directly.

Editing Events
We'll make this tutorial even better if we manage to edit an event. What we'll really do is to delete and re-create a selected event, after having edited its details of course. The EditEventViewController class already contains the mechanism needed to modify and save an event, so we'll only perform some adjustments to make it fit to our demanding.
The key to the event editing idea is to store somewhere a unique identifier string that each event has (it's produced when an event is saved for first time), and using that identifier to load the event details in the EditEventViewController view controller. To store temporarily the identifier of the event that we're about to edit, we'll create a new public property to the EventManager class, so we can access it directly later on from the EditEventViewController class.
Open the EventManager.h file, and declare the next string property:
@interface EventManager : NSObject

...

@property (nonatomic, strong) NSString *selectedEventIdentifier;

@end

Then, go back to the ViewController.m file, and add the next table view delegate method:
-(void)tableView:(UITableView *)tableView accessoryButtonTappedForRowWithIndexPath:(NSIndexPath *)indexPath{
    // Keep the identifier of the event that's about to be edited.
    self.appDelegate.eventManager.selectedEventIdentifier = [[self.arrEvents objectAtIndex:indexPath.row] eventIdentifier];

    // Perform the segue.
    [self performSegueWithIdentifier:@"idSegueEvent" sender:self];
}

With that method, the identifier of the selected event will be stored to the property we just created, and the EditEventViewController view controller will appear every time that the respected accessory button gets tapped . Note that the idSegueEvent has already been set in the Interface Builder, so the above code will work at once.
Now, let's go to the EditEventViewController.m file. For starters, declare an EKEvent object that we'll use for loading the event with the specified identifier:
@property (nonatomic, strong) AppDelegate *appDelegate;

...

@property (nonatomic, strong) EKEvent *editedEvent;

@end

The next thing we have to do here, is to check in the viewDidLoad method whether the selectedEventIdentifier property contains a value. If yes, then the proper event should be loaded, and its details should be set to the subviews of the view controller. If that property doesn't contain a value (it's nil or it contains the empty string value), then it's not the case of an edited event. Let's see that in action. In the viewDidLoad method add the next code segment:
- (void)viewDidLoad
{
    [super viewDidLoad];
    ...    

    // Check the value of the selectedEventIdentifier property, of the eventManager object.
    // If its length is 0, then a new event is going to be added.
    // If its length is other than 0, then an existing event is going to be edited. In that case, load the event.
    if (self.appDelegate.eventManager.selectedEventIdentifier.length > 0) {
        self.editedEvent = [self.appDelegate.eventManager.eventStore eventWithIdentifier:self.appDelegate.eventManager.selectedEventIdentifier];

        self.eventTitle = self.editedEvent.title;
        self.eventStartDate = self.editedEvent.startDate;
        self.eventEndDate = self.editedEvent.endDate;
    }

}

That's it. In the tableView:cellForRowAtIndexPath: method no changes are required to be made, as we have already set the value of each property shown above to the proper subview. The next modification we should make though, is in the saveEvent: method. In this one, we must check if we are editing an existing event or not, and if so, to delete the existing event as we're going to save it again. Note that by deleting an event and by re-creating it, its identifier gets changed, but actually we don't care about that.
Go to the saveEvent: and navigate yourself right above the next line:
EKEvent *event = [EKEvent eventWithEventStore:self.appDelegate.eventManager.eventStore];

Then, add the next condition:
if (self.appDelegate.eventManager.selectedEventIdentifier.length > 0) {
        [self.appDelegate.eventManager deleteEventWithIdentifier:self.appDelegate.eventManager.selectedEventIdentifier];
        self.appDelegate.eventManager.selectedEventIdentifier = @"";
    }

As you correctly guess, the deleteEventWithIdentifier: is another public custom method of the EventManager class. Before we work with it, I should just say that these lines are enough for succeeding our goal. The existing event will be deleted, and the rest of the code in this method will create it again. Notice that we set the empty string value again to the selectedEventIdentifier property, so we won't have any problems if we try to add a new event later.
Now, open the EventManager.h file and declare the new method:
@interface EventManager : NSObject

...

-(void)deleteEventWithIdentifier:(NSString *)identifier;

@end

To delete the event, we'll make use of the event store object again. Here's the implementation, which is straightforward enough:
-(void)deleteEventWithIdentifier:(NSString *)identifier{
    // Get the event that's about to be deleted.
    EKEvent *event = [self.eventStore eventWithIdentifier:identifier];

    // Delete it.
    NSError *error;
    if (![self.eventStore removeEvent:event span:EKSpanFutureEvents error:&error]) {
        // Display the error description.
        NSLog(@"%@", [error localizedDescription]);
    }
}

We are ready. Test the app once again, and edit an existing event. You'll see that when you save it, your changes will be reflected in the ViewController view controller.
Deleting an Event
The way we structured the app so far, and the last custom method we created in the EventManager class, allow us to delete an event pretty easily. The only thing we should do, is to implement a new table view delegate method, and use in there the deleteEventWithIdentifier: method we previously defined. Let's see it:
-(void)tableView:(UITableView *)tableView commitEditingStyle:(UITableViewCellEditingStyle)editingStyle forRowAtIndexPath:(NSIndexPath *)indexPath{
    if (editingStyle == UITableViewCellEditingStyleDelete) {
        // Delete the selected event.
        [self.appDelegate.eventManager deleteEventWithIdentifier:[[self.arrEvents objectAtIndex:indexPath.row] eventIdentifier]];

        // Reload all events and the table view.
        [self loadEvents];
    }
}

With this one, every time you swipe your finger on a cell towards left the red Delete button will appear. When tapping it, the respective event will be deleted, and the remaining events will be loaded again so the table view contents remain up to date.
With that fast addition you can try the app out again, and delete existing events.

Setting Alarms
Setting alarms for one or more events is useful in cases you want the system to notify you about them before their start date. If you remember, when we implemented the logic of the EditEventViewController we said that the table view is going to have two sections. The first one is for the event details, while the second will be used for setting one or more alarms per event. Here, we're going to focus on that second section, and we'll perform all the necessary tasks required for using alarms. Keep in mind that when talking about alarms, we actually talk about the date that an alarm should occur. That date should be prior the start date of an event. Alarms act like local notifications, but it's not recommended to use them in place of such notifications for other general purposes.
For starters, open the EditEventViewController.m file, and in the private section of the class declare the following array:
@interface EditEventViewController ()

...

@property (nonatomic, strong) NSMutableArray *arrAlarms;

@end

In this one we'll store the alarms we'll create later. Actually, in this array we'll keep the date of each alarm (date objects). Now, in the viewDidLoad method initialize it:
- (void)viewDidLoad
{
    ...
    self.arrAlarms = [[NSMutableArray alloc] init];

}

Then, go to the tableView:numberOfRowsInSection: method and modify the body of the else case as shown below:
-(NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section{
    if (section == 0) {
        return 3;
    }
    else{
        return self.arrAlarms.count + 1;
    }
}

The first row of the second section in the table view will have a permanent cell displaying a prompting message for adding a new alarm. All the alarms created will be listed below that cell, starting from the index 1. That's also the reason we return the total number of alarms plus one in the above method. Further than that, when tapping on the first row to add a new alarm, the DatePickerViewController view controller will appear to pick a date for the alarm.
Having all that in mind, let's move to the tableView:cellForRowAtIndexPath: method, and let's add some code to the else case. As you'll see, we check what the current row is, and if it's the first one then we display the prompt message. Otherwise, we get the date matching to an alarm, we convert it to a string object, and we show it. Right next, it's given the whole method again, fully implemented this time:
-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath{
    UITableViewCell *cell = nil;

    if (indexPath.section == 0) {
        // If the cell is nil, then dequeue it. Make sure to dequeue the proper cell based on the row.
        if (cell == nil) {
            if (indexPath.row == 0) {
                cell = [tableView dequeueReusableCellWithIdentifier:@"idCellTitle"];
            }
            else{
                cell = [tableView dequeueReusableCellWithIdentifier:@"idCellGeneral"];
            }
        }

        switch (indexPath.row) {
            case 0:
                // The title of the event.
            {
                UITextField *titleTextfield = (UITextField *)[cell.contentView viewWithTag:10];
                titleTextfield.delegate = self;
                titleTextfield.text = self.eventTitle;
            }
                break;

            case 1:
                // The event start date.
                if (self.eventStartDate == nil) {
                    cell.textLabel.text = @"Select a start date...";
                }
                else{
                    cell.textLabel.text = [self.appDelegate.eventManager getStringFromDate:self.eventStartDate];
                }
                break;

            case 2:
                // The event end date.
                if (self.eventEndDate == nil) {
                    cell.textLabel.text = @"Select an end date...";
                }
                else{
                    cell.textLabel.text = [self.appDelegate.eventManager getStringFromDate:self.eventEndDate];
                }
                break;

            default:
                break;
        }
    }
    else{
        if (cell == nil) {
            cell = [tableView dequeueReusableCellWithIdentifier:@"idCellGeneral"];
        }

        if (indexPath.row == 0) {
            cell.textLabel.text = @"+ Add a new alarm...";
        }
        else{
            cell.textLabel.text = [self.appDelegate.eventManager getStringFromDate:[self.arrAlarms objectAtIndex:indexPath.row - 1]];

            // No selection for the alarm cells.
            cell.selectionStyle = UITableViewCellSelectionStyleNone;

            // No accessory style.
            cell.accessoryType = UITableViewCellAccessoryNone;
        }
    }

    return cell;
}

As I said earlier, we want to load and show the DatePickerViewController view controller when tapping on the first row, therefore we must modify the following method as shown:
-(void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath{
    if ((indexPath.section == 0 && (indexPath.row == 1 || indexPath.row == 2)) ||
        (indexPath.section == 1 && indexPath.row == 0)) {
        [self performSegueWithIdentifier:@"idSegueDatepicker" sender:self];
    }
}

By doing so, the date picker view controller will be presented in three cases: When tapping on the start and end dates of the event, and when adding a new alarm. However, that's not enough for picking a date for the alarm. It's necessary to modify the dateWasSelected: delegate method, so we add the selected date to the arrAlarms array. Right next, it's given the whole method again. The interesting part is the outer else case:
-(void)dateWasSelected:(NSDate *)selectedDate{
    // Based on the selected cell, specify what the selected date is purposed for.
    NSIndexPath *indexPath = [self.tblEvent indexPathForSelectedRow];

    if (indexPath.section == 0) {
        // In this case, it's either the event start or end date.
        if (indexPath.row == 1) {
            // The event start date.
            self.eventStartDate = selectedDate;
        }
        else{
            // The event end date.
            self.eventEndDate = selectedDate;
        }
    }
    else{
        // In this case, the selected date regards a new alarm.
        [self.arrAlarms addObject:selectedDate];
    }

    // Reload the table view.
    [self.tblEvent reloadData];
}

The next step is to edit the saveEvent: IBAction method, so any alarms set to be saved along with the event. Adding an alarm to an event is quite easy, as the EKEvent class provides a method named addAlarm: specifically for this reason. Because it's possible to set more than one alarms, we'll use a loop to go through all of the arrAlarms array's objects, we'll create an alarm object for each date (EKAlarm object) and finally we'll add it to the event.
In the saveEvent: method, go right above that point (right before we save the event):
NSError *error;
    if ([self.appDelegate.eventManager.eventStore saveEvent:event span:EKSpanThisEvent commit:YES error:&error])

There, add that snippet:
// Add any alarms the user has set.
    for (int i=0; i
With this small addition, our events can now have alarms. Before we finish our work here though, it would be nice if we could remove an already set alarm, wouldn't be? Actually, the easiest way would be to swipe towards left on an alarm cell and make the familiar red Delete button appear. Well, that's more than easy, as long as we implement the following method:
-(void)tableView:(UITableView *)tableView commitEditingStyle:(UITableViewCellEditingStyle)editingStyle forRowAtIndexPath:(NSIndexPath *)indexPath{
    if (indexPath.section == 1 && indexPath.row > 0) {
        if (editingStyle == UITableViewCellEditingStyleDelete) {
            // Remove the respective date from the arrAlarms array.
            [self.arrAlarms removeObjectAtIndex:indexPath.row - 1];

            // Reload the table view.
            [self.tblEvent reloadData];
        }
    }
}

There's one more detail that we shouldn't overlook here, and it regards the alarms of an event that is being edited. We must display the alarms for an edited event when it's loaded, but we haven't done something like that so far. What we should do, is to to get all alarms from the edited event in the viewDidLoad method, and add them to the arrAlarms array. Let's see that:
- (void)viewDidLoad
{
    ...

    // Check the value of the selectedEventIdentifier property, of the eventManager object.
    // If its length is 0, then a new event is going to be added.
    // If its length is other than 0, then an existing event is going to be edited. In that case, load the event.
    if (self.appDelegate.eventManager.selectedEventIdentifier.length > 0) {
        self.editedEvent = [self.appDelegate.eventManager.eventStore eventWithIdentifier:self.appDelegate.eventManager.selectedEventIdentifier];

        ...

        // If there are alarms, then keep the absolute date of each one.
        if (self.editedEvent.hasAlarms) {
            NSArray *alarms = self.editedEvent.alarms;
            for (int i=0; i
A great new feature was just added to our app, so feel free to give it one more try. If you think that's not working correctly on Simulator, then test it on a device. Set an alarm for an event a bit before its start date, and wait until iOS notifies you.

Repeating an Event
A repeating, or in other words, a recurring event, is an event that can be re-scheduled automatically with a predefined frequency. In order to make an event able to be repeated, we must create a recurrence rule, and we necessarily need to set two values: The recurrence frequency and the * recurrence interval*. The frequency can have any of the following values:

Daily
Weekly
Monthly
Yearly

The interval is an integer number, indicating how often an event will be repeated using the specified frequency. For example, if the recurrence frequency is weekly and the interval is 2, then the event will be repeated every two weeks. Besides these two values, the recurrence end can be also set. In this sample, we're going to use the event's end date as the recurrence end date too. After having specified the above two values to a recurrence rule, we set it to an event object.
Our goal in this part is to extend a bit more the EditEventViewController class and to make it capable of making an event recurring. In order to keep things simple, we'll use an array with some predefined recurring values, which will be displayed to the table view and they will be available for selecting any of them. For the sake of the demo app, we'll set these predefined values:

No repeat
Repeat every day
Repeat every 3 days
Repeat every week
Repeat every 2 weeks
Repeat every month
Repeat every 6 months
Repeat every year

Let's start working now to see everything in action. Make sure you've opened the EditEventViewController.m file, and then go to the private section of the class to declare the next two properties:
@interface EditEventViewController ()

...

@property (nonatomic, strong) NSArray *arrRepeatOptions;

@property (nonatomic) NSUInteger indexOfSelectedRepeatOption;


@end

The first one is the array that will contain the predefined repeat values. The second property will indicate the index of the selected repeat value in the table view and in the array.
Next, we must initialize the array with the above values, as well as the integer property. In the viewDidLoad method add the following:
- (void)viewDidLoad
{
    ...

    // Initialize the repeat options array.
    self.arrRepeatOptions = @[@"Never", @"Every day", @"Every 3 days", @"Every week", @"Every 2 weeks", @"Every month", @"Every six months", @"Every year"];

    self.indexOfSelectedRepeatOption = 0;
}

Now that we have the repeating options ready, it's necessary to modify the table view so we display them. Begin by setting the total number of sections:
-(NSInteger)numberOfSectionsInTableView:(UITableView *)tableView{
    return 3;
}

Then, return the proper number of rows for each section:
-(NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section{
    if (section == 0) {
        return 3;
    }
    else if (section == 1) {
        return self.arrAlarms.count + 1;
    }
    else{
        return self.arrRepeatOptions.count;
    }
}

As you see, a new case was added here. Next, let's set the section title:
-(NSString *)tableView:(UITableView *)tableView titleForHeaderInSection:(NSInteger)section{
    if (section == 0) {
        return @"General Settings";
    }
    else if (section == 1) {
        return @"Alarms";
    }
    else{
        return @"Repeat Frequency";
    }
}

The most important part now, is to display the repeat values. In the tableView:cellForRowAtIndexPath: table view method, we need to add one more case with the following body:
if (cell == nil) {
            cell = [tableView dequeueReusableCellWithIdentifier:@"idCellGeneral"];
        }

        // The section with the repeat options.
        cell.textLabel.text = [self.arrRepeatOptions objectAtIndex:indexPath.row];

        if (indexPath.row == self.indexOfSelectedRepeatOption) {
            cell.accessoryType = UITableViewCellAccessoryCheckmark;
        }
        else{
            cell.accessoryType = UITableViewCellAccessoryNone;
        }

Notice that we check whether the current row is the selected one. If that's the case, then we use the checkmark accessory type to indicate that. Here's the whole method implementation once again. Our addition is in the last case:
-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath{
    UITableViewCell *cell = nil;

    if (indexPath.section == 0) {
        // If the cell is nil, then dequeue it. Make sure to dequeue the proper cell based on the row.
        if (cell == nil) {
            if (indexPath.row == 0) {
                cell = [tableView dequeueReusableCellWithIdentifier:@"idCellTitle"];
            }
            else{
                cell = [tableView dequeueReusableCellWithIdentifier:@"idCellGeneral"];
            }
        }


        switch (indexPath.row) {
            case 0:
                // The title of the event.
            {
                UITextField *titleTextfield = (UITextField *)[cell.contentView viewWithTag:10];
                titleTextfield.delegate = self;
                titleTextfield.text = self.eventTitle;
            }
                break;

            case 1:
                // The event start date.
                if (self.eventStartDate == nil) {
                    cell.textLabel.text = @"Select a start date...";
                }
                else{
                    cell.textLabel.text = [self.appDelegate.eventManager getStringFromDate:self.eventStartDate];
                }
                break;

            case 2:
                // The event end date.
                if (self.eventEndDate == nil) {
                    cell.textLabel.text = @"Select an end date...";
                }
                else{
                    cell.textLabel.text = [self.appDelegate.eventManager getStringFromDate:self.eventEndDate];
                }
                break;

            default:
                break;
        }
    }
    else if (indexPath.section == 1){
        if (cell == nil) {
            cell = [tableView dequeueReusableCellWithIdentifier:@"idCellGeneral"];
        }

        if (indexPath.row == 0) {
            cell.textLabel.text = @"+ Add a new alarm...";
        }
        else{
            cell.textLabel.text = [self.appDelegate.eventManager getStringFromDate:[self.arrAlarms objectAtIndex:indexPath.row - 1]];

            // No selection for the alarm cells.
            cell.selectionStyle = UITableViewCellSelectionStyleNone;

            // No accessory style.
            cell.accessoryType = UITableViewCellAccessoryNone;
        }
    }
    else{
        if (cell == nil) {
            cell = [tableView dequeueReusableCellWithIdentifier:@"idCellGeneral"];
        }

        // The section with the repeat options.
        cell.textLabel.text = [self.arrRepeatOptions objectAtIndex:indexPath.row];

        if (indexPath.row == self.indexOfSelectedRepeatOption) {
            cell.accessoryType = UITableViewCellAccessoryCheckmark;
        }
        else{
            cell.accessoryType = UITableViewCellAccessoryNone;
        }
    }

    return cell;
}

If you run it, you'll see the repeat options listed successfully on the table view. However, nothing happens yet if you tap on any of them, and the first option always remains the selected one. Let's fix that in the tableView:didSelectRowAtIndexPath: table view method, where we'll just add a new if clause:
-(void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath{
    ...

    if (indexPath.section == 2) {
        self.indexOfSelectedRepeatOption = indexPath.row;

        [self.tblEvent reloadData];
    }
}

Now, every time you tap on a repeat option the selection will get changed too. Up to now, we've managed to set and show the predefined repeat options, and to properly select any of them. The most important thing however is to create a recurring rule based on the user selection, and then set it to the event upon saving. Before we create the rule though, we must specify the recurrence frequency and interval values. To do so, head to the saveEvent: IBAction method and and add the next code snippet right before the point where we save the event and after the alarms segment:
// Specify the recurrence frequency and interval values based on the respective selected option.
    EKRecurrenceFrequency frequency;
    NSInteger interval;
    switch (self.indexOfSelectedRepeatOption) {
        case 1:
            frequency = EKRecurrenceFrequencyDaily;
            interval = 1;
            break;
        case 2:
            frequency = EKRecurrenceFrequencyDaily;
            interval = 3;
        case 3:
            frequency = EKRecurrenceFrequencyWeekly;
            interval = 1;
        case 4:
            frequency = EKRecurrenceFrequencyWeekly;
            interval = 2;
        case 5:
            frequency = EKRecurrenceFrequencyMonthly;
            interval = 1;
        case 6:
            frequency = EKRecurrenceFrequencyMonthly;
            interval = 6;
        case 7:
            frequency = EKRecurrenceFrequencyYearly;
            interval = 1;

        default:
            interval = 0;
            frequency = EKRecurrenceFrequencyDaily;
            break;
    }

Having at our disposal the frequency and interval values, we're able to create a new recurrence rule:
// Create a rule and assign it to the reminder object if the interval is greater than 0.
    if (interval > 0) {
        EKRecurrenceEnd *recurrenceEnd = [EKRecurrenceEnd recurrenceEndWithEndDate:event.endDate];
        EKRecurrenceRule *rule = [[EKRecurrenceRule alloc] initRecurrenceWithFrequency:frequency interval:interval end:recurrenceEnd];
        event.recurrenceRules = @[rule];
    }
    else{
        event.recurrenceRules = nil;
    }

In the above two lines, not only we created the rule, but we added it to the event as well. Note that the event expects an array of rules, but in our case we have just one.
Now the app is capable of setting a recurring event. Before we test it, let's look at a last, but important detail: What will happen when we'll edit an existing event? What is going to be the selected repeat option index? By default, the preselected repeat option is the first one, but that would be wrong in cases that another repeat option had been selected. So, we need to fix that now, and to do so we'll implement a private method. At first declare it:
@interface EditEventViewController ()

...

-(void)determineIndexOfRepeatOption;

@end

In its implementation, we'll retrieve the recurrence rule from the edited event, and based on the frequency and interval values we'll specify the index of the selected option. Let's see it:
-(void)determineIndexOfRepeatOption{
    if (self.editedEvent.recurrenceRules != nil && self.editedEvent.recurrenceRules.count > 0) {
        // Get the frequency and interval values from the recurrence rule of the edited event.
        EKRecurrenceRule *rule = [self.editedEvent.recurrenceRules objectAtIndex:0];

        EKRecurrenceFrequency frequency = rule.frequency;
        NSInteger interval = rule.interval;

        if (interval == 1){
            if (frequency == EKRecurrenceFrequencyDaily) {
                self.indexOfSelectedRepeatOption = 1;
            }
            else if (frequency == EKRecurrenceFrequencyWeekly){
                self.indexOfSelectedRepeatOption = 3;
            }
            else if (frequency == EKRecurrenceFrequencyMonthly){
                self.indexOfSelectedRepeatOption = 5;
            }
            else{
                self.indexOfSelectedRepeatOption = 7;
            }
        }
        else{
            if (frequency == EKRecurrenceFrequencyDaily) {
                self.indexOfSelectedRepeatOption = 2;
            }
            else if (frequency == EKRecurrenceFrequencyWeekly){
                self.indexOfSelectedRepeatOption = 4;
            }
            else{
                self.indexOfSelectedRepeatOption = 6;
            }
        }
    }
}

Lastly, we just have to call it. This should happen in the viewDidLoad method, inside the if condition where we check if the event is edited:
- (void)viewDidLoad
{
    ...

    // Check the value of the selectedEventIdentifier property, of the eventManager object.
    // If its length is 0, then a new event is going to be added.
    // If its length is other than 0, then an existing event is going to be edited. In that case, load the event.
    if (self.appDelegate.eventManager.selectedEventIdentifier.length > 0) {
        self.editedEvent = [self.appDelegate.eventManager.eventStore eventWithIdentifier:self.appDelegate.eventManager.selectedEventIdentifier];

        ...

        // Determine the index of the repeat option based on the recurrence rule of the edited event.
        [self determineIndexOfRepeatOption];

        ...
    }

}

That's it. Our app can now set recurring events, so go and give it a try. Create a new event, set its details and finally pick a repeating option. Tap on Save and return to the ViewController view controller to see that... we have a problem! The table view displays multiple occurrences of the new event instead of just once, as follows:

Well, that would definitely should not happen, but on the other hand it's quite reasonable, because if you remember we use predicates with specific time frame to retrieve the events. The framework returns all the events for the period we specified, regardless if it's the same, recurring event. To fix this, we have to pay a visit to the getEventsOfSelectedCalendar custom method of the EventManager class, and add a small code segment, where we'll copy all the retrieved events to another array before we return them. This time, we'll keep just one occurrence of each event, and we'll have no problem. Here's the method fixed (the modifications start after we have retrieved the events):
-(NSArray *)getEventsOfSelectedCalendar{
    // Specify the calendar that will be used to get the events from.
    EKCalendar *calendar = nil;
    if (self.selectedCalendarIdentifier != nil && self.selectedCalendarIdentifier.length > 0) {
        calendar = [self.eventStore calendarWithIdentifier:self.selectedCalendarIdentifier];
    }

    // If no selected calendar identifier exists and the calendar variable has the nil value, then all calendars will be used for retrieving events.
    NSArray *calendarsArray = nil;
    if (calendar != nil) {
        calendarsArray = @[calendar];
    }

    // Create a predicate value with start date a year before and end date a year after the current date.
    int yearSeconds = 365 * (60 * 60 * 24);
    NSPredicate *predicate = [self.eventStore predicateForEventsWithStartDate:[NSDate dateWithTimeIntervalSinceNow:-yearSeconds] endDate:[NSDate dateWithTimeIntervalSinceNow:yearSeconds] calendars:calendarsArray];

    // Get an array with all events.
    NSArray *eventsArray = [self.eventStore eventsMatchingPredicate:predicate];

    // Copy all objects one by one to a new mutable array, and make sure that the same event is not added twice.
    NSMutableArray *uniqueEventsArray = [[NSMutableArray alloc] init];
    for (int i=0; i 0) {
            for (int j=0; j
If you run the app again, you'll see that the same event doesn't appear more than once now.

Summary
This tutorial was an effort to help you meet the world of calendars and events. As you may conclude, working with Event Kit is a quite straightforward process, as nothing especially difficult is required to be done. Working with all the stuff we met here is something that maybe will be needed sooner or later in your programming life, and knowing how to deal with it will surely save you a significant amount of time. Besides that, the class we created and used for managing the framework can be extended and evolved, and ultimately become a useful tool that you can add in your programming toolbox. Closing, I'd like to believe that this tutorial will become handy to all of you, and as always, let me know your thoughts.
For your reference, you can download the complete Xcode project from here.

Among the numerous applications existing on the App Store today, it would be hard for someone to find more than a few of them that do not deal with data. Most of the apps handle some sort of data, no matter in what format they are, and always perform some actions upon it. There are various solutions offered to developers for storing and managing data, and usually each one of them is suitable for different kind of applications. However, when working with large amount of data, the preferred method it seems like a one-way path: That is the use of a database.

Indeed, making use of a database can solve various kind of problems that should be solved programmatically in other cases. For programmers who love working with databases and SQL, this is the favorite data-managing method at 90% of the cases, and the first think that crosses their minds when talking about data. Also, if you were used to working with other databases or database management systems (DBMSs), then you’ll really appreciate the fact that you can keep applying your SQL knowledge in the iOS platform as well.

The database that can be used by apps in iOS (and also used by iOS) is called SQLite, and it’s a relational database. It is contained in a C-library that is embedded to the app that is about to use it. Note that it does not consist of a separate service or daemon running on the background and attached to the app. On the contrary, the app runs it as an integral part of it. Nowadays, SQLite lives its third version, so it’s also commonly referred as SQLite 3.

SQLite is not as powerful as other DMBSs, such as MySQL or SQL Server, as it does not include all of their features. However, its greatness lies mostly to these factors:

• It’s lightweight.
• It contains an embedded SQL engine, so almost all of your SQL knowledge can be applied.
• It works as part of the app itself, and it doesn’t require extra active services.
• It’s very reliable.
• It’s fast.
• It’s fully supported by Apple, as it’s used in both iOS and Mac OS.
• It has continuous support by developers in the whole world and new features are always added to it.

Focusing now on our tutorial, let me start by stating that my goal is not to show you how to become a SQLite expert. Instead, my plan is to implement a database class step by step, which will utilize the most important features of the SQLite library, but it will also become a reusable tool for your own applications. Unfortunately, even though SQLite is supported by Apple, a mechanism or a pre-made database management library does not exist. Going into more details, the database class that we will implement will be capable of executing all the standard SQL queries (select, insert, update, delete). The most important is that we’ll create it in such way, so it accepts clear SQL statements, and if you had worked with SQL in the past, you’ll definitely know what to do here too.

Besides the database class that we’ll develop, we’ll also create a sample application to test it and to see it in action. More details about that you’ll find in the next section though. Note that the queries we’ll write in the demo app will be simple enough for the sake of the tutorial, however be sure that more complex queries can be executed as well.

As a final word before we proceed, I would recommend to make a web search and read some more stuff about the SQLite itself. Of course, the first one should be the the official website.

App Overview

One could say that this tutorial is composed by three parts. In the first and most important one, we are going to create a new class and in there we’ll implement all the database handling. As I have already said in the introduction, after we have it finished, you can take it and use it as a reusable component to your own apps. In the second part we are going to leave Xcode for a while, as it’s necessary to work in the Terminal and in the SQLite command line environment. There, we will create a simple database, which we will add to the project and use it. Finally, in the third part, we are going to implement a sample application where we will make use of both the database class and the database file. More specifically about the third part, we will make the necessary configuration in the Interface Builder, and then we’ll write the required code so we’ll have a fully functional app in which the database class will have the most significant role.

Regarding the database class that we will create in a while, I would say that it can be used as-is in the most cases of applications. To tell the truth, I rarely needed to do any updates or modifications to the class’s code after its initial implementation, as it has been suitable for every app I developed or have been developing. Nevertheless, keep in mind that even though we will build a reusable tool, you should feel free to change it, evolve it and add any extra features you might think that would be useful for your own needs. Nothing is set of stone.

In the sample database that we will create to test the class, we are going to add just one table. We’ll name that table peopleInfo, and it will contain some basic people’s data. These will be the first name, the last name and the age. The datatype of the first two fields will be set to text, while the age will be an integer value. For the primary key of the table, we will set an auto-increment integer value. Generally, using such a key is recommended in most of cases, unless special requirements of your app define otherwise. The sample database will be created in Terminal, and then it will be added to the project. Maybe you are wondering if there are any Mac applications that could be used for that purpose, and the answer is that there are. To be honest though, I prefer and like a lot more to use the command line environment, as I think that it consists of the fastest and most efficient way to work with a database.

Finally, focusing a bit more on the sample app, it’s necessary to say that it’s going to be a navigation based app. However, initially we will create a simple, view-based app, and later through the Interface Builder we will convert it to navigation-based. Furthermore, the app will be parted by two view controllers. In the first view controller, we will display all the records fetched from the database in a table view. Besides than simply listing them, we’ll also make our app capable of editing and deleting records. The second view controller will be used to add a new record, or edit an existing one. Upon finishing, our app will be able to perform all the basic kind of queries: select for loading the data, insert for adding new records, update for editing existing records and delete to completely delete a record.

In the animated graphic below you can see the final outcome of our effort in this tutorial:

Having said all the above, I think is time to get started. We have a long journey ahead of us, so let’s don’t waste any more time.

Creating the Project

Unless we have a very special topic to discuss, the first step will always be the creation of our project. So, let me guide you through the necessary steps and make sure that we get along in all that.

Initially, launch Xcode and wait for the Welcome screen to appear. There, select to create a new project, as shown in the next figure:

Next, in the first step of the guide that is appeared, select the Single View Application template, in the Application category, under the iOS section.

Click on the Next button to proceed. In the second step, in the Product Name field set the SQLite3DBSample as the project’s name, and also make sure that the iPhone is the selected value in the Device drop down control.

Click on the Next button once again, and in the last step of the guide select a directory in your computer to save the project. Click on the Create button and wait until Xcode prepares the project.

The SQLite 3 Library

Before we begin implementing, it’s necessary to perform a small prerequisite step. That is to add the appropriate SQLite 3 library to the project, so we can import it later on to our class.

In the Project Navigator on Xcode click on the project name. Next, make sure that the General tab is on, and then go to the bottom of the page, in the Linked Frameworks and Libraries section. Click on the small plus icon as shown in the next image:

In the modal window that appears, type the term sqlite, and from the suggested options select the one with the libsqlite3.dylib title.

Finally, click on the Add button and this step is over.

Creating and Initializing the Database Class

So, now that the SQLite 3 library has been added to the project, the first thing we are going to do is to create a new class to manage all the database functionality. In this class, we will write all the code needed to execute queries and to load data from the database.

Let’s get started by adding a new class file to the project. Go to the File > New > File… menu of the Xcode, or just hit the Command-N key combination on your keyboard. The familiar Xcode guide will appear. In the first step, select the Objective-C class option in the Cocoa Touch category, under the iOS section.

Click on the Next button, and in the next step perform two tasks: First, make sure that the Subclass of field contains the NSObject value. If not, then type it. Next, in the Class field type the name of our class, which is DBManager.

After having done the above, click once again on the Next button, and in the third and last step make sure that the SQLite3DBSample target is selected. If not do it now, and click on the Create button. The guide will close and the new class will be ready.

Now we have an empty class in our hands, and we just have to write code in it. We’ll begin by creating a custom init method, as upon initialization we want to specify the database file name. Click on the DBManager.h file on the Project Navigator to open it. In there, add the following declaration:

@interface DBManager : NSObject

-(instancetype)initWithDatabaseFilename:(NSString *)dbFilename;

@end

Now, go to the DBManager.m file, and write the standard definition of all the init methods:

-(instancetype)initWithDatabaseFilename:(NSString *)dbFilename{
    self = [super init];
    if (self) {

    }
    return self;
}

As I have already said, the original database file will reside in the application’s bundle (in other words, the app package). Our mission is to make a copy of that file to the application’s documents directory, and work with that copy later on. Note that you should never work directly with a file existing in the app bundle, especially if your app is going to modify it. Always make a copy of it to the documents directory.

Focusing on the init method again, we’re going:

1. To specify the path to the documents directory of the app and store it to a property .
2. To store the database filename that is provided as an argument in the above init method to another property.
3. To copy the database file from the app bundle into the documents directory if that’s necessary.

We’ll use properties to store the documents directory and the database filename values, as we’ll need them later as well.

Having said all the above, go at the top of the file and create the private class section, by declaring at the same time the two properties as described.

@interface DBManager()

@property (nonatomic, strong) NSString *documentsDirectory;
@property (nonatomic, strong) NSString *databaseFilename;

@end

Now, once being at the top of the file, make the next import:

#import 

So far, so good. Back to the init method, let’s do some initialization. Right next you are given the method again, containing this time all the proper code:

-(instancetype)initWithDatabaseFilename:(NSString *)dbFilename{
    self = [super init];
    if (self) {
        // Set the documents directory path to the documentsDirectory property.
        NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
        self.documentsDirectory = [paths objectAtIndex:0];

        // Keep the database filename.
        self.databaseFilename = dbFilename;

        // Copy the database file into the documents directory if necessary.
        [self copyDatabaseIntoDocumentsDirectory];
    }
    return self;
}

At first, we specify the path to the documents directory and we store it to the documentsDirectory property. Next, we assign the database filename to the databaseFilename property, and finally we copy the database file from the app bundle to the documents directory.

As you correctly assume, the copyDatabaseIntoDocumentsDirectory is a custom, private method that we must implement, and in here we’ll do the file copying, if needed of course. Surely Xcode have issued an error by now, so let’s work against it.

Go back to the private class section, and declare the method as shown below:

@interface DBManager()

@property (nonatomic, strong) NSString *documentsDirectory;
@property (nonatomic, strong) NSString *databaseFilename;

-(void)copyDatabaseIntoDocumentsDirectory;

@end

Let’s go to the definition right away. What we’ll do here is fairly simple: We’ll check if the database file exists or not in the documents directory, and if it’s not there we’ll copy it. Here’s the implementation:

-(void)copyDatabaseIntoDocumentsDirectory{
    // Check if the database file exists in the documents directory.
    NSString *destinationPath = [self.documentsDirectory stringByAppendingPathComponent:self.databaseFilename];
    if (![[NSFileManager defaultManager] fileExistsAtPath:destinationPath]) {
        // The database file does not exist in the documents directory, so copy it from the main bundle now.
        NSString *sourcePath = [[[NSBundle mainBundle] resourcePath] stringByAppendingPathComponent:self.databaseFilename];
        NSError *error;
        [[NSFileManager defaultManager] copyItemAtPath:sourcePath toPath:destinationPath error:&error];

        // Check if any error occurred during copying and display it.
        if (error != nil) {
            NSLog(@"%@", [error localizedDescription]);
        }
    }
}

There’s nothing especially difficult in the above method. We are based on the NSFileManager class to check for the file existence and to copy it if needed. It’s also quite interesting the way we access the original file in the app bundle: [[[NSBundle mainBundle] resourcePath] stringByAppendingPathComponent:self.databaseFilename].

The above method will be called every time that an object of the DBManager class is initialized. If the database file won’t be found in the documents directory, then the code in the condition block will be executed, otherwise it will be skipped. Normally, that code should be executed just once per app install, as the database file should always remain in the documents directory after having been copied in there.

So, quickly summarizing, we’ve managed to perform two important tasks here: To create the DBManager class files, and to create a custom init method, which makes sure that the database file will exist to the documents directory of the app. Now, we are ready to go deeper in the details of the SQLite 3 database.

SQLite 3 Functions Preview

Our next step is to implement the heart of our class, the method that will take care of all the work with the database. However, I believe it would be much better to take a quick look at the SQLite 3 functions that we are going to need first, and then proceed to implementation. There’s a great number of functions supported and provided, but we’ll need just some of them. Let’s see them one by one:

• sqlite3_open: This function is used to create and open a database file. It accepts two parameters, where the first one is the database file name, and the second a handler to the database. If the file does not exist, then it creates it first and then it opens it, otherwise it just opens it.
• sqlite3_prepare_v2: The purpose of this function is to get a SQL statement (a query) in string format, and convert it to an executable format recognizable by SQLite 3.
• sqlite3_step: This function actually executes a SQL statement (query) prepared with the previous function. It can be called just once for executable queries (insert, update, delete), or multiple times when retrieving data. It’s important to have in mind that it can’t be called prior to the sqlite3_preprare_v2 function.
• sqlite3_column_count: This method’s name it makes it easy to understand what is about. It returns the total number of columns (fields) a contained in a table.
• sqlite3_column_text: This method returns the contents of a column in text format, actually a C string (char *) value. It accepts two parameters: The first one is the query converted (compiled) to a SQLite statement, and the second one is the index of the column.
• sqlite3_column_name: It returns the name of a column, and its parameters are the same to the previous function’s.
• sqlite3_changes: It actually returns the number of the affected rows, after the execution of a query.
• sqlite3_last_insert_rowid: It returns the last inserted row’s ID.
• sqlite3_errmsg: It returns the description of a SQLite error.
• sqlite3_finalize: It deletes a prepared statement from memory.
• sqlite3_close: It closes an open database connection. It should be called after having finished any data exchange with the database, as it releases any reserved system resources.

Core Functionality Implementation

Now that you’ve been provided with a short description of every SQLite function we’ll meet next, let’s go to the implementation of the core method of our class. In this one, we are going to run both executable and non-executable queries. Based on that, we will make sure to implement it that way so it accepts two parameters: The query itself, and a boolean value indicating whether the query is executable or not. The logic applied in the method is quite simple, but let’s give it a look:

• Initially, we’ll perform some necessary initializations, regarding mostly the structures that will store our data (NSMutableArray objects).
• Then, we’ll open the database and if that’s successful, we’ll compile the query to a SQLite 3 statement (prepared statement).
• If the query is not executable, meaning that is a select statement, we’ll fetch the desired data row by row. For each one, we’ll get each single column’s contents as a text value, and we’ll add it to a temporary mutable array. When all the columns of a data row have been read, we’ll add the temporary array to the final results array. At the same time, we’ll use another array to save the column names, as it’s quite possible to become handy when the database class will be used.
• If the query is executable, meaning that is an insert, update, or delete statement, things will be much simpler. We’ll just execute the query and if the result is successful, then we’ll store to properties the affected rows and the last inserted ID values.
• In case of any error, we’ll just output its description.
• Finally, we’ll make sure to free up all used resources.

Let me now denote a couple of things. First of all, and according to what I said in the above description, we’ll get each column’s contents as a text value. This is a generic approach and you may think that it doesn’t suit to all kind of data existing to a database table. However, don’t forget that we want to implement a class that will work for all applications (or the most of them), so our solution shouldn’t be oriented to specific data. Moreover, the text (string) results can be converted to other data types and be handled in any desired way by an app.
At second, the fetched results will be stored to a two-dimensional array. Into each index of the results array, there will be another array containing the data of a single row. Personally, I consider this to be the best option for having the result set from the database file to memory. If you wish so, you could try to modify the implementation and use NSDictionary objects instead.

Let’s get started with the implementation now. We’ll do one step at the time, so we discuss each action we take. Besides that, there are plenty of comments in the code that will help you understand it much better.

First off, go to the private class section, and declare a mutable array property for storing our results, and of course, the private method itself:

@interface DBManager()

...
...
@property (nonatomic, strong) NSMutableArray *arrResults;


-(void)runQuery:(const char *)query isQueryExecutable:(BOOL)queryExecutable;

@end

If you wonder why this method is private, while it should be public, then the answer is simple: After having finished with it, we’ll create two small public methods, where we’ll use the first one just to load data from the database, and the second one to run executable queries. Both of those methods will call this, providing each one the proper arguments. Besides that, notice that the query parameter is a const char (a C string) and not a NSString* object. That’s because the SQLite functions don’t know anything about NSStrings, they just know how to handle C strings.

Next, go to the DBManager.h file, and in the public class section declare the next three properties:

@interface DBManager : NSObject

...
...

@property (nonatomic, strong) NSMutableArray *arrColumnNames;

@property (nonatomic) int affectedRows;

@property (nonatomic) long long lastInsertedRowID;

@end

I think there’s no need to explain what these properties are for.

Back to the DBManager.m file to get started with the implementation. As you’ll see right next, initially we perform four specific tasks: We declare a local SQLite 3 object to handle the database, we set the path to the database file, and we initialize the two array properties (the arrResults and the arrColumnNames arrays).

-(void)runQuery:(const char *)query isQueryExecutable:(BOOL)queryExecutable{
    // Create a sqlite object.
    sqlite3 *sqlite3Database;

    // Set the database file path.
    NSString *databasePath = [self.documentsDirectory stringByAppendingPathComponent:self.databaseFilename];

    // Initialize the results array.
    if (self.arrResults != nil) {
        [self.arrResults removeAllObjects];
        self.arrResults = nil;
    }
    self.arrResults = [[NSMutableArray alloc] init];

    // Initialize the column names array.
    if (self.arrColumnNames != nil) {
        [self.arrColumnNames removeAllObjects];
        self.arrColumnNames = nil;
    }
    self.arrColumnNames = [[NSMutableArray alloc] init];
}

Note that if any previous data exist in any of the arrays, we get rid of them before we initialize the arrays again to make sure that nothing remains on memory.

Next, we must open the database, and if no error occurs we will use the sqlite3_prepare_v2 function to convert the query into a executable SQLite part:

    // Open the database.
    BOOL openDatabaseResult = sqlite3_open([databasePath UTF8String], &sqlite3Database);
    if(openDatabaseResult == SQLITE_OK)
        // Declare a sqlite3_stmt object in which will be stored the query after having been compiled into a SQLite statement.
        sqlite3_stmt *compiledStatement;

    // Load all data from database to memory.
    BOOL prepareStatementResult = sqlite3_prepare_v2(sqlite3Database, query, -1, &compiledStatement, NULL);
    if(prepareStatementResult == SQLITE_OK) {
        ...
    }
    ...
}

As you see, we check if the database was opened successfully comparing with the SQLITE_OK value. Then, we declare the compiledStatement variable, which is a sqlite3_stmt type, for storing the compiled statement. Finally, we make use of the sqlite3_prepare_v2 function, in which we pass the database handler, the query and the compiled statement variable as parameters.

Inside the inner if clause above, we’ll check if the query is executable or not. In case it’s a select query, we’ll load all data specified by the query. Here we go:

// Check if the query is non-executable.
    if (!queryExecutable){
        // In this case data must be loaded from the database.

        // Declare an array to keep the data for each fetched row.
        NSMutableArray *arrDataRow;

        // Loop through the results and add them to the results array row by row.
        while(sqlite3_step(compiledStatement) == SQLITE_ROW) {
            // Initialize the mutable array that will contain the data of a fetched row.
            arrDataRow = [[NSMutableArray alloc] init];

            // Get the total number of columns.
            int totalColumns = sqlite3_column_count(compiledStatement);

            // Go through all columns and fetch each column data.
            for (int i=0; i 0) {
                [self.arrResults addObject:arrDataRow];
            }
        }
    }

We wrote some code here, so let’s discuss it. At first we declare a local array, named arrDataRow. In this one, we’ll store each data row fetched from the dataset existing in memory. Then, using the sqlite3_step function, we go through all the results row by row. Inside the while loop, we initialize the arrDataRow array and we get the total number of columns existing in the result set. Then, inside a new for loop, we get each column’s contents and we assign them to a char variable. If that value is not null, we add it to the temp arrDataRow array converted to a NSString* object. Next, if we haven’t done so already, we store each column name to the arrColumnNames array. Finally, when the for loop is over, we add the fetched data row to the arrResults array.

Let’s proceed to the case of an executable query:

    else {
        // This is the case of an executable query (insert, update, ...).

        // Execute the query.
        BOOL executeQueryResults = sqlite3_step(compiledStatement);
        if (executeQueryResults == SQLITE_DONE) {
            // Keep the affected rows.
            self.affectedRows = sqlite3_changes(sqlite3Database);

            // Keep the last inserted row ID.
            self.lastInsertedRowID = sqlite3_last_insert_rowid(sqlite3Database);
        }
        else {
            // If could not execute the query show the error message on the debugger.
            NSLog(@"DB Error: %s", sqlite3_errmsg(sqlite3Database));
        }
    }
}
else {
    // In the database cannot be opened then show the error message on the debugger.
    NSLog(@"%s", sqlite3_errmsg(sqlite3Database));
}

Things are much simple here. We run the query, and if it’s all okay, we store the affected rows and the last inserted row ID to the respective properties. In the else cases you see that we show on the debugger the error description, when the query cannot be executed and when the database can’t be opened.

Finally, we need to free up the memory by releasing all used resources, and by closing the connection to database:

// Release the compiled statement from memory.
        sqlite3_finalize(compiledStatement);

    }

    // Close the database.
    sqlite3_close(sqlite3Database);

That was the last step needed to be performed in the method. Right below it’s given in one piece, as all the if-else cases and the curly brackets become confusing enough:

-(void)runQuery:(const char *)query isQueryExecutable:(BOOL)queryExecutable{
    // Create a sqlite object.
    sqlite3 *sqlite3Database;

    // Set the database file path.
    NSString *databasePath = [self.documentsDirectory stringByAppendingPathComponent:self.databaseFilename];

    // Initialize the results array.
    if (self.arrResults != nil) {
        [self.arrResults removeAllObjects];
        self.arrResults = nil;
    }
    self.arrResults = [[NSMutableArray alloc] init];

    // Initialize the column names array.
    if (self.arrColumnNames != nil) {
        [self.arrColumnNames removeAllObjects];
        self.arrColumnNames = nil;
    }
    self.arrColumnNames = [[NSMutableArray alloc] init];


    // Open the database.
    BOOL openDatabaseResult = sqlite3_open([databasePath UTF8String], &sqlite3Database);
    if(openDatabaseResult == SQLITE_OK) {
        // Declare a sqlite3_stmt object in which will be stored the query after having been compiled into a SQLite statement.
        sqlite3_stmt *compiledStatement;

        // Load all data from database to memory.
        BOOL prepareStatementResult = sqlite3_prepare_v2(sqlite3Database, query, -1, &compiledStatement, NULL);
        if(prepareStatementResult == SQLITE_OK) {
            // Check if the query is non-executable.
            if (!queryExecutable){
                // In this case data must be loaded from the database.

                // Declare an array to keep the data for each fetched row.
                NSMutableArray *arrDataRow;

                // Loop through the results and add them to the results array row by row.
                while(sqlite3_step(compiledStatement) == SQLITE_ROW) {
                    // Initialize the mutable array that will contain the data of a fetched row.
                    arrDataRow = [[NSMutableArray alloc] init];

                    // Get the total number of columns.
                    int totalColumns = sqlite3_column_count(compiledStatement);

                    // Go through all columns and fetch each column data.
                    for (int i=0; i 0) {
                        [self.arrResults addObject:arrDataRow];
                    }
                }
            }
            else {
                // This is the case of an executable query (insert, update, ...).

                // Execute the query.
                BOOL executeQueryResults = sqlite3_step(compiledStatement);
                if (executeQueryResults == SQLITE_DONE) {
                    // Keep the affected rows.
                    self.affectedRows = sqlite3_changes(sqlite3Database);

                    // Keep the last inserted row ID.
                    self.lastInsertedRowID = sqlite3_last_insert_rowid(sqlite3Database);
                }
                else {
                    // If could not execute the query show the error message on the debugger.
                    NSLog(@"DB Error: %s", sqlite3_errmsg(sqlite3Database));
                }
            }
        }
        else {
            // In the database cannot be opened then show the error message on the debugger.
            NSLog(@"%s", sqlite3_errmsg(sqlite3Database));
        }

        // Release the compiled statement from memory.
        sqlite3_finalize(compiledStatement);

    }

    // Close the database.
    sqlite3_close(sqlite3Database);
}

Loading Data and Executing Queries

Now that the core method of our class has been implemented, we have only left to make use of it. That’s simple, as we just have to implement two new small, public methods: One for running select queries and loading data, and one for executing insert, update and delete queries.

Let’s begin by declaring both of them. Open the DBManager.h file, and add the next two lines:

@interface DBManager : NSObject

...

-(NSArray *)loadDataFromDB:(NSString *)query;

-(void)executeQuery:(NSString *)query;

@end

Let’s focus on the first method, named loadDataFromDB:. This method accepts as a parameter value the query we want to be executed as a NSString object. For example, such a valid string would be this: “select * from people where age > 18”. The fetched result set is returned as an array, and according to what I said in the previous section, this is going to be a two-dimensional array. The first array represents the rows, while each sub-array represents the columns of each row. Having said all that, let’s go back to the DBManager.m file, and let’s implement it:

-(NSArray *)loadDataFromDB:(NSString *)query{    
    // Run the query and indicate that is not executable.
    // The query string is converted to a char* object.
    [self runQuery:[query UTF8String] isQueryExecutable:NO];

    // Returned the loaded results.
    return (NSArray *)self.arrResults;
}

As you see, it’s just a matter of two lines. In the first line, we call the runQuery:isQueryExecutable: method and we convert the query to a C string object. At the same time, we specify that the query is not executable.

In the second line we return the arrResults array that contains the query results, casting it first to a NSArray object. It would be a bad idea to make the arrResults array public and allow apps to have direct access to it, as then the returned data could be potentially altered before it used.

Going to the executeQuery: method now, here’s it its definition:

-(void)executeQuery:(NSString *)query{
    // Run the query and indicate that is executable.
    [self runQuery:[query UTF8String] isQueryExecutable:YES];
}

In this one, there is not a return value. However, the affectedRows property can be used to verify whether there were any changes or not after having executed a query.

A Sample Database

The database class is ready to be used, but how can we do that without having an actual database to test it? So, in this part I’m going to show you how to create a new database on Terminal, how to create a new table and finally how to embed the database file to the Xcode project. If you’re not used to work in a command line environment don’t worry; you’ll find out that doing so it’s interesting, different, even amusing.

For the purpose of this example we won’t create a complex database. On the contrary, we will create just one table, named peopleInfo, with the following fields:

• peopleInfoID: An integer value, the primary key of the table.
• firstname: A text value.
• lastname: A text value.
• age: An integer value.

Such a table is just fine to try out all the functionalities we want. Let’s see everything in action now. Click on the Spotlight icon, and type the Terminal word in the textfield:

Once it gets spotted, hit the Return key on the keyboard, or click on its name with your mouse and the terminal window will appear. We are going to create a new database file named sampledb.sql. For the record, let me say that you can use any extension you would like for the file, or no extension at all. The most common extensions are:

• .sql
• .sqlite
• .db

Personally, I like to give the .sql extension to my database files, but feel free to use anything that better suits to your preferences.

To create the above database, simply write the following in the terminal:

sqlite3 sampledb.sql

The database file will be created at once, and you’ll enter into the SQLite command line environment. The command needed to create a new table is quite similar to other SQL databases or DBMSs, with some slight differences though. Here it is:

CREATE TABLE peopleInfo(peopleInfoID integer primary key, firstname text, lastname text, age integer);

Even though this tutorial has nothing to do with offering instructions on how to use the SQLite command line environment, I believe that it would be useful to mention just a couple of commands. These are the .tables and the .schema TABLE_NAME. The first one displays a listing with all the tables you’ve created in a database. The second one displays the the Create Table command for the table specified by the Table_Name parameter. Notice that both commands are preceded by the dot point (.), and there’s not a semicolon at the end of the commands. For clear SQL commands, you use no dot mark, but you add the semicolon.

To quit from the SQLite environment, just type:

.quit

That way you’ll return back to the terminal environment. The next screenshot of my terminal synopsizes all the above:

Our next task is to add the database file to the Xcode project. You have two options for doing that:

• Either open the Finder, locate the file, and then drag and drop to the Project Navigator on Xcode, or,
• Go to Xcode, open the menu File > Add Files to “SQLite3DBSample”…, and then locate the file and click on the Add button.

No matter which way you’ll choose, make sure that the Copy items into destination group’s folder (if needed) and the SQLite3DBSample target checkmarks are selected in the window that will appear before the database file gets added to the project.

Demo App Interface Setup

In most of my tutorials, this part is usually one of the first things you read. However, due to the fact that at the previous sections we created the database class and the sample file, the setup of the interface for our demo app had to be waiting up to this point. In here, as you’ve already assumed, we’ll work in the Interface Builder, and we will add all those subviews needed to make the app working, just like the sample demonstrated at the beginning of the tutorial. Further than that, we’ll add the necessary IBOutlet properties and IBAction methods that will make everything properly work.

On the Project Navigator, click on the Main.storyboard file and wait until it appears in the Interface Builder. As I said in the App Overview section, this is going to be a navigation based app, therefore select the View Controller scene and then go to the menu: Editor > Embed In > Navigation Controller. Instantly, a navigation controller will be added at the left side of the scene, and a new arrow will point from the navigation controller to the View Controller scene.

Let’s focus now on adding all the necessary subviews to the scene, and after having finished with that, we’ll add one more scene (a new view controller) which we’ll use to add new records to the database. Right next you are given all the subviews you need to drag from the Objects library to the scene, along with the attributes needed to be specified:

UITableView

• Frame: X=0, Y=0, Width=320, Height=568

UITableViewCell

Drag a table view cell in the table view to make it prototype
* Row Height: 60
* Style: Subtitle
* Identifier: idCellRecord
* Selection: None
* Accessory: Detail Disclosure

UIBarButtonItem

• Add it to the right side of the navigation bar
• Identifier: Add
• Tint: Red=255, Green=128, Blue=0

Besides all the above, select the Navigation Item and set the next two attributes:
1. Title: SQLite 3 Demo
2. Back Button: Go Back

These are all the subviews of the View Controller scene. Here’s how it should look like:

Now, from the Objects library take a UIViewController object and drop it to the canvas. For this view controller, we need to create a new class, so for the time being we’ll just pause our work here.

Following the same way you did when you added the database class file to the project, add a new class of UIViewController kind. Specifically:

1. Go to the menu: File > New > File….
2. As the template for the file, select the Objective-C class in the Cocoa Touch category, under the iOS section.
3. In the second step, make sure that in the Subclass of field there is the UIViewController value. If there is not, just type it. In the Class field, set the EditInfoViewController as the name for the new class, and then click on the Next button to proceed.
4. In the last step, make sure that the SQLite3DBSample is checked, and click on the Create button.

Head back to the Interface Builder, and select the second, new scene. In the Utilities pane show the Identity Inspector, and in the Class field type the EditInfoViewController value. Immediately, the second view controller scene will turn into the Edit Info View Controller scene.

To connect the View Controller scene with the Edit Info View Controller scene, go to the Document Outline pane, Ctrl-Click on the View Controller scene object, and drag right onto the Edit Info View Controller object.

In the black popup window that appears (titled Manual Segue), select and click the Push option:

The two scenes will become connected, but there’s still one last thing to do. Click on the circle of the connection line, and in the Attributes inspector set the idSegueEditInfo as the identifier value for the segue.

Now, we can add the necessary subviews here too:

UITextField

• Frame: X=20, Y=93, Width=280, Height=30
• Placeholder: Type the first name…
• Color: Red=255, Green=128, Blue=0
• Border Style: No border style
• Background: Red=217, Green=219, Blue=221
• Capitalization: Words
• Return Key: Done

UITextField

• Frame: X=20, Y=139, Width=280, Height=30
• Placeholder: Type the last name…
• Color: Red=255, Green=128, Blue=0
• Border Style: No border style
• Background: Red=217, Green=219, Blue=221
• Capitalization: Words
• Return Key: Done

UITextField

• Frame: X=20, Y=186, Width=280, Height=30
• Placeholder: Type the age…
• Color: Red=255, Green=128, Blue=0
• Border Style: No border style
• Background: Red=217, Green=219, Blue=221
• Capitalization: Words
• Return Key: Done
• Keyboard: Numbers and Punctuation

UIBarButtonItem

• Add it to the right side of the navigation bar
• Identifier: Save
• Tint: Red=255, Green=128, Blue=0

Also, edit the navigation item and set the Edit Info value as its title.

Here’s how the second view controller should look like:

Let’s see now what IBOutlet properties and IBActions are needed to be declared for the subviews we previously added. Starting from the View Controller scene, we want an IBOutlet property for the table view, so as we can display our data, and an IBAction method for the bar button item, which we’ll use to perform the segue and transit to the EditInfoViewController view controller. Open the ViewController.h file, and add the next two declarations:

@interface ViewController : UIViewController

@property (weak, nonatomic) IBOutlet UITableView *tblPeople;


- (IBAction)addNewRecord:(id)sender;

@end

Go back to the Interface builder and make the proper connections.

Next, for the Edit Info View Controller scene we’ll need an IBOutlet property for each textfield, and an IBAction method for the save button. Similarly to the previous steps, open the EditInfoViewController.h file and declare them:

@interface EditInfoViewController : UIViewController

@property (weak, nonatomic) IBOutlet UITextField *txtFirstname;

@property (weak, nonatomic) IBOutlet UITextField *txtLastname;

@property (weak, nonatomic) IBOutlet UITextField *txtAge;


- (IBAction)saveInfo:(id)sender;

@end

Finally, go to the Interface Builder once again and do the appropriate connections, as shown in the next figure:

Note that when you’ll be viewing the EditInfoViewController view controller, the back button will appear to the navigation bar along with the Save button. To let it have the same color to the Save button you just need to go to the EditInfoViewController.m file, and to add the next line in the viewDidLoad method:

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view.

    // Set the navigation bar tint color.
    self.navigationController.navigationBar.tintColor = self.navigationItem.rightBarButtonItem.tintColor;

}

Adding New Records

Having the interface of the sample app prepared, we can go towards the implementation of our sample app where we’ll try out our database class. As no data still exist in our database, the best point to start from would be to develop the feature of adding a new record. That requires work in both of our view controllers: In the View Controller class we should make the Add (plus button) functioning, so we can navigate to the next view controller. In the Edit Info View Controller class, we will get all values from textfields, and using an insert command, we’ll add a new record to database.

Let’s see everything in details. Go to the ViewController.m file, and straight ahead to the addNewRecord: IBAction method. Navigating to a new view controller using segues is easy, so the only thing we have to do here is to write just one line of code:

- (IBAction)addNewRecord:(id)sender {
    [self performSegueWithIdentifier:@"idSegueEditInfo" sender:self];
}

Focusing now our attention on the EditInfoViewController class, the first thing we should take care about is to dismiss the keyboard every time the Done button on it is tapped. To do so, we must implement one textfield delegate method, but first, we must adopt the respective protocol. So, open the EditInfoViewController.h file, and modify the header line as follows:

@interface EditInfoViewController : UIViewController 

Next, we must indicate that our class is the delegate of the textfields, and that can be done in two ways: Either to do it in Interface Builder, or to do it programmatically. The second is the way I prefer, as I think is much simpler. Open the EditInfoViewController.m file and go to the viewDidLoad method. In there add these three lines:

- (void)viewDidLoad
{
    ...

    // Make self the delegate of the textfields.
    self.txtFirstname.delegate = self;
    self.txtLastname.delegate = self;
    self.txtAge.delegate = self;
}

Now, we are ready to implement a simple delegate method and know when the Done button of the keyboard gets tapped. That method is the textFieldShouldReturn:, and in its implementation we’ll perform just one task: We’ll resign the textfield from first responder. Here it is:

-(BOOL)textFieldShouldReturn:(UITextField *)textField{
    [textField resignFirstResponder];
    return YES;
}

Time to work with the database. Go to the top of the file, and import our custom class:

#import "DBManager.h"

Now that the database class can be used, let’s declare a private property to do so. Go to the private class section and add the next declaration:

@interface EditInfoViewController ()

@property (nonatomic, strong) DBManager *dbManager;

@end

Then, in the viewDidLoad method initialize it using the custom init method we implemented:

- (void)viewDidLoad
{
    ...

    // Initialize the dbManager object.
    self.dbManager = [[DBManager alloc] initWithDatabaseFilename:@"sampledb.sql"];

}

By initializing as shown above, upon the first run the database class will check if the sampledb.sql file exists or not in the documents directory, and it will copy it there if not found.

What we have left to do now is easy, but the most important part. Using all the textfield text values, we’ll prepare an insert query and we’ll execute it. To verify the outcome of the execution we’ll output to the debugger either a success message, or the error message if any error occurs. Also, upon successful saving we’ll display the number of the affected rows, so we’ll manage to see if our class works as expected.

To do all that go to the saveInfo: IBAction method. Right next is given its implementation:

- (IBAction)saveInfo:(id)sender {
    // Prepare the query string.    
    NSString *query = [NSString stringWithFormat:@"insert into peopleInfo values(null, '%@', '%@', %d)", self.txtFirstname.text, self.txtLastname.text, [self.txtAge.text intValue]];

    // Execute the query.
    [self.dbManager executeQuery:query];

    // If the query was successfully executed then pop the view controller.
    if (self.dbManager.affectedRows != 0) {
        NSLog(@"Query was executed successfully. Affected rows = %d", self.dbManager.affectedRows);

        // Pop the view controller.
        [self.navigationController popViewControllerAnimated:YES];
    }
    else{
        NSLog(@"Could not execute the query.");
    }
}

Notice that after having added a new record successfully, we also pop the view controller and return back to the View Controller one.

The app can be tested now for first time. Compile and run it, and try to add a new record. When you finish typing data, tap on the Save button and watch at the debugger. If you see a message similar to the next one, then congratulations, the database is working!

Loading and Displaying Records

Now that we can successfully add records to the database, the most reasonable next step is to display them, so we’ll work on the View Controller class. Summarizing what we have to do here, I would say that our job has two parts: The first one is to implement all the necessary, required table view methods so our loaded data from the database get listed properly on the table view. The second one is to create a select query, load our data and finally display them.

If you recall, when we did all the setup in the Interface Builder, we declared an IBOutlet property for the table view. Using it, we’ll make the View Controller class both the delegate and datasource of it, but prior to that we must adopt two necessary protocols, the UITableViewDelegate and the UITableViewDataSource. As always, this will take place in the ViewController.h file, where we’ll modify the @interface header line as follows:

@interface ViewController : UIViewController 

Next, in the ViewController.m file and in the viewDidLoad method we just have to write these:

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view, typically from a nib.

    // Make self the delegate and datasource of the table view.
    self.tblPeople.delegate = self;
    self.tblPeople.dataSource = self;
}

Now, let’s get started by loading the data from the database. To do so, we need three things:

1. To declare and initialize a DBManager property.
2. To declare and array for storing the returned data.
3. A private method to do the job.

Go to the private section of the class, and declare the next two properties, and one private method:

@interface ViewController ()

@property (nonatomic, strong) DBManager *dbManager;

@property (nonatomic, strong) NSArray *arrPeopleInfo;


-(void)loadData;

@end

Don’t worry if Xcode is showing an error. We just need to import our database class header:

#import "DBManager.h"

Now, as we exactly did in the EditInfoViewController class, we’ll initialize the database property here as well:

- (void)viewDidLoad
{
    ...

    // Initialize the dbManager property.
    self.dbManager = [[DBManager alloc] initWithDatabaseFilename:@"sampledb.sql"];

}

Our next task is to implement the loadData method, and prepare the select query. Let’s see it first:

-(void)loadData{
    // Form the query.
    NSString *query = @"select * from peopleInfo";

    // Get the results.
    if (self.arrPeopleInfo != nil) {
        self.arrPeopleInfo = nil;
    }
    self.arrPeopleInfo = [[NSArray alloc] initWithArray:[self.dbManager loadDataFromDB:query]];

    // Reload the table view.
    [self.tblPeople reloadData];
}

Three things happen here: At first, the query string is prepared, and as you see, is a simple select statement. Then, the arrPeopleInfo array gets initialized, and upon its initialization we call the loadDataFromDB: method of the dbManager object. Once the data has been fetched and returned, we reload the table view to display it. For the time being the last line will do nothing, but after we have had our table view ready, it will be working just fine.

Loading data is as simple as you see in the previous code snippet. Having done so, enables us to move ahead and work with the table view. Note that based on the arrPeopleInfo array, we will be able to define the total rows of the table view.

Regarding the table view methods, let’s get started from the easy ones:

-(NSInteger)numberOfSectionsInTableView:(UITableView *)tableView{
    return 1;
}


-(NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section{
    return self.arrPeopleInfo.count;
}


-(CGFloat)tableView:(UITableView *)tableView heightForRowAtIndexPath:(NSIndexPath *)indexPath{
    return 60.0;
}

In the first one, we tell our table view that we want to have just one section. With the second one, we specify the total number of rows displayed in the table view. Actually, this method will return as many rows as those existing in the result set that will be loaded from the database. Finally, with the third one we set each row’s height to 60.0 points.

To display a row’s data, we’ll use the tableView:cellForRowAtIndexPath: method. In it, initially we’ll dequeue the prototype cell we created in the Interface Builder. Then, making use of the arrColumnNames array of the dbManager property we’ll define the index of each column (field) in the sub-array for the current index of the arrPeopleInfo array. Finally, we’ll get the actual data and assign it to the textLabel and detailTextLabel labels of the cell. Here’s the implementation:

-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath{
    // Dequeue the cell.
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"idCellRecord" forIndexPath:indexPath];

    NSInteger indexOfFirstname = [self.dbManager.arrColumnNames indexOfObject:@"firstname"];
    NSInteger indexOfLastname = [self.dbManager.arrColumnNames indexOfObject:@"lastname"];
    NSInteger indexOfAge = [self.dbManager.arrColumnNames indexOfObject:@"age"];

    // Set the loaded data to the appropriate cell labels.
    cell.textLabel.text = [NSString stringWithFormat:@"%@ %@", [[self.arrPeopleInfo objectAtIndex:indexPath.row] objectAtIndex:indexOfFirstname], [[self.arrPeopleInfo objectAtIndex:indexPath.row] objectAtIndex:indexOfLastname]];

    cell.detailTextLabel.text = [NSString stringWithFormat:@"Age: %@", [[self.arrPeopleInfo objectAtIndex:indexPath.row] objectAtIndex:indexOfAge]];

    return cell;
}

Notice that instead of using the indexOfFirstname, indexOfLastname and indexOfAge variables for accessing the proper data, we could have used the index number for each field directly. For example, instead of writing this:

cell.detailTextLabel.text = [NSString stringWithFormat:@"Age: %@", [[self.arrPeopleInfo objectAtIndex:indexPath.row] objectAtIndex:indexOfAge]];

we could just have written this:

cell.detailTextLabel.text = [NSString stringWithFormat:@"Age: %@", [[self.arrPeopleInfo objectAtIndex:indexPath.row] objectAtIndex:3]];

Using or not the column names array is totally up to you, and I used it here just for demonstrative reasons. I just wanted to make clear how you can specify the index of a field programmatically, even though our example is quite simple and it is not necessary to do this.

So, it seems that we’ve finished taking all the proper actions for loading the data and showing it to the table view. However, if you run the app now, you’ll see no data displayed at all. That’s because of a simple reason: We didn’t call the loadData method anywhere. So, go to the viewDidLoad method and add the next line:

- (void)viewDidLoad
{
    ...

    // Load the data.
    [self loadData];
}

Run the app once again. This time, the records you added in the previous step are shown in the table view. That’s great.

Before we consider this section as finished, there’s one more detail we should take care about. You’ll definitely notice that when adding a new record and then tapping on the Save button, the record is saved and you’re transferred back to the View Controller view controller, but the table view doesn’t get updated with the new data, unless you re-launch the app. That’s because for the time being the View Controller view controller cannot know whether new data have been added to the database after the Edit Info View Controller view controller has popped from the navigation stack. To workaround this, we must create a protocol in the EditInfoViewController class, declare a delegate method to be used for notifying when a new record has been added, and adopt that protocol to the ViewController class.

Let’s give life to all the above. Start by opening the EditInfoViewController.h file. At the top of it, add the next code fragment:

@protocol EditInfoViewControllerDelegate

-(void)editingInfoWasFinished;

@end

Next, in the interface right below, add a declaration for the delegate property:

@interface EditInfoViewController : UIViewController 

...

@property (nonatomic, strong) id delegate;

@end

Finally, go to the saveInfo: IBAction method and modify it, so the delegate method is called before popping the view controller. Right next, you are given that method updated:

- (IBAction)saveInfo:(id)sender {
    // Prepare the query string.
    NSString *query = [NSString stringWithFormat:@"insert into peopleInfo values(null, '%@', '%@', %d)", self.txtFirstname.text, self.txtLastname.text, [self.txtAge.text intValue]];

    // Execute the query.
    [self.dbManager executeQuery:query];

    // If the query was successfully executed then pop the view controller.
    if (self.dbManager.affectedRows != 0) {
        NSLog(@"Query was executed successfully. Affected rows = %d", self.dbManager.affectedRows);

        // Inform the delegate that the editing was finished.
        [self.delegate editingInfoWasFinished];

        // Pop the view controller.
        [self.navigationController popViewControllerAnimated:YES];
    }
    else{
        NSLog(@"Could not execute the query.");
    }
}

With the above three steps, the EditInfoViewController will notify the delegate class every time a new save action occurs.

Let’s go now to the ViewController.h file. Go to the top of it, and make the next import:

#import "EditInfoViewController.h"

Then, modify the @interface header a bit:

@interface ViewController : UIViewController 

As you see, now we are adopting the EditInfoViewControllerDelegate protocol, so the only thing we have left is to implement the delegate method. Go to the ViewController.m file, and add the next code segment:

-(void)editingInfoWasFinished{
    // Reload the data.
    [self loadData];
}

As you may have expected, the only thing we do is to load our data once again.

However, nothing is going to happen until we make the ViewController class the delegate of the EditInfoViewController one. We’ll do that in the prepareForSegue:sender: method, which is called before the segue is performed. Here it is:

-(void)prepareForSegue:(UIStoryboardSegue *)segue sender:(id)sender{
    EditInfoViewController *editInfoViewController = [segue destinationViewController];
    editInfoViewController.delegate = self;
}

If you run the app, you’ll see that is working and behaving much better now. When adding new records, they immediately appear in the table view after having tapped on the Save button.

Editing a Record

Our sample app will be much better if we add support for editing and deleting records, apart from just adding new and loading existing ones. Also, that way we’ll see in action how the update and delete queries work, and we’ll test our database class even more.

In this section we’ll see how to edit a record. Running the app and looking at the table view, you notice that we have added a detail disclosure indicator on the prototype cell. That’s what we’ll use to edit a record matching to the respective row. The actual editing will take place in the EditInfoViewController class, which we’ll modify a little bit, so when saving it will either execute an insert or an update query.

The most important part of the underlying logic is the existence of a public int property in the EditInfoViewController class, in which the edited record’s ID will be assigned. When saving, that property will be used to specify the exact data that should be updated. However, in case of adding a new record, we’ll set the −1 value to this property, indicating that way we want to run an insert query, not an update. Lastly, when the EditInfoViewController view controller is appeared to edit a record, the data for that specific record will be loaded and assigned to the textfields.

If all the above seem confusing, don’t worry. Come along to perform some simple steps, and everything will become crystal clear.

Let’s get started from the EditInfoViewController.h file, where we should declare the public int property:

@interface EditInfoViewController : UIViewController 

...

@property (nonatomic) int recordIDToEdit;

@end

Now, open the EditInfoViewController.m file and declare a private method which will be used to load the edited data. Go to the private section of the class, and add the next line:

@interface EditInfoViewController ()

...

-(void)loadInfoToEdit;

@end

Now, let’s implement it:

-(void)loadInfoToEdit{
    // Create the query.
    NSString *query = [NSString stringWithFormat:@"select * from peopleInfo where peopleInfoID=%d", self.recordIDToEdit];

    // Load the relevant data.
    NSArray *results = [[NSArray alloc] initWithArray:[self.dbManager loadDataFromDB:query]];

    // Set the loaded data to the textfields.
    self.txtFirstname.text = [[results objectAtIndex:0] objectAtIndex:[self.dbManager.arrColumnNames indexOfObject:@"firstname"]];
    self.txtLastname.text = [[results objectAtIndex:0] objectAtIndex:[self.dbManager.arrColumnNames indexOfObject:@"lastname"]];
    self.txtAge.text = [[results objectAtIndex:0] objectAtIndex:[self.dbManager.arrColumnNames indexOfObject:@"age"]];
}

Everything is quite straightforward here. At first, we form the query. As you notice, it’s the first time we have a where clause. Then, we get the data from the database and assign the appropriate values to the textfields.

The above method won’t work if we don’t call it, so go to the viewDidLoad method and make a conditional call:

- (void)viewDidLoad
{
    ...

    // Check if should load specific record for editing.
    if (self.recordIDToEdit != -1) {
        // Load the record with the specific ID from the database.
        [self loadInfoToEdit];
    }
}

Great, but we’ve left one more step in this class: To modify the saveInfo: IBAction method and make it update an existing record instead of just inserting new records to the database. Right below you’re given the method implemented in its final form. Notice how using the recordIDToEdit property we specify the query type:

- (IBAction)saveInfo:(id)sender {
    // Prepare the query string.
    // If the recordIDToEdit property has value other than -1, then create an update query. Otherwise create an insert query.
    NSString *query;
    if (self.recordIDToEdit == -1) {
        query = [NSString stringWithFormat:@"insert into peopleInfo values(null, '%@', '%@', %d)", self.txtFirstname.text, self.txtLastname.text, [self.txtAge.text intValue]];
    }
    else{
        query = [NSString stringWithFormat:@"update peopleInfo set firstname='%@', lastname='%@', age=%d where peopleInfoID=%d", self.txtFirstname.text, self.txtLastname.text, self.txtAge.text.intValue, self.recordIDToEdit];
    }


    // Execute the query.
    [self.dbManager executeQuery:query];

    // If the query was successfully executed then pop the view controller.
    if (self.dbManager.affectedRows != 0) {
        NSLog(@"Query was executed successfully. Affected rows = %d", self.dbManager.affectedRows);

        // Inform the delegate that the editing was finished.
        [self.delegate editingInfoWasFinished];

        // Pop the view controller.
        [self.navigationController popViewControllerAnimated:YES];
    }
    else{
        NSLog(@"Could not execute the query.");
    }
}

Our job in the EditInfoViewController class is over. However, that was just the half part of what we should do. We must go to the ViewController class now and make the detail disclosure button of the cells functional.

To detect tappings on the detail disclosure buttons, UITableViewDelegate protocol provides the tableView:accessoryButtonTappedForRowWithIndexPath: delegate method. We are going to implement it, and inside its body we’ll do two simple tasks:

1. We will specify the record ID that’s about to be edited.
2. We’ll perform the segue so the EditInfoViewController view controller gets pushed to the navigation stack and make us able to edit.

We’ll get started by declaring a private property to the ViewController class similar to the recordIDToEdit, because we’ll need a way to keep the record ID matching to the row of the tapped button. So, go to the private section of the interface, and do so:

@interface ViewController ()

...

@property (nonatomic) int recordIDToEdit;

@end

With the above private property declared, we can proceed to the tableView:accessoryButtonTappedForRowWithIndexPath: implementation:

-(void)tableView:(UITableView *)tableView accessoryButtonTappedForRowWithIndexPath:(NSIndexPath *)indexPath{
    // Get the record ID of the selected name and set it to the recordIDToEdit property.
    self.recordIDToEdit = [[[self.arrPeopleInfo objectAtIndex:indexPath.row] objectAtIndex:0] intValue];

    // Perform the segue.
    [self performSegueWithIdentifier:@"idSegueEditInfo" sender:self];
}

Easy enough, but now we must tell the EditInfoViewController class what the record ID we want to edit is. This should take place before the segue is performed, so go to the prepareForSegue:sender: and add just one line:

-(void)prepareForSegue:(UIStoryboardSegue *)segue sender:(id)sender{
    ...
    editInfoViewController.recordIDToEdit = self.recordIDToEdit;
}

We are almost finished. The only issue that we’re still having, is that we haven’t specified the value of the recordIDToEdit property when we’re about to add a new record. That can be easily fixed, as we just have to go to the addNewRecord: IBAction method definition, and modify it as follows:

- (IBAction)addNewRecord:(id)sender {
    // Before performing the segue, set the -1 value to the recordIDToEdit. That way we'll indicate that we want to add a new record and not to edit an existing one.
    self.recordIDToEdit = -1;

    // Perform the segue.
    [self performSegueWithIdentifier:@"idSegueEditInfo" sender:self];
}

Everything is ready now. Feel free to run the app once again, and then try to edit one or more of any existing records. As it seems, our database class perfectly works and our sample app gains more features.

Deleting a Record

Now that we can insert, load and update records, let’s make our app able to delete them as well. To delete a record, we’ll use the built-in table view functionality, where by swiping on a row towards left, the delete button is appeared.

To do that possible, we must implement the tableView:commitEditingStyle:forRowAtIndexPath: table view method. In it, if the editing style is a delete style, we’ll execute a delete query, and then we’ll reload the data. As simple as that, and the record deletion will be ready. Let’s see it:

-(void)tableView:(UITableView *)tableView commitEditingStyle:(UITableViewCellEditingStyle)editingStyle forRowAtIndexPath:(NSIndexPath *)indexPath{

    if (editingStyle == UITableViewCellEditingStyleDelete) {
        // Delete the selected record.
        // Find the record ID.
        int recordIDToDelete = [[[self.arrPeopleInfo objectAtIndex:indexPath.row] objectAtIndex:0] intValue];

        // Prepare the query.
        NSString *query = [NSString stringWithFormat:@"delete from peopleInfo where peopleInfoID=%d", recordIDToDelete];

        // Execute the query.
        [self.dbManager executeQuery:query];

        // Reload the table view.
        [self loadData];
    }
}

At first, we set the ID of the record to be deleted. Then, we compose the query string appropriately, we execute it using the executeQuery: method of our database class, and finally we load the data once again. That way, every time the delete button of a row is tapped, the respective record on the database will be permanently removed.

If you want now give the app one more try, and see how it works. All the basic features are now implemented and fully functional.

Compile and Run the App

This section exists in almost every tutorial in case you are one of those guys who wait to arrive at the finish point, and then run and test the app. Well, we’re almost at the end of our mission, so if you still haven’t run it, do it now. Begin by adding a new record, and then save it. Next, try to edit it, and finally delete it. Add as many records as you want and generally do whatever you want for testing both the sample app and the database class. Even more, add any extra features you may think of and build more complex queries.

Right next it’s demonstrated the animated graphic presented at the beginning of the tutorial too:

Summary

I’ve always believed that working with databases is the best possible solution when dealing with data, and having relevant tools or libraries ready for use is a must for every developer. SQLite might not be as powerful as other databases or database management systems, however is light and maybe the most suitable solution for a mobile platform. The class we developed in this tutorial is not set of stone, so keep in mind that you can change it and evolve it at any time and in any possible way that serves you. With it, I just wanted to provide you with a working, suitable for the most cases, reusable component, which could potentially have double results: Both to teach you the basics of SQLite, and to get you out of the hassle of developing other custom data handling solutions. That said, I truly hope you have learned and earned something new by this tutorial, and as always let me know your thoughts or questions. Until next time, I wish an easy, bug-free programming to all!

For your reference, you can download the complete Xcode project from here.

So, you are about to start developing the next super app, you have everything planned and designed, but there’s still one last thing you haven’t made your mind up about; how to make some earnings out of it! Well, there are two options apart from offering it completely free: Either to make it a paid app where your potentials users should pay to download it, or make it a free app, add some advertisements, and earn a revenue from the ads.

Today’s trends show that it’s more possible for users to download free apps, instead of paid ones. They will pay for an app if it really worths it, or if it’s super famous and have received good rating. So, having that in mind, you decide to make your app a free one, and integrate advertisements in it. To do so, you have various services to pick from in order to display ads, and one of them is the iAd Network provided by Apple. Undoubtably, you have already concluded even from the tutorial’s title that the today’s topic is about how to use iAd advertisements, but before we see all in action let’s see some introductory stuff.

Deciding about the kind of your application (paid or free) before starting the actual implementation is really important, as it affects your work directly. For paid apps, there’s no need to do anything particular, however for free apps it’s necessary to define where the ads will appear, and setup your interface accordingly. Speaking of position, ads should be placed either to the top or the bottom of your view controller. If your app does not contain a tab bar, then ads should be placed at the bottom of the screen, otherwise at the top. Note that if you display ads anywhere else in the view, then the Human Interface Guidelines are breached and Apple will reject it with no second thought.

Besides all the above regarding the positioning of the ads, there are a couple more rules you should have in mind. Firstly, don’t expect ads to be always available. Various network or server-side problems may cause troubles in ad serving, and it’s your duty to take care so no ugly empty space appears when no ads are there for you. It’s considered as a good idea to show another meaningful view when no ads exist. Actually, it’s totally up to your app design whether you should display another view instead of the ad banner or not, and what kind of view this should be.

Also, ad banners should not be obscured by other view controllers all the time. You have to make sure that they will appear in the most viewable view controller, the one that users will spend the most of their time when working with the app, and maximize that way the possibility for your ads to get tapped and earn some money.

Regarding the revenue, both Apple and developers benefit when users tap on advertisements. Actually, the developer’s cut is equal to the 70% percent of the revenue, while the rest 30% is held by Apple as a commission for offering you the iAd Network services. The same split applies to paid apps too.

It’s quite common for sole developers and companies to follow another approach, to create two versions of the same app. The first version, the paid, is the full-featured one. The second version is free, but it doesn’t contain all the features that the paid version ships. That free version, also called Lite version, can have advertisements and beyond the revenue you may earn from them, you can also count on extra revenue if users like the app and buy the paid version. Remember that you should never add advertisements in paid apps. Even if Apple allows that to happen, and I seriously doubt about that, you’ll receive the worst critics and ratings, as users don’t pay to see ads.

In the next sections of the tutorial we’ll implement as always a sample app, and through this you’ll learn how to integrate ads provided by Apple into your projects. If you are new to this, you’ll find out that using ads is a super-easy process. So, keep reading and discover how all this new great stuff works!

App Overview

As always, our tutorial will be based on the creation of a sample app. In the one we will start developing right next, we will see how to integrate iAd advertisements and display ad banners within a few steps. More specifically, we’ll do the following:

• We will add an ad banner at the bottom side of the view. This will be the container in which the ads will be displayed if available. If there are no available ads, then we’ll hide it until we have something to show.
• Generally speaking, a modal full-screen view shows up when tapping on an advertisement, covering everything else behind it. In such cases, any critical or important tasks regarding especially visual updates must be paused or stopped, and get restarted after the ad has been closed. To demonstrate how this can be managed, we’ll use a timer to count the seconds that the user is viewing the default view controller’s view, and a label to display a message containing the timer’s value. When an ad gets tapped, we’ll stop counting, and we’ll restart doing so when it’s closed again.

Also, in this tutorial we are going to use an extra framework, the iAd Framework. Without it, it’s not possible to display and handle iAd advertisements.

The next figure illustrates how the app of this tutorial will look like:

Project Creation

Let’s begin by creating a new project for the sample app. Launch Xcode and in the Welcome window select the respective option, as shown in the next figure:

In the guide that appears, select the Single View Application template, in the Application category under the iOS section:

Click Next, and in the Product Name field set the iAdDemo as the project’s name. Also, make sure that the iPhone option is the selected one in the Devices menu. Leave the rest as it is, and proceed:

In the last step of the guide select a directory to save the project and click Create.

Interface Configuration

Now that we have an empty project on our hands, let’s begin working on the interface of the app. Click on the Main.storyboard file to let Interface Builder appear. Below you are given all the subviews along with their attributes that you should add, so the final outcome of our work in this section is similar to the app figure illustrated previously. Note that you could skip some of the subviews that will be described next if you just want to focus just on the ad banner.

UILabel

1. Frame: X=20, Y=60, Width=280, Height=40
2. Text: iAd Integration
3. Font: Avenir Black, 24.0pt
4. Text Alignment: Center

UILabel

1. Frame: X=20, Y=108, Width=280, Height=21
2. Text: by Appcoda
3. Font: Avenir Medium Oblique, 17.0pt
4. Text Alignment: Center
5. Text Color: Red=255, Green=128, Blue=0

UILabel

1. Frame: X=20, Y=360, Width=280, Height=40
2. Text: None
3. Font: Noteworthy Light, 15.0pt
4. Text Alignment: Center
5. Text Color: Light Gray

UILabel

1. Frame: X=0, Y=518, Width=320, Height=50
2. Text: Ad banner will appear here
3. Font: Avenir Medium, 14.0pt
4. Text Alignment: Center
5. Text Color: White
6. Background Color: Red=255, Green=128, Blue=0

ADBannerView

1. Frame: X=0, Y=518, Width=320, Height=50

After adding all the above subviews and setting their attributes as shown, your interface should look like this:

It’s necessary to create and connect two IBOutlet properties now. The first one regards the ad banner view, while the second one will be connected to the label that contains no text. In this label we’ll display later the time counter value. Open the ViewController.h file, and the next two lines:

@interface ViewController : UIViewController 

@property (weak, nonatomic) IBOutlet ADBannerView *adBanner;

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

@end

At this point Xcode will issue an error and some warnings. That’s because we haven’t added the iAd framework yet, and we haven’t included the appropriate library on our file. Let’s fix everything and let’s start by adding the framework. On the Project Navigator, click on the iAdDemo project, and then in the General tab.

Next, at the bottom side of the screen, under the Linked Frameworks and Libraries section, click on the plus icon to add the new framework. In the new window that appears, start typing the text: “iAd Framework” and Xcode will immediately suggest it. Select it and then click on the Add button:

Now head back to the ViewController.h file, and import the next library:

#import 

With that, Xcode stops displaying any error and warnings. Finally, our class must adopt the ad banner view protocol, so we can access all the necessary delegate methods. Modify the interface header line as follows:

@interface ViewController : UIViewController 

As a last step, the two IBOutlet properties must be connected to the appropriate subviews. Open the Main.storyboard file, and connect the adBanner property to the ad banner view, and the lblTimerMessage label to the textless label view.

iAd Integration

By adding the ad banner view to the interface and by also adding the iAd framework into the project, advertisements are already able to be delivered to the app. However, no handling is possible yet, therefore our goal here is to take all that actions that will make the ad banner management feasible.

The iAd framework provides several delegate methods for managing ads. These allow us to know when an ad is about to be shown or it has already been shown, when a failure occurs and no more ads can be served, and finally when the user taps on an ad to view it on full-screen mode or the modal ad view gets dismissed. Besides all that, you should always have in mind that ads are not delivered right away. Therefore, until the first ad is ready to be shown, the ad banner must not be visible. It should also become hidden when the iAd Network stops serving ads for some reason.

Diving into code now, initially we must perform two things: To make our class the delegate of the ad banner view, and secondarily to hide it. Open the ViewController.m file, and go to the viewDidLoad method to add the next couple of lines:

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view, typically from a nib.

    // Make self the delegate of the ad banner.
    self.adBanner.delegate = self;

    // Initially hide the ad banner.
    self.adBanner.alpha = 0.0;
}

As you see, we hide the ad banner view simply by setting its alpha value to 0. Later on, when a delegate method will inform us that an ad is ready to be shown, we’ll set that value to 1 again, and to make it more attractive we’ll do so using an animation. Changing the alpha value though is not the only way to hide or show the ad banner. There are many other ways to do that, as for example to change the value of the hidden banner’s property, or initially place the ad banner view out of the visible screen area. What method you’ll finally choose is totally up to you, and to what best suits to your application. For simplicity reasons, I just chose to use the alpha value.

The ADBannerViewDelegate protocol provides five delegate methods in total. Using them, we can manage the ads and ultimately the behavior of our app. Let’s see them one by one, and let’s discuss shortly what each one is about. Note that in the body of every delegate method I’ve intentionally added a NSLog command, so when we run the app later to know which method exactly has been called.

The first method is this:

-(void)bannerViewWillLoadAd:(ADBannerView *)banner{
    NSLog(@"Ad Banner will load ad.");
}

It’s easy from the method’s name to conclude that this one is called when a new advertisement is about to be loaded. Note that when this method is called the ad is not yet ready to be displayed.

The second delegate method:

-(void)bannerViewDidLoadAd:(ADBannerView *)banner{
    NSLog(@"Ad Banner did load ad.");
}

This one is called after a new ad has been loaded and is ready to be displayed. Later, in this method we’ll add the code needed to make the ad banner view visible again, as we’ll know that there is an ad to show.

The third delegate method:

-(BOOL)bannerViewActionShouldBegin:(ADBannerView *)banner willLeaveApplication:(BOOL)willLeave{
    NSLog(@"Ad Banner action is about to begin.");

    return YES;
}

This method is called when the user taps on the banner, and the ad is going to be displayed in a full size modal view. When that happens, any visual or critical tasks that regard user should be paused until that modal view gets dismissed. The interesting with this method is the value it returns. When the returned value is YES, then the ad will be shown in a full-screen view indeed. However, if the returned value is NO, then nothing will happen when users tap on the ad.

The fourth delegate method:

-(void)bannerViewActionDidFinish:(ADBannerView *)banner{
    NSLog(@"Ad Banner action did finish");
}

This method is called when the full-screen view with the add gets dismissed. It’s very useful, as in here any paused or stopped tasks should be put in action again.

Finally, the fifth delegate method:

-(void)bannerView:(ADBannerView *)banner didFailToReceiveAdWithError:(NSError *)error{
    NSLog(@"Unable to show ads. Error: %@", [error localizedDescription]);
}

This method is also very useful and important, as it’s called when no ads are available to be delivered to the app. When it’s called, it’s our duty to hide the ad banner view so no blank space is shown to the user when no ads exist.

As you understand, all these delegate methods make the ad handling a really easy task. Now, as we said before, we must show the ad banner view when an advertisement is ready to be displayed, so modify the bannerViewDidLoadAd: delegate method as shown right next:

-(void)bannerViewDidLoadAd:(ADBannerView *)banner{
    NSLog(@"Ad Banner did load ad.");

    // Show the ad banner.
    [UIView animateWithDuration:0.5 animations:^{
        self.adBanner.alpha = 1.0;
    }];
}

You see that using an animation we set the alpha value of the ad banner view to 1 again. That animation will result in a fade-in effect.

Lastly, when there are no ads to be displayed we should hide the ad banner view. Go to the bannerView:didFailToReceiveAdWithError: and add the same code as above. This time make the alpha value 0:

-(void)bannerView:(ADBannerView *)banner didFailToReceiveAdWithError:(NSError *)error{
    NSLog(@"Unable to show ads. Error: %@", [error localizedDescription]);

    // Hide the ad banner.
    [UIView animateWithDuration:0.5 animations:^{
        self.adBanner.alpha = 0.0;
    }];
}

The most important work with the ads have been done. In the next section of the tutorial we’ll see how to use the other delegate methods, but our app is already pretty functional. So, if you want give it a try and wait for the first ad to be shown.

Adding the Counter

The ad banner now works great, and the most important goal, showing and hiding the banner properly, has been achieved. However, this tutorial wouldn’t be complete without having discussed about all the important delegate methods, so in this section we are going to make an interesting addition to the project. We are going to use a timer (a NSTimer object) that will count the seconds the user is seeing the View Controller scene, and using the delegate methods provided by iAd framework we’ll pause counting when an ad is displayed in full-screen mode. After the ad view has been dismissed, the counter will work again.

Let’s get started by declaring three properties that we’ll need for our purpose. The first property is the timer object, the second an integer value that will be used to count the seconds elapsed, and finally the third property is a boolean flag that will indicate whether the counting should be paused or not. In the ViewController.m file, go to the private class section, and add the next properties as shown below:

@interface ViewController ()

@property (nonatomic, strong) NSTimer *timer;

@property (nonatomic) int secondsElapsed;

@property (nonatomic) BOOL pauseTimeCounting;


@end

Now, in the viewDidLoad method let’s do some initializations:

- (void)viewDidLoad
{
    [super viewDidLoad];
      ...
     ...

    // Start the timer.
    self.timer = [NSTimer scheduledTimerWithTimeInterval:1.0 target:self selector:@selector(showTimerMessage) userInfo:nil repeats:YES];

    // Set the initial value for the elapsed seconds.
    self.secondsElapsed = 0;
}

As you see in the timer object creation, in the selector parameter is given the showTimerMessage method name. This is a private method that does not exist yet, and it will be called by the timer every one second (the interval argument set to 1.0). Of course, we want our timer to work repeatedly, so we set the repeats parameter value to YES.

Xcode is showing a warning now, because it’s unable to find a declaration for the above method. Let’s go to fix it by declaring the method first, and then we’ll define it. Go back to the private class section, and add the next line:

@interface ViewController ()

...
...

-(void)showTimerMessage;

@end

In its definition now, you’ll see in the following code fragment that the code execution flow depends on the pauseTimeCounting flag. If its value is false, then we’ll keep counting and updating the text of the lblTimerMessage. Apparently, when its value is true we won’t count. Notice that before any text update it’s necessary to increase the secondsElapsed property’s value by one. The implementation is really simple, so there you go:

-(void)showTimerMessage{
    if (!self.pauseTimeCounting) {
        self.secondsElapsed++;

        self.lblTimerMessage.text = [NSString stringWithFormat:@"You've been viewing this view for %d seconds", self.secondsElapsed];
    }
    else{
        self.lblTimerMessage.text = @"Paused to show ad...";
    }
}

Let’s get to the point now, and let’s see how to use two more iAd delegate methods. The first one we’ll see, is the bannerViewActionShouldBegin:willLeaveApplication: one. As I have already said, this method is called after a user has tapped on an ad, and a full-screen view is about to be shown containing the ad. Of course, it’s necessary the returned value of that method to be set to YES, otherwise no ad will be displayed. What we want when this method is called is quite simple: To tell our app that the time counting should be paused. To do that, we’ll simply change the value of the pauseTimeCounting flag. Let’s see the method:

-(BOOL)bannerViewActionShouldBegin:(ADBannerView *)banner willLeaveApplication:(BOOL)willLeave{
    NSLog(@"Ad Banner action is about to begin.");

    self.pauseTimeCounting = YES;

    return YES;
}

Apart from pausing the counting process, we must also allow it to continue when a full-image view with an ad has been closed. For that purpose, we’ll use the bannerViewActionDidFinish: delegate method. In it, we’ll simply change once again the flag’s value. Here it is:

-(void)bannerViewActionDidFinish:(ADBannerView *)banner{
    NSLog(@"Ad Banner action did finish");

    self.pauseTimeCounting = NO;
}

That was our last touch! Now, when the ad banner gets tapped the counting will be paused, and it will keep going again once the ad has been dismissed.

Compile and Run the App

At this point, feel free to compile and run the app. You will notice that at the bottom of the screen the ad banner will appear after a while, and the counter’s value is displayed in the message label. Tap on the ad banner and watch the advertisements in full-screen mode. When you go back to the View Controller scene, you see that the time counting wasn’t active while you were viewing ads. If suddenly no ads are being served, don’t worry, that’s normal. Ad delivery may stop from time to time.

As an extra exercise, if you want try to display the ad banner at the top of the view.

Summary

Integrating advertisements into an application is a quite common tactic, and a good way to make some earnings while you give you app for free. To tell the truth, maybe you won’t make a fortune from ads, but if your app acquire big download numbers then you’ll probably have a remarkable revenue. As you saw in this tutorial, there are simple rules regarding the ad banners, and the required code is just a matter of a few lines. So, if you’re still thinking about whether you should add ads on your app and how to do it, this is your chance. Of course, you are recommended and encouraged to go through the official documentation as well. I hope this tutorial becomes helpful to all of you, and as always feel free to share any thoughts or comments with us.

For your reference, you can download the complete Xcode project from here.

In my previous tutorial, I presented an easy and fast way to implement the login with Facebook feature. Based on the FBLoginView class, I demonstrated how logging in and out from Facebook can be done in really a few minutes with the assistance of a predefined login button. In this tutorial we’ll do the exact same thing, but this time we won’t use any automatic solution. Instead, we will implement every part of the login process manually and we’ll see in some detail level how everything works when connecting to Facebook. That’s a useful knowledge to have, as there are many cases that the default login view we saw in the last tutorial isn’t handful at all.

Before we start programming, it is necessary to present some basic terms, so you’ve got an idea about the whole process. The first important thing you should know, is that after a successful login with Facebook the app receives an access token. This is a unique key, that allows to perform requests and exchange data with Facebook in a secure fashion, without having to authorize the app all the time. One could say that the whole login hassle happens just to get that access token. Once received, and depending on the permissions your app asks for, you can freely get and send data.

The key class of the Facebook SDK that handles everything that has to do with the access token, is the FBSession class. This one, manages all the various session states that a connection can have, and is the one that determines the logged in status. It would be useful to take a quick look at the state lifecycle, as that would help to understand what we’ll do next. Let’s see some details:

• When an app is launched, the initial session state, meaning the initial state value set to the FBSession class by default, is the FBSessionStateCreated. The class searches for an existing, stored access token, and if founds one, it goes to the FBSessionStateCreatedTokenLoaded, and then to the FBSessionStateOpen, where the session is open and data exchange can take place with no problem.
• When no access token exists and a login process is on the way, then from the initial FBSessionStateCreated state, when the login UI is appeared the state changes to FBSessionStateCreatedOpening. If all goes well on login/app authorization, then the state gets the FBSessionStateOpen value. However, if during the credentials entry or on app authorization the user taps on the Cancel button and stops the login process, then the state gets the FBSessionStateClosedLoginFailed value.
• There are cases where the initial permissions asked during login are not enough, so additional permissions are needed to be granted. If that successfully takes place, then the state changes its value from FBSessionStateOpen to FBSessionStateOpenTokenExtended. Note that no extra permissions can be asked if the current session state doesn’t have the FBSessionStateOpen value.
• Finally, when logging out, then from any of the two open states, the FBSessionStateOpen and the FBSessionStateOpenTokenExtended, the session ends up with the FBSessionStateClosed state value.

In the above description, I mentioned a couple of times the term “permissions”, so now let me make a comment on them. Permissions actually determine what assets, features or resources an app can have access to, and they are separated in two categories: The read and publish permissions. To the read category belong all those that describe access to user info, while to the second one belong all those that allow an app to publish on behalf of the user. If no permissions are requested for a specific resource, then accessing it is impossible. A login process is initiated using read permissions, and always the public user info, or in other words the “public_profile” permission, is granted by default. When users login with Facebook through an app may become hesitant when they’re asked to grant permissions, so make sure to ask only for those permissions that are necessary for the app. We’ll talk about permission more later in the tutorial as well.

Finally, a word about the Graph API, as this is a term you’ll meet in the sections that follow. The Graph API, is actually the Facebook API for communicating and exchanging data. Is HTTP-based, and it’s used for all the tasks you want to do with Facebook. Regarding the Facebook SDK for iOS, there is a wide number of methods that work with it. In this tutorial we’ll use just a couple of them. If you are curious though and you’d like to see more about it, then feel free to read more on Facebook documentation. Of course, if you’re about to develop an app that works with Facebook and does more than logging users in, you definitely need to read some stuff.

All the discussion made so far, will help you understand all that coming next. If you need more theory or to get fundamental knowledge, then there’s no better option than visiting the source itself, meaning the Facebook documentation. For now, we’ve said enough already, so let’s begin doing some work.

App Overview

The next figure illustrates the final outcome of our implementation in this tutorial:

The main goal is to manage to login with Facebook, and then logout, using a custom button. Further than doing that, we’ll also get some piece of the user’s public info, the e-mail address and the profile picture after a successful login.

The UI will contain a few controls: Some labels for showing the user’s info and the current connection status, an image view for displaying the profile picture, an activity indicator that will animate when opening a session, and of course, the custom login/logout button. We’ll see more details about all these subviews when we’ll setup the interface.

Lastly, there’s a dedicated section in this tutorial almost for every part of the sample app that’s about to be implemented. Even though we’ll pay some attention to create the app, we’ll mostly focus on the login implementation, and all the related stuff.

Note that if you download the sample project, make sure to correctly enter your app’s FacebookAppID, FacebookDisplayName string values and the URL Types array. Also, you must necessarily add the Facebook SDK framework to the project. For more information about all that, see the Initial Steps section of the tutorial.

Having said all that, let’s get started.

Creating the App

As always, the first step we have to do is to create a new sample project. Therefore, launch Xcode and do so. In the initial guide that appears, select the Single View Application as the project template, in the Applications category, under the iOS section.

Click Next to proceed. In the second step of the guide, in the Product Name field set the ManualFBLogin as the project’s name. Also, make sure that in the Devices drop down menu, the iPhone option is selected.

Click Next, and in the third and last step of the guide select a directory to save the project and then click on the Create button.

Initial Steps

This part is very crucial, as it involves the necessary setup needed to be done in both Facebook developers website and Xcode project before writing even a single line of code. In the previous tutorial regarding the Facebook login, I presented in details all the actions you should take, so go in the Preparing the Environment section and follow everything described there step by step. Here’s a summary of what you should do:

1. Create a new app record on the Facebook developers website.
2. Fill in all the necessary fields, and correctly copy the app’s bundle ID.
3. Add the Facebook SDK framework to the project.
4. In the .plist file of the project add all the needed keys and the respective values properly.

When you are ready with all the above, you can return here and continue with this tutorial. Don’t skip this step.

Interface Setup

Our goal here is to configure the interface by adding all the necessary subviews to the View Controller scene, and by declaring and connecting all the respective IBOutlet properties. We will work in the Interface Builder, so click on the Main.storyboard file to let it appear.

The following screenshot demonstrates what the final outcome of our work here will be.

The subviews we must add to the interface are the next ones:

• An image view to display the user’s profile picture.
• A label to show the user’s full name (first and last name).
• A label to show the user’s e-mail address.
• A label centered in the view that will display the status.
• An activity indicator view that will animate when the app is opening an existing session.
• A button at the bottom of the view, that will be used to log in and out.

As you notice, the login button is fully customized and it has nothing to do with the login view, the pre-made login button of the Facebook SDK.

Let’s start adding all the subviews one by one and setting all the appropriate attributes of them. For each subview described below, find the appropriate object in the Object Library and drag and drop it in the default view.

UIImageView

• Frame: X=20, Y=60, Width=63, Height=63

UILabel

• Frame: X=91, Y=60, Width=209, Height=63
• Text: None or Fullname
• Text Color: White
• Font: System Bold, 15.0
• Text Alignment: Center
• Lines: 5
• Line Break: Word Wrap

UILabel

• Frame: X=20, Y=148, Width=280, Height=21
• Text: None or E-mail
• Text Color: White
• Font: System Bold, 15.0
• Text Alignment: Center

UILabel

• Frame: X=20, Y=273, Width=280, Height=21
• Text: You are not logged in.
• Text Color: White
• Font: System Bold, 17.0
• Text Alignment: Center

UIActivityIndicator

• Frame: X=150, Y=302, Width=20, Height=20
• Style: White

UIButton

• Frame: X=0, Y=508, Width=320, Height=60
• Title: Login
• Text Color: White
• Font: System Bold, 15.0
• Background Color: R=255, G=128, B=0

Finally, set the view’s background color to R=59, G=89, B=152.

Your scene should now look like the screenshot illustrated at the beginning of this part.

Now that all the necessary subviews have been added to the view, it’s time to declare some IBOutlet properties and then connect them to these subviews. Open the ViewController.h file and add the next lines:

@interface ViewController : UIViewController

@property (weak, nonatomic) IBOutlet UIButton *btnToggleLoginState;

@property (weak, nonatomic) IBOutlet UIImageView *imgProfilePicture;

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

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

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

@property (weak, nonatomic) IBOutlet UIActivityIndicatorView *activityIndicator;


@end

The name of each property clearly declares its purpose. Further than the above, let’s also declare an IBAction method that we’ll use to login and logout. Add the next line right after the last property declaration:

- (IBAction)toggleLoginState:(id)sender;

Finally, head back to the Main.storyboard file, and connect the IBOutlet properties to the appropriate subviews. Here are the matches:

• The btnToggleLoginState property must be connected to the login button at the bottom.
• The imgProfilePicture property must be connected to the image view.
• The lblFullname property must be connected to the label next to the image view.
• The lblEmail property must be connected to the e-mail label, right under the image view.
• The lblStatus property must be connected to the status label to the center of the view.
• The activityIndicator property must be connected to the activity indicator view.

Here is a figure illustrating a property connection:

Additional In-Code Configuration

Having finished with the interface configuration, it’s time to move on to code. Before we dive into the heart of the topic though, we will perform some code-level setup that will determine the initial state of the app. Note that what we’ll do here is not required for the Facebook SDK to work. However it will help you make your project similar to the sample in case you develop following this tutorial step by step. So, here’s in short the most important tasks we’ll do:

• We will create a private method to set the hidden state of the subviews.
• We will add the necessary code needed to make the image view rounded.
• We will change the status bar style, making it have a light color.

Let’s begin with the easy one. Open the ViewController.m file, and in the viewDidLoad method add the next line:

[[UIApplication sharedApplication] setStatusBarStyle:UIStatusBarStyleLightContent];

This will turn the dark status bar into a light one.

Next let’s make the image view rounded, with a white border around it. In order to do that, we must access the CALayer layer property of it, and set three specific properties of the layer object. However the CALayer class is not part of the UIKit framework, therefore we must import the QuartzCore framework. In the top of the file add the next line:

#import 

The following four lines make the image view rounded, with a white border and 1px thick. Make sure to add them in the viewDidLoad method.

self.imgProfilePicture.layer.masksToBounds = YES;
self.imgProfilePicture.layer.cornerRadius = 30.0;
self.imgProfilePicture.layer.borderColor = [UIColor whiteColor].CGColor;
self.imgProfilePicture.layer.borderWidth = 1.0;

Now, let’s create a private method that will enable us to hide and show all the user info related subviews, depending on whether the user is logged in or not. At first, we must declare it in the private class section:

@interface ViewController ()

-(void)hideUserInfo:(BOOL)shouldHide;

@end

The shouldHide parameter flag will specify if the hidden property of the following subviews will be YES or NO. The method definition:

-(void)hideUserInfo:(BOOL)shouldHide{
    self.imgProfilePicture.hidden = shouldHide;
    self.lblFullname.hidden = shouldHide;
    self.lblTotalFriends.hidden = shouldHide;
}

Initially, we want all of the above subviews to be hidden. Later, when the connected state will be determined using the Facebook SDK, they’ll become visible if needed. So, let’s go to the viewDidLoad method and make a call to this method:

[self hideUserInfo:YES];

Besides than making those subviews hidden, it’s necessary to hide the activity indicator as well. We wouldn’t like the spinner appear with no reason. So, right below the above method call, add the next line:

self.activityIndicator.hidden = YES;

Note that the activity indicator will be handled separately from the rest of the subviews. The same applies to the status label.

Finally, let’s declare and instantiate an AppDelegate property, which we are going to use later during the implementation. Firstly, import the AppDelegate.h header file:

#import "AppDelegate.h"

Next, go to the private class section and add a property declaration as follows:

@property (nonatomic, strong) AppDelegate *appDelegate;

Lastly, in the viewDidLoad method, instantiate it:

self.appDelegate = (AppDelegate *)[[UIApplication sharedApplication] delegate];

Now we are ready to focus on the login implementation.

Logging In

The Facebook SDK contains a great number of libraries and classes. Among them, there is one class that is responsible for handling sessions, therefore its job is to handle the login process as well. That class is named FBSession, and it’s the one we need in order to achieve our goal.

The FBSession class implements the next method:

openActiveSessionWithReadPermissions:allowLoginUI:completionHandler:

With this one the login process is started. Let’s take a quick look at its parameters:

• openActiveSessionWithReadPermissions: The read permissions that are required by the app are provided here. For your knowledge, it’s not necessary to request for all permissions at once, as the more they are, the less possible is for the user to authorize and use the app. Additional permissions can be asked during the app execution. There are publish permissions too that can be requested along the way, but we don’t care about any of them right now. In this example, we will ask for the public_profile and the email permissions. You can find a full reference about permissions here.
• allowLoginUI: This parameter accepts a YES or NO value. If YES, then it shows either the Facebook app (if installed) or Safari to enter credentials if needed, and then to authorize the app.
• completionHandler: The completion handler block is called when the login process has finished. It returns three parameters: A session (FBSession) object, the session state value, and an error object in case it occurs any. We’ll talk more about the session and its various states in the next section of the tutorial.

Let’s start working now, and we’ll discuss every detail along the way. The “entry” point that we’ll begin from, is the toggleLoginState: IBAction method we had previously declared. Using this method, we’ll initiate both the login and the logout operations. The first thing we have to consider, is to check whether there is an open session or not. In case there isn’t any, then we’ll use the method described above to login. However, prior to implementation, make sure to import the Facebook framework at the top of the ViewController.m file:

#import 

Then, let’s see the initial implementation of the IBAction method:

- (IBAction)toggleLoginState:(id)sender {
    if ([FBSession activeSession].state != FBSessionStateOpen &&
        [FBSession activeSession].state != FBSessionStateOpenTokenExtended) {

    }
    else{

    }

}

A couple of observations here:

• The current session, also named active session, is accessed just like this: [FBSession activeSession].
• Using the state property of the active session, we determine if there is an open session or not. The two open session states are shown above.

Now, instead of directly calling the openActiveSessionWithReadPermissions:allowLoginUI:completionHandler: method of the FBSession class, we’ll make a small detour. We’ll implement a public method in the AppDelegate class, and in there we’ll make the call. That might seem strange to you at the moment, but I have two specific reasons to do that:

1. Later on, we’ll have to use the openActiveSessionWithReadPermissions:allowLoginUI:completionHandler: method again to open a stored session, and it wouldn’t be a good idea to write the same code twice.
2. It is a more general solution that can be used in larger projects.

Having said that, open the AppDelegate.h file, and firstly import the Facebook framework:

#import 

Then add the next method declaration:

@interface AppDelegate : UIResponder 

@property (strong, nonatomic) UIWindow *window;


-(void)openActiveSessionWithPermissions:(NSArray *)permissions allowLoginUI:(BOOL)allowLoginUI;

@end

The parameters we’ll provide to the openActiveSessionWithPermissions:allowLoginUI: custom method will be passed to the openActiveSessionWithReadPermissions:allowLoginUI:completionHandler: of the FBSession class. What follows next is the method’s definition, but what are we going to do there?

Well, the answer lies to the completion handler of the openActiveSessionWithReadPermissions:allowLoginUI:completionHandler: method, where we must handle the various session states. In our case, after the user has logged in, we must update the UI and show the user’s info. The same should happen later on, when we’ll open an existing session on a subsequent app launch. However, we can’t access the ViewController‘s interface through the AppDelegate class directly. The simplest solution would be to inform the ViewController when the login/session opening process is over, and perform in that class all the session handling. A simple way to do that is using a notification. Indeed, we’ll post a notification when the completion handler will be called, and along with it we’ll post the completion handler’s results (session, session state, error).

So, speaking with code this time, go to the AppDelegate.m file to define the public method. Here it is:

-(void)openActiveSessionWithPermissions:(NSArray *)permissions allowLoginUI:(BOOL)allowLoginUI{    
    [FBSession openActiveSessionWithReadPermissions:permissions
                                       allowLoginUI:allowLoginUI
                                  completionHandler:^(FBSession *session, FBSessionState status, NSError *error) {

                                      // Create a NSDictionary object and set the parameter values.
                                      NSDictionary *sessionStateInfo = [[NSDictionary alloc] initWithObjectsAndKeys:
                                                                        session, @"session",
                                                                        [NSNumber numberWithInteger:status], @"state",
                                                                        error, @"error",
                                                                        nil];

                                      // Create a new notification, add the sessionStateInfo dictionary to it and post it.
                                      [[NSNotificationCenter defaultCenter] postNotificationName:@"SessionStateChangeNotification"
                                                                                          object:nil
                                                                                        userInfo:sessionStateInfo];

                                  }];
}

You see that we initialize a NSDictionary object and we set all the values returned by the completion handler to it. Then, a new NSNotification object is posted, using the custom name SessionStateChangeNotification and the dictionary created right before.

Now, back at the toggleLoginState: IBAction method in the ViewController.m file, let’s make a call to the above method:

- (IBAction)toggleLoginState:(id)sender {
    if ([FBSession activeSession].state != FBSessionStateOpen &&
        [FBSession activeSession].state != FBSessionStateOpenTokenExtended) {

        [self.appDelegate openActiveSessionWithPermissions:@[@"public_profile", @"email"] allowLoginUI:YES];
    }
    else{

    }

}

To recap, when the user taps on the Login custom button, the openActiveSessionWithPermissions:allowLoginUI: public method of the AppDelegate is first called, which invokes in turn the openActiveSessionWithReadPermissions:allowLoginUI:completionHandler: of the FBSession class. Once the whole login process is over, we inform the ViewController using a notification, where we’ll handle the various session states in a while.

Before we reach the end of this section is necessary to perform a couple more steps: The first is to implement an application delegate method, the next one:

-(BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{    
    return [FBAppCall handleOpenURL:url sourceApplication:sourceApplication];
}

This one is called after the login credentials entry and app authorization have finished in Facebook app or Safari. The [FBAppCall handleOpenURL:url sourceApplication:sourceApplication] manages the results of all the actions taken outside the app (successful login/authorization or cancelation), and properly directs the login flow back in our app again.

The second step is to take our measures in case the user leaves the app while the login dialog is visible either in Facebook app or in Safari. In such a case, it’s necessary to use the Facebook framework for doing some cleanup and removing any unfinished session processes. Thankfully this is easy and it takes only a single line. Go to the applicationDidBecomeActive: of the application delegate, and add the next one:

- (void)applicationDidBecomeActive:(UIApplication *)application
{
    // Restart any tasks that were paused (or not yet started) while the application was inactive. If the application was previously in the background, optionally refresh the user interface.
    [FBAppCall handleDidBecomeActive];
}

The handleDidBecomeActive method of the FBAppCall class will check for an unfinished login process at the next app launch, and it will clear all the unnecessary “leftovers”, if any found.

Handling Session States

Posting the notification after a finished login process is an important step, but it consists only of the half work that must be done. The other half regards two things: To observe for the notification and to handle the session states.

Let’s begin by observing for the notification. Open the ViewController.m file, and head to the viewDidLoad method. In there, add the following code snippet:

[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleFBSessionStateChangeWithNotification:) name:@"SessionStateChangeNotification" object:nil];

With that statement, we force our class to observe for the notification specified by the given name, and when it arrives we will call the handleFBSessionStateChangeWithNotification: method. This is a private method that we are about to implement right now.

Initially, go to the private class section and declare it:

@interface ViewController ()

-(void)handleFBSessionStateChangeWithNotification:(NSNotification *)notification;

@end

In its definition we’ll handle the session states we are interested in. These are:

• FBSessionStateOpen: When a session is open.
• FBSessionStateClosed: When a session is closed.
• FBSessionStateClosedLoginFailed: When the user cancels the login /authorization process.

Actually, here is what we are going to do:

1. From the notification parameter object, we’ll extract the dictionary.
2. We’ll assign to local variables the session state value and the error object which we’ll take from the dictionary.
3. We’ll show the appropriate status message, along with the activity indicator.
4. If no error occurred, then if the session is open we’ll make a call to Facebook Graph API to get all the info we want. If the session is closed or failed, we’ll update the UI.
5. If an error occurred, we’ll output the error description and perform any UI-related tasks.

The next code fragment contains all these:

-(void)handleFBSessionStateChangeWithNotification:(NSNotification *)notification{
    // Get the session, state and error values from the notification's userInfo dictionary.
    NSDictionary *userInfo = [notification userInfo];

    FBSessionState sessionState = [[userInfo objectForKey:@"state"] integerValue];
    NSError *error = [userInfo objectForKey:@"error"];

    self.lblStatus.text = @"Logging you in..."
    [self.activityIndicator startAnimating];
    self.activityIndicator.hidden = NO;

    // Handle the session state.
    // Usually, the only interesting states are the opened session, the closed session and the failed login.
    if (!error) {
        // In case that there's not any error, then check if the session opened or closed.
        if (sessionState == FBSessionStateOpen) {
            // The session is open. Get the user information and update the UI.

            [self.btnToggleLoginState setTitle:@"Logout" forState:UIControlStateNormal];

        }
        else if (sessionState == FBSessionStateClosed || sessionState == FBSessionStateClosedLoginFailed){
            // A session was closed or the login was failed or canceled. Update the UI accordingly.            
            [self.btnToggleLoginState setTitle:@"Login" forState:UIControlStateNormal];            
            self.lblStatus.text = @"You are not logged in."
            self.activityIndicator.hidden = YES;
        }
    }
    else{
        // In case an error has occured, then just log the error and update the UI accordingly.
        NSLog(@"Error: %@", [error localizedDescription]);

        [self hideUserInfo:YES];        
        [self.btnToggleLoginState setTitle:@"Login" forState:UIControlStateNormal];

    }
}

If you look closely at the code, you’ll notice that we’ve handled everything we care about, but we didn’t get the user’s info yet. That’s something we’ll do right next, as I’d like us to focus our attention a bit more on that.

Getting User Info

Summarizing what we’ve done so far, I’d say that the most important steps we have managed to complete are the login process initiation and the session state handling. What we haven’t still done, is to get the user’s information after a successful login or after having loaded an existing, and display it on-screen.

Getting user’s data is easy. It takes only a call to the startWithGraphPath:parameters:HTTPMethod:completionHandler: method of the FBRequestConnection class. As you conclude from the method’s name, it makes a HTTP request to the appropriate API and sends all the provided parameters, which are given as a dictionary object. This method is a general one and can be used for several kinds of requests.

Back to our sample app now, let me specify the kind of info we’ll ask for the connected user. We’re going to get the first name, the last name, the e-mail address and the profile picture URL, which we’ll then use for showing the user’s image on the view. The dictionary object, and according to the Facebook Graph API, is expressed as follows:

@{@"fields": @"first_name, last_name, picture.type(normal), email"}

Notice that for the profile picture we use the picture.type(normal) value, asking from Facebook to return the normal size picture. There are four picture types that can be used:

1. Small
2. Normal
3. Large
4. Square

The completion handler of the startWithGraphPath:parameters:HTTPMethod:completionHandler: method contains three parameters:

1. A FBRequestConnection object. We won’t need it here.
2. An id object that contains the actual data. In our case, this is going to be a NSDictionary object.
3. An error pointer.

If no error occurred during the request, then we’ll get the user data from the returned dictionary and we’ll assign it as a value to the appropriate subview. Also, we’ll get the picture from the returned URL, and after all UI controls have taken their values, we’ll just unhide them. In case of an error, we’ll only output its description.

In the next code fragment it’s given the handleFBSessionStateChangeWithNotification: method implementation once again. However, this time contains the call to the startWithGraphPath:parameters:HTTPMethod:completionHandler: method in the case of an open session.

-(void)handleFBSessionStateChangeWithNotification:(NSNotification *)notification{
    // Get the session, state and error values from the notification's userInfo dictionary.
    NSDictionary *userInfo = [notification userInfo];

    FBSessionState sessionState = [[userInfo objectForKey:@"state"] integerValue];
    NSError *error = [userInfo objectForKey:@"error"];

    self.lblStatus.text = @"Logging you in..."
    [self.activityIndicator startAnimating];
    self.activityIndicator.hidden = NO;

    // Handle the session state.
    // Usually, the only interesting states are the opened session, the closed session and the failed login.
    if (!error) {
        // In case that there's not any error, then check if the session opened or closed.
        if (sessionState == FBSessionStateOpen) {
            // The session is open. Get the user information and update the UI.            
            [FBRequestConnection startWithGraphPath:@"me"
                                         parameters:@{@"fields": @"first_name, last_name, picture.type(normal), email"}
                                         HTTPMethod:@"GET"
                                  completionHandler:^(FBRequestConnection *connection, id result, NSError *error) {
                                      if (!error) {
                                          // Set the use full name.
                                          self.lblFullname.text = [NSString stringWithFormat:@"%@ %@",
                                                                   [result objectForKey:@"first_name"],
                                                                   [result objectForKey:@"last_name"]
                                                                   ];

                                          // Set the e-mail address.
                                          self.lblEmail.text = [result objectForKey:@"email"];

                                          // Get the user's profile picture.
                                          NSURL *pictureURL = [NSURL URLWithString:[[[result objectForKey:@"picture"] objectForKey:@"data"] objectForKey:@"url"]];
                                          self.imgProfilePicture.image = [UIImage imageWithData:[NSData dataWithContentsOfURL:pictureURL]];

                                          // Make the user info visible.
                                          [self hideUserInfo:NO];

                                          // Stop the activity indicator from animating and hide the status label.
                                          self.lblStatus.hidden = YES;
                                          [self.activityIndicator stopAnimating];
                                          self.activityIndicator.hidden = YES;
                                      }
                                      else{
                                          NSLog(@"%@", [error localizedDescription]);
                                      }
                                  }];

            [self.btnToggleLoginState setTitle:@"Logout" forState:UIControlStateNormal];
        }
        else if (sessionState == FBSessionStateClosed || sessionState == FBSessionStateClosedLoginFailed){
            // A session was closed or the login was failed. Update the UI accordingly.
            [self.btnToggleLoginState setTitle:@"Login" forState:UIControlStateNormal];
            self.lblStatus.text = @"You are not logged in."
            self.activityIndicator.hidden = YES;
        }
    }
    else{
        // In case an error has occurred, then just log the error and update the UI accordingly.
        NSLog(@"Error: %@", [error localizedDescription]);        
        [self hideUserInfo:YES];        
        [self.btnToggleLoginState setTitle:@"Login" forState:UIControlStateNormal];

    }
}

If you add a NSLog command to the above completion handler and print the result object, then you’ll get something like the next one:

2014-05-25 11:39:14.573 ManualFBLogin[748:90b] {
    email = "gabriel_dqhaczs_tester@tfbnw.net"
    "first_name" = Gabriel;
    id = 1377148289239707;
    "last_name" = Tester;
    picture =     {
        data =         {
            "is_silhouette" = 0;
            url = "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-xpf1/t1.0-1/s100x100/10390960_1392345714386631_6289945774589507432_s.jpg"
        };
    };
}

As you see, the picture object is a dictionary which in turn contains the data dictionary, and that’s the one containing the picture data we want. Based on that, it’s easy to understand how the NSURL object in the above method is formed:

NSURL *pictureURL = [NSURL URLWithString:[[[result objectForKey:@"picture"] objectForKey:@"data"] objectForKey:@"url"]];

Before we consider our work in this section done, I must say that using the startWithGraphPath:parameters:HTTPMethod:completionHandler: method is not the only way to get the user’s public info. Actually, there’s a method dedicated to that, the startForMeWithCompletionHandler:, and it’s part of the FBRequestConnection class. It has a disadvantage though, as it doesn’t return the URL of the profile picture and that’s why we didn’t use it in the first place.

If you wish so, feel free to make a call to that method and print to the debugger the results it brings back. Make sure to add it in the open session case, right before or after the startWithGraphPath:parameters:HTTPMethod:completionHandler: call. Here’s how you should invoke it:

[FBRequestConnection startForMeWithCompletionHandler:^(FBRequestConnection *connection, id result, NSError *error) {

                if (!error) {
                    NSLog(@"%@", result);
                }

            }];

This will output to the debugger something similar to this:

{
    email = "gabriel_dqhaczs_tester@tfbnw.net"
    "first_name" = Gabriel;
    gender = male;
    id = 1377148289239707;
    "last_name" = Tester;
    link = "https://www.facebook.com/app_scoped_user_id/1377148289239707/"
    locale = "en_US"
    name = "Gabriel Tester"
    timezone = 3;
    "updated_time" = "2014-05-21T18:49:16+0000"
    verified = 0;
}

Using this method just like that provides a nice way to find out what the public info regarding the user is, and what the names of the relevant fields are.

Now it’s a good time to run the app for first time. Initially, tap on the login button to get connected:

Provide your credentials and authorize the app:

If everything runs normally, then you’ll see your info appearing in the app, once you get back to it.

Opening a Session

If you try to run the app twice, you’ll notice that even though you’ve logged in the first time, you seem to be logged out upon the second launch. Actually, you are logged in indeed, but for the time being the app doesn’t know that. Fixing that situation is easy, but before we do so, let’s see some more details.

Every time that you successfully login with Facebook, the Facebook API returns some info regarding the connection, and saves it persistently. The most important piece of information contained is the access token that defines the session state and allows you to make requests without additional authorization to be needed upon subsequent app launches. Along with that token, its expiration date and some other stuff are included as well. The truth is that you don’t need to be aware of all these, as the Facebook SDK handles it behind the scenes. However,it is always good to know where everything is stored, so you can manually check if the proper info has been returned when debugging.

All the session-related info is stored into a .plist file, which you can find in a path similar to this (make sure that you have the hidden files visible):

/Users/gabriel/Library/Application Support/iPhone Simulator/7.1/Applications/A62A3F77-6A8C-477D-96FE-C32FB23B166B/Library/Preferences

The file of our app is named com.Your_Company_Name.ManualFBLogin.plist, and if you open it you can see if the token info is really there. Note that you shouldn’t edit it, otherwise expect something bad to happen in the app.

Having said all the above, let’s focus on our app again. As I said, for the time being the app doesn’t know if you are logged in or not, therefore will present you the default, logged out state on a subsequent launch. The goal is to make it read the above file in order to determine the connected state and then open the existing session. This should be done when the app is launched, and a good place to do so would be the application:didFinishLaunchingWithOptions: method of the application delegate. However, keep in mind that when the session state changes, we want to update our UI, and the problem that arises here is that this method is called before the view controller is loaded. That means that even if we load and open the session, the view controller won’t be ready soon enough to observe for the notification that will be posted upon a session state change, so the UI won’t be refreshed.

The solution in our case to load and open the session in the applicationDidBecomeActive: method of the AppDelegate class. If you remember, in a previous section of this tutorial we had added the next line in that method:

[FBAppCall handleDidBecomeActive];

Now, we must modify once again that method. In the next code segment is presented the code that must be added in order to properly open a saved session:

- (void)applicationDidBecomeActive:(UIApplication *)application
{
    // Restart any tasks that were paused (or not yet started) while the application was inactive. If the application was previously in the background, optionally refresh the user interface.

    if ([FBSession activeSession].state == FBSessionStateCreatedTokenLoaded) {
        [self openActiveSessionWithPermissions:nil allowLoginUI:NO];
    }

    [FBAppCall handleDidBecomeActive];
}

Initially, the Facebook SDK checks if there’s a stored access token. If so, then we call the openActiveSessionWithPermissions:allowLoginUI: public method we had created previously, providing no permissions and not allowing the login UI to appear. That way, the app loads from the .plist file the saved session, and then posts the notification. The notification is received by the ViewController class, and ultimately the session is properly handled. If a valid access token exists, and if the session normally opens, then our app requests the user’s info from Facebook every time the app launches.

If you add the above few lines and you run the app again, you’ll see that this time you won’t seem to be logged out.

Before closing, there are three things I’d like to mention:

1. The option to open the session in the applicationDidBecomeActive: is not a rule. I just chose to do so in this project, so the session opening works flawlessly with the custom notification posting and the session state handling. In your projects you could either choose this way, or open the session anywhere that best serves you.
2. This is a sample project, so every time the app launches we request the user’s info from Facebook. In a real-world app though, and depending on the security level of your app, you could store the user’s info locally, and make requests to update it only when that’s necessary.
3. In the beginning of this section I showed you where the access token along with the rest of the session info is saved to an app. However, Facebook allows to use a custom strategy for storing the session and managing all the procedures that deal with it (such as opening or loading it). That’s something out of the scope of this tutorial, so I won’t get into any details at all. I believe that you should be aware of that, so if you’d like to learn more you just have to visit the official Facebook documentation.

Logging Out

Everything is ready, apart from one thing. We still haven’t implemented the logout functionality, and that’s necessary for having a complete login mechanism.

Logging out is literally a matter of a single line of code. If you recall, in the toggleLoginState: IBAction method we have two cases: The first one where no open session exists and the user should login, and the opposite case (the else case), where the user is already logged in and now should log out.

In the next code fragment you are given the whole IBAction method, including the logout functionality. As you’ll see, we also update the UI accordingly.

- (IBAction)toggleLoginState:(id)sender {
    if ([FBSession activeSession].state != FBSessionStateOpen &&
        [FBSession activeSession].state != FBSessionStateOpenTokenExtended) {

        [self.appDelegate openActiveSessionWithPermissions:@[@"public_profile", @"email"] allowLoginUI:YES];

    }
    else{
        // Close an existing session.
        [[FBSession activeSession] closeAndClearTokenInformation];

        // Update the UI.
        [self hideUserInfo:YES];
        self.lblStatus.hidden = NO;
        self.lblStatus.text = @"You are not logged in."
    }

}

Compile and Run the App

Reaching almost at the end of the tutorial, it’s hard to imagine that you haven’t still compiled and run the app. However, if you haven’t done so, then this is the right time to do it. Before you click on the Run button on Xcode, make sure that you have properly configured both Facebook account and Xcode, and you followed everything step by step described in the previous sections.

The next animated graphics illustrate the whole process of login/logout we implemented in this tutorial:

Summary

This tutorial, in combination with the previous one regarding the Facebook login view, gives you all the tools you need for logging in with Facebook. As you see, it’s not difficult to do so as long as you follow some specific rules. I should mention that no special reference to error handling was made. That was in purpose, as it would be out of my goals to discuss it here. There’s an extensive description about that topic in Facebook documentation, so I’d advise you to give it a reading. Lastly, as a final word I would suggest to always stay up-to-date regarding the changes in Facebook SDK, as there might be significant modifications from version to version. I hope you’ve been helped by this post, and as always, leave us your thoughts.

For your reference, you can download the complete Xcode project from here.

Integrating Facebook features into an app is nowadays a quite common task, and one of the most important steps in the integration process is the login functionality implementation. Logging in with Facebook not only allows you to attach a social characteristic into your app, but it can also be used as a login system instead of creating a custom one. By adding it you offer to users a familiar way to authenticate, considering that the majority of users use Facebook.

Facebook integration is natively supported since iOS 6, even though it’s still necessary to manually add the Facebook SDK into your projects. There are two ways provided by the SDK for logging in with Facebook. The first one consists of a relatively easy solution, as it uses a predefined login view which manages all the session and login related stuff. The second one is a more “heavy” approach as everything must be implemented and handled by the developer, but on the other hand the login process can be highly customized. The method that should be used into a project definitely depends on the app’s requirements. If the predefined, familiar Login with Facebook button fits to the application’s look and feel, then this should be the number #1 option. If further customization is needed, then the programmatic option is a one-way road.

In this tutorial we are going to see how to login with Facebook using the first way, so let’s talk a bit more about it. The login view, or programmatically speaking the FBLoginView class, provides a standard Facebook button to log in and log out from the app. The appearing position of the view can be specified, but neither its size or its title can be changed. Actually, the title is automatically set according to the logged in status at a given time. Behind the scenes, the class is responsible to carry out all the heavy work. It manages all the communication with Facebook, it handles the various session changes, it persistently stores the authentication token received from Facebook after a successful login, it checks for an existing token upon the application launch, and a lot more. Developers don’t have to deal with all that details, or even care about them. They are only required to add the login view to the appropriate view controller, define all the desired permissions and implement a few delegate methods to handle the login state changes.

The login with Facebook relies on the Single Sign-On (SSO) access control system, according to which users can access multiple applications having logged in just once and using the same session. If, for example, you have the Facebook app installed on your device and you have already logged in, then when you’ll use for first time another application that implements the login with Facebook feature you’ll see that you’re already connected and no credentials are required again. You’ll only need to authorize the app. The basic idea behind this, is the fact that a device (such as the iPhone) is personal, so users are not obliged to provide the login info repeatedly. There is a drawback though; when you log out from an app you actually just de-authorize its access to your account. You are not really disconnected from Facebook, so even if you expect so, no credentials will be asked the next time you’ll use the app. In that case, you have to explicitly logout using the Facebook app or through the iPhone/iPad settings.

By finishing this tutorial you’ll be able to login with Facebook and to use the method you will learn in your projects too. However, I would strongly advise you to read the official Facebook documentation regarding the login workflow and the Single Sign-On technology. Doing so will also help you to obtain a deep understanding on the current topic.

App Overview

Looking at the big picture of this tutorial, one could say that is separated in two major parts. The first one is dedicated to the preparation needed to be done both in Facebook and Xcode prior to any implementation. In this, we will see how to create an application record on Facebook, how to setup Xcode and add the Facebook SDK framework, and how to use information taken from the newly created Facebook record to the project. Once this necessary step is over, we will be devoted to the implementation. By implementing a sample project, we will see how the login view and the FBLoginClass work by logging in and out. Finally, we will implement all those needed delegate methods that will inform our app about the connection state, and we display specific user information on-screen.

The next figure gives you an idea of the final goal of this tutorial.

Notice that if you download the sample project, you must perform some preparatory steps before you run it. Specifically, you must firstly set your own Facebook app’s info in the project’s .plist file. Be sure to correctly enter your app’s FacebookAppID, FacebookDisplayName string values and the URL Types array. If you skip it, you won’t be able to try out the sample project. Also, you must necessarily to add the Facebook SDK framework to the project. To accomplish all these, follow the guidelines described in the Preparing the Environment section.

Project Creation

Let’s start working by launching Xcode and creating a new project for the sample application, as it’s shown in the next figure:

In the guide that appears, select the Single View Application in the Application category, under the iOS section. Click on the Next button to proceed. In the second step, enter the LoginSampleFB value in the Product Name field, and make sure that in the Devices drop down menu the iPhone option is selected.

Click on the Next button once again, and in the last step select a directory to save the project. Once you do so, click on the Create button and you are ready.

Preparing the Environment

Before using any Facebook SDK feature, it’s necessary to perform some prerequisite tasks. These include preparation on both the Facebook platform and the Xcode project, as well as adding the Facebook SDK framework on the app. Of course, you must have a Facebook account active. In case you don’t, then create one and then return here to continue.

For starters, open Safari or any other browser you use, and go to the Facebook Developers website. Click on the Log In link at the far right side of the screen, and in the next page enter your credentials.

After you have logged in, you will be probably guided to your Facebook home page. In this case, at the top bar, click on the most-right link with a down arrow image, and from the menu that will appear select the Manage Apps option.

Next, from the top menu again, click on the Apps and then on the Create a New App option. As I have already said, for the purpose of this tutorial we are going to create a sample application which you can delete later.

In the window that pops up, in the Display Name field enter the LoginSample value as the app’s name. Also, in the Category drop down menu select any category you want, just don’t leave it with its default value. As you see in the next figure, I set the Education value.

Click on the Create App button, and then enter the captcha code you see on your screen in the security check window. Once you’ve finished, the new app will be created and you’ll be guided to the app’s dashboard.

The next step is to enable the app login from iOS. Click on the Settings option in the left menu, and in the main area click on the +Add Platform big button.

In the new window, select the iOS platform. A new panel is appeared on the dashboard titled iOS. In the Bundle ID field, it’s very important to enter the exact same to the project’s Bundle Identifier value, otherwise the app users won’t be able to be authorized. So, go back to Xcode, click on the project target on the Project Navigator pane, and under the General tab copy the value of the Bundle Identifier field.

Return on the Facebook dashboard, and paste or type the Bundle Identifier in the Bundle ID field. Also, make sure to enable the Single Sign On toggle button. Finally, click on the Save Changes button and this step is ready. Don’t logout from the dashboard though, as we have not finished yet.

Next, visit this link, download the Facebook SDK for iOS and install the package following the instructions shown on-screen. By default, the package is extracted on the Documents directory of your user account on your computer. You can either leave it there, or move it to another directory. In this tutorial, I presume that the SDK resides in the ~/USER/Documents directory. Once you have finished with the package extraction, open the FacebookSDK directory, and then drag and drop the FacebookSDK.framework on Xcode, under the Frameworks group. In the modal window that Xcode presents, unselect the Copy items into destination group’s folder (if needed) checkbox, so the framework won’t be actually copied on the project, just a reference to it to be created. By doing so, when you download and extract a new version of the SDK your project will be automatically updated when you re-open it. Leave the rest of options as they are, and click on the Finish button.

There is one final step needed to be performed, and that is to add three new keys to the project’s .plist file. So, open it by clicking on the Supporting Files group in the Project Navigator and then on the FBLoginSample-Info.plist file. Add a new key named FacebookAppID, and as its value paste the App ID value which you can copy from the Facebook dashboard, at the top of it. Similarly, add the FacebookDisplayName key, and in its value paste the Display Name which you can also copy from the dashboard.

Finally, create a new key named URL Types, and set its type to array with one item only. Give it the URL Schemes title and make it an array too. In the one and only item that should be contained, set the app ID value you copied from the Facebook dashboard, prefixing it with the fb literal. The next figure illustrates all the three additions on the .plist file:

All steps described here are mandatory for every app that is supposed to integrate Facebook features.

Creating Test Users

During the development stage of an app, and especially when authentication is involved in it, it’s generally a bad habit to use your normal account to perform all the required testings. Thankfully, Facebook supports the creation and usage of fake, test users per app. These users can’t harm your account, and of course, they can be deleted at any time, usually after the app has been developed. You can create as many of them as you want, you can “baptize” them as you want or let Facebook compose random names, and you can assign to a test user other test users as friends. You can even login to a test user’s account if it was a normal user.

To create a test user (at least) for the sample app that we will implement here, go to the Facebook dashboard of the LoginSample app, and select the Roles option at the left menu.

In the main dashboard area, click at the Test Users link at the top of it, and then click on the Add button, as you see in this figure:

A small window is appeared, where you set the number of test users you want to add, as well as some other options. If you want to create just one user, leave everything as they are and simply click on the Create Test Users button.

You could skip the creation of a new test user in case Facebook adds one by default, named Open Graph Test User. Anyway, here is the list of test users as they are shown on my dashboard, where everything has been automatically created:

At the right of the test users there are some options, which you can use to rename them, login to their fake account or add friends. Feel free to use them and see what they are for.

Later on we are going to use the e-mail address of a test user to login with Facebook. As a last word, I would recommend to edit the test user you’re about to use and set a password, so you won’t encounter any problems during the login process.

Interface Setup

All the required preparation has been done, so we are now ready to proceed to implementation. As I have already said in the introduction, we are going to add a pre-made view, existing already built in the Facebook SDK. This view is based on a class named FBLoginView, and it has two advantages:

1. It automatically displays the log in/log out Facebook button depending on the connection state.
2. It handles all the session related stuff, connection states and basic data fetching under the hood.

From the developer’s point of view, using the login view consists of a two-step process in general. The first one includes all the necessary tasks needed to be done in order to display the view, and the second involves the implementation of some delegate methods for handling all changes been made on the login and session state.

In the default view of the ViewController class we are going to add various subviews, and the most of the will be used to display the user’s information after a successful login. Specifically, the most important subview that we will add is the login view, which actually is the login button. Further than that, we will use three UILabel objects to display:

• The current login status.
• The user’s name.
• The user’s e-mail address.

Finally, we will have one more UIView object to show the user’s profile image. When the user is logged out, the all labels and the profile picture view will be hidden, with just one exception; the login status label.

Let’s get started by opening the Main.storyboard file. Add the following subviews to the View Controller scene:

1. UIView
• Frame: X=60, Y=430, Width=200, Height=50
2. UILabel
• Frame: X=20, Y=32, Width=280, Height=21
• Text Alignment: Center
3. UIView
• Frame: X=85, Y=61, Width=150, Height=150
4. UILabel
• Frame: X=20, Y=219, Width=280, Height=21
• Text Alignment: Center
• Font: System Bold
5. UILabel
• Frame: X=20, Y=248, Width=280, Height=21
• Text Alignment: Center
• Font Size: 14.0

In order for the two UIView objects to properly work, we must modify their classes and set the Facebook-related ones. Specifically, for the UIView at the bottom of the interface (#1 in the above list), in the Class* field of the Custom Class** section in the Identity Inspector, we must set the FBLoginValue, as shown below:

For the profile image view, meaning the second UIView object (#3 in the list above), we must set the FBProfilePictureView as its class name:

Setting these custom classes to the above views is not enough to make them work as expected. One more touch is required, and that is to make a call to both of these classes in the application:didFinishLaunchingWithOptions: method of the AppDelegate class. However, we must import the Facebook SDK libraries to the class firstly, so open the AppDelegate.m file and add the next command at the top of it:

#import 

Now, go to the AppDelegate.m file and in the application:didFinishLaunchingWithOptions: delegate method add the next two lines:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Override point for customization after application launch.

    [FBLoginView class];
    [FBProfilePictureView class];

    return YES;
}

Now that the first contact with the Facebook SDK has been made, let’s create some IBOutlet properties for the subviews we added to the interface, and then we’ll make the connections. Open the ViewController.h file, and add the next property declarations:

@interface FirstViewController : UIViewController

property (weak, nonatomic) IBOutlet FBLoginView *loginButton;

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

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

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

@property (weak, nonatomic) IBOutlet FBProfilePictureView *profilePicture;

@end

Of course, you should import the Facebook SDK library here as well:

#import 

Note: It’s possible for Xcode to issue some errors, even when you import the above file. That’s probably caused because Xcode does not correctly “see” the path to the Facebook framework. There is a workaround for that:

1. Go to the project target and open the Build Settings tab.
2. Scroll down until you find the Search Paths section
3. Click on the Framework Search Paths key and press the Return key on your keyboard to edit the value.
4. You should see something similar to this: $(inherited) /Users/gabriel/Documents/FacebookSDK. Delete the $(inherited) term, and include the remaining string value in double quotes, just like it’s shown in the next figure:

Finally, go to the Main.storyboard file and connect all IBOutlet properties to the appropriate subviews. Specifically, be sure to match:

1. The loginButton property to the FBLoginView view at the bottom side of the scene.
2. The lblLoginStatus property to the first, top-most UILabel.
3. The lblUsername property to the second UILabel where the logged in user’s name will appear.
4. The profilePicture property to the FBProfilePictureView view.
5. The lblEmail property to the last UILabel object.

Logging In and Out

By simply doing all the previous preparation, the login view is ready to work. When the login button will be tapped, the user credentials must be given in order to get authenticated. This can take place in two ways: Either through the Safari app, or through the Facebook app if it is installed on your device (note that the Facebook app works only on a real device, not in the Simulator). Once the login info has been provided, our app must take the control again, but besides that, the Facebook SDK must handle and determine the login process.

Therefore, before we give a try to the app, we must add the necessary code that will do the above. First of all, open the AppDelegate.m file and add the following delegate method:

-(BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{

}

The iOS will call this method after the user has authorized the app through Safari of the Facebook app. In here we will add just one line to let Facebook SDK handle the login result and modify the login view accordingly. Behind the scenes, the authentication token received by Facebook will be persistently stored, and the session state will get changed.

In the next code fragment, you see the necessary code added in the above method that handles the login process:

-(BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{

    return [FBAppCall handleOpenURL:url
                  sourceApplication:sourceApplication];
}

Additionally, we must take care so all subviews to be hidden until the logged in state is determined, except for the login status label. They should become visible only after a successful login and after their values have been set, otherwise they must remain hidden. We’ll create a small private method to accomplish this. Open the ViewController.m file, and in the private class section add the next declaration:

@interface ViewController ()

-(void)toggleHiddenState:(BOOL)shouldHide;

@end

Next, define that method:

-(void)toggleHiddenState:(BOOL)shouldHide{
    self.lblUsername.hidden = shouldHide;
    self.lblEmail.hidden = shouldHide;
    self.profilePicture.hidden = shouldHide;
}

It’ obvious that the shouldHide parameter value defines the hidden state of the subviews. Now, let’s call it in the viewDidLoad method, so initially the subviews are hidden. Also, along with the call to this method, we will set the empty string as the login status label text value:

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view, typically from a nib.

    [self toggleHiddenState:YES];
    self.lblLoginStatus.text = @"";

}

It’s always necessary to specify the read permissions you want for your app when logging in with Facebook. The Facebook SDK uses by default the public_profile permissions, independently on whether you specify or not any. Using it, the user’s public info (such as name, profile picture, friends, etc) is returned. However, even though the SDK uses the public_profile automatically, it is recommended to specifically set it along with any other permissions you want to ask for. In this sample app we want to get the user’s e-mail address as well, therefore the email permission is required too.

Right next it’s shown the way you can use to specify the permissions you need. Note that you must add it to the viewDidLoad method:

self.loginButton.readPermissions = @[@"public_profile", @"email"];

As a footnote, in case you want permissions other than for the public profile, the user’s e-mail address and the friends list, or if you need post permissions, your app must be approved by Facebook before it goes live to the App Store. If it won’t be approved, the Facebook-related features won’t work when your app is live.

Build and run the app now for first time. Tap (or click) on the Login with Facebook button, and be prepared to enter your credentials. In a previous section of the tutorial we talked about test users, so I would advise you to use such an account in order to make your testings. When you’ll go back on the app, you will see that the login view title has changed to Log out. Nothing else happens yet, but that’s something we’ll fix next.

Note that if you test the app on a real device and you have the Facebook app installed, then in case you have logged in with Facebook through that app, you won’t be asked again to enter your credentials, just to authorize the app. That’s the meaning of the Single Sign-On after all.

If you try to log out, an action sheet asking for confirmation will appear, as shown below:

Handling States

If you have successfully logged in and logged out, then you see that the login view makes it really easy to get connected to Facebook. For the time being though, the only thing that gets changed is the button’s view, nothing else. In this section, we will add all those required delegate methods that will enable us to know if we are connected or not, and then display or hide the appropriate information.

There are four delegate methods that should be implemented in total. Before we add any of them, we must make our class, the ViewController, to conform to a certain protocol, the FBLoginViewDelegate. Open the ViewController.h file, and in the header line adopt the protocol, just like it’s shown below:

@interface ViewController : UIViewController 

Now, open the ViewController.m file, and before the implementation of the delegate methods, let’s make our class the delegate of the login view. Simply go to the viewDidLoad: method and add this line:

self.loginButton.delegate = self;

Let’s focus now on the delegate methods. The first one we’ll talk about, it is called when the user is logged in. Using it, we can change the hidden state of our subviews, and set the current login status value. Right next it’s shown its implementation:

-(void)loginViewShowingLoggedInUser:(FBLoginView *)loginView{
    self.lblLoginStatus.text = @"You are logged in.";

    [self toggleHiddenState:NO];
}

Two simple tasks are performed here: The appropriate message is set as the text of the status label, and the rest of the subviews are becoming visible.

Now that both the profile picture view and the username label can be shown when we have logged in, they must be assigned with values too. This will take place to another delegate method, which provides us with the info we want. That method contains a FBGraphUser object as parameter, which actually is a NSDictionary object, and it contains all the public info of the logged in user. Here is the implementation:

-(void)loginViewFetchedUserInfo:(FBLoginView *)loginView user:(id)user{
    NSLog(@"%@", user);
    self.profilePicture.profileID = user.id;
    self.lblUsername.text = user.name;
    self.lblEmail.text = [user objectForKey:@"email"];
}

I intentionally added a NSLog command in the above method, just to let you see the data contained in the user object. By assigning the id property as the profile ID in the profile picture view, the Facebook SDK downloads the appropriate picture and displays it. If no user picture has been specified, then the default image of the Facebook user will be used. Lastly, the user’s name and the e-mail address values are set to the appropriate labels.

With the above two delegate methods, we managed to handle case where the user has logged in. Now, we must deal with the log out. For this case, there’s another delegate method, in which we will simply change the status text on the status label and we will hide the rest of the subviews. Here it is:

-(void)loginViewShowingLoggedOutUser:(FBLoginView *)loginView{
    self.lblLoginStatus.text = @"You are logged out";

    [self toggleHiddenState:YES];
}

There is one delegate method remaining, and that is to handle any errors that may occur. In this sample, we won’t do any actual error handling, we’ll just display the error on the debugger. However, in a real application you should handle all errors according to your app’s requirements.

-(void)loginView:(FBLoginView *)loginView handleError:(NSError *)error{
    NSLog(@"%@", [error localizedDescription]);
}

With the above four methods implemented, you can test the app once again. This time, when you have logged in, you’ll see the user’s name, the profile picture and the e-mail address displayed on the view.

Summary

Login with Facebook consists of one of the best solutions when you need to add a SSO-oriented login system to your app. By performing some simple steps as described in this tutorial, you gain multiple advantages: You get rid of the hassle to create your own login and authentication mechanism, and you offer your users a familiar technology to work with. Featuring well-known experiences surely leads to more attractive apps, and more potential users. Social apps cover a big part of the available app spectrum, and knowing how to deal with Facebook login and Facebook technologies in general is almost mandatory. Closing, I hope this tutorial to be beneficial to all, and that you’ll add what you’ve learned here to your code toolbox.

For your reference, you can download the complete Xcode project from here. As always, leave me comment if you have any question or feedback.

All mobile applications, no matter what they are about, they have one common and obvious characteristic: They offer interaction, which means that they are not static, but require input or actions needed to be taken by users from time to time in order to function properly. One quite usual behavior, is the ability to provide ways that allow users to make choices or take decisions where it’s needed, and ultimately act that way on the applications’ data or functionalities. iOS SDK provides a pre-made action-taking view controller, the UIActionSheet.

Action sheets consist of a really convenient and fast way to display a bunch of options that the user should select from, and it is widely used in great number of applications. Its disadvantage though is that it adopts the iOS’s look and feel without being able to be graphically modified, therefore it might not fit to applications with customized GUI.

Beyond action sheets, another very important and cool tool designed especially for the iPad, is the UIPopoverController. A popover controller is actually a container which is used to display content on top of another content. What makes it unique is the fact that it can be displayed almost everywhere around the screen of the iPad, but usually it’s shown near to the button that caused its appearing with a nice arrow pointing to the button’s direction. iOS by default encloses action sheets in popover controllers on iPad, but they can also be manually created for custom content.

Before we begin working with those two view controllers, let’s do some more talking about them in order to get to know their basics, and then we’ll proceed on how to use them in projects. So, let me start by telling that both the UIActionSheet and UIPopoverController exist to serve the same purpose, and that is to provide a quick way for presenting content to the user. This content can be either a button-based menu (action sheet), or anything else originating from a view controller (popover controller). Undoubtably, they are both pretty useful tools, and everyone developing for iOS should master both of them. Their great difference lies to where each one is used, and that’s the essential fact you should be aware of: An action sheet can be used on any iOS device (iPhone, iPad), but a popover controller can be used only on iPad, as I have already said.

Focusing now a bit on the UIActionSheet, right next is shown a sample of it on iPhone (that’s an action sheet we’ll create next in this tutorial):

As you can see in the figure above, an action sheet can have three different kind of buttons: A destructive button displayed in red and usually used to highlight deletion actions, a cancel button that simply makes the action sheet to be dismissed, and a bunch of other normal buttons, whose number can vary depending on the provided options to the user. When an action sheet is presented, all of those buttons can be used, or just a combination of them, but surely the action sheet can’t be empty. We’ll see examples of that along our way in this tutorial.

When working on iPad, actions sheets are displayed embedded into popover controllers. From the developers’ point of view, no action is required for that, as the iOS automatically does it. However, it’s on the programmer’s hands to properly display the popover controller with the action sheet in it, and stay aligned to the Human Interface Guidelines. Further than that, keep in mind that the cancel button of the action sheet is not displayed on iPad, as tapping anywhere else but the action sheet is the same as tapping on the cancel button.

About the UIPopoverController now, the next figure illustrates a popover controller on iPad (again, this is a popover we’ll create in this tutorial later on):

If you have never worked with it, then it might sounds hard to make use of it. However, as you’ll ultimately find out, initializing and using popover controllers is just a matter of a couple of lines. Popovers are excellent tools, as they can show content almost anywhere you want around the screen. They are suitable for cases that user must interact in a quick fashion with a view controller, without losing from his eyes the current one. Besides that, the arrow pointing their origin is a beautiful visual effect, always attractive to the users.

If you feel you want to learn more theoretical stuff about action sheets or popover controllers, then visit Apple’s documentation and have an in-depth study. That’s something I definitely encourage you to do. However, now it is time to proceed and see how everything works in practice.

App Overview

Now that you have a taste of what we are going to work with in this tutorial, let’s take a glance at the sample application we are about to develop next. So, let me begin by saying that we will deal firstly with action sheets. We’ll see how they can be presented, how to customize the displayed options, and of course, how to handle the user response and actions. All that will be done for the iPhone device family initially, through simple and practical examples.

Next, we’ll see how action sheets work on iPad devices, and how they are displayed enclosed in popover controllers (UIPopoverController) automatically by the system. Actually, we will see how the examples implemented for the iPhone apply on iPad, and what differences may exist.

Finally, we’ll focus on the popover controller itself. We will programmatically initialize and display one, in which we’ll add the contents of a new view controller.

Everything will be presented in details, so if you are new to all these, be sure that you’ll definitely learn something when you reach the end of the tutorial. Having said all that, let’s get started.

App Creation

Let’s get started by creating the sample app of this tutorial. Launch Xcode and create a new project. In the first step of the guide that appears, select the Single View Application as the template of the app, in the Application category under the iOS section. Then click on the Next button.

In the second step, in the Product Name field set the ActionSheetDemo value. Then in the Devices drop down menu, select the Universal option so it works on both the iPhone and the iPad. Once you do so, click on the Next button again.

Finally, in the last step select a destination directory to save the project and click Create. It is now ready, so we can keep on going with the UIActionSheet demonstration.

Presenting a UIActionSheet

Now that there is a project to work on, let’s see how a UIActionSheet view controller can be displayed. Before doing so though, open the Main_iPhone.storyboard file by clicking on its name on the Project Navigator. Once the Interface Builder is appeared, add the following three UIButton objects, as described and shown below:

Button #1:
1. Title: Normal Action Sheet
2. Frame: X=81, Y=228, Width=159, Height=33

Button #2:
1. Title: Delete Confirmation Action Sheet
2. Frame: X=32, Y=269, Width=256, Height=33

Button #3:
1. Title: Colors Action Sheet
2. Frame: X=83, Y=310, Width=154, Height =33

Now, open the ViewController.h file, and declare the next three IBAction methods:

@interface ViewController : UIViewController

- (IBAction)showNormalActionSheet:(id)sender;

- (IBAction)showDeleteConfirmation:(id)sender;

- (IBAction)showColorsActionSheet:(id)sender;

@end

Then, return to the Interface Builder and connect each one to the appropriate button, matching the method names with the button titles. Get finished with that and then open the ViewController.m file to write some code.

Let’s begin by implementing the showNormalActionSheet: IBAction method, and let’s display our first action sheet. What you always have to do is to initialize a UIActionSheet object (either local or a class property) in the way that’s shown below:

 - (IBAction)showNormalActionSheet:(id)sender {

    UIActionSheet *actionSheet = [[UIActionSheet alloc] initWithTitle:@"What do you want to do with the file?"
                                                             delegate:self
                                                    cancelButtonTitle:@"Cancel"
                                               destructiveButtonTitle:@"Delete it"
                                                    otherButtonTitles:@"Copy", @"Move", @"Duplicate", nil];


}

As you may conclude from the above code, in this action sheet we hypothetically provide to the user some file handling options. Let’s talk a bit about the initialization method, which as you see it accepts a great number of parameters. The first one is a title that’s displayed on top of the action sheet with small letters, and usually is a prompt message or a question about the action that’s about to be taken. The second one is the delegate of the action sheet, which can be set to nil if you are not planning to implement any delegate method (something that’s really rare though), otherwise the self object is usually set. The cancelButtonTitle parameter accepts a desired title for the cancel button, which always is placed at the bottom of the action sheet, separately from the others, and as its name suggests, it simply forces the action sheet to be dismissed without any action performed. Next, the destructive button is a special button colored in red, and is used to indicate a critical action, such as a deletion. In the respective parameter you set its title. This button is always first in the buttons’ order. Finally, the otherButtonTitles parameter accepts a nil terminated string, and in here the titles of the rest buttons existing on the action sheet are set. All of the normal buttons are positioned between the destructive and the cancel button.

When initializing an action sheet, it’s not mandatory to have all kind of buttons if you don’t need them. To avoid a button’s appearance on the sheet, you simply set the nil value to the respective parameter and the button won’t appear. We’ll see that later.

Now, to make the action sheet appear when the button gets tapped, you need to add one more command right after the initialization:

- (IBAction)showNormalActionSheet:(id)sender {
    UIActionSheet *actionSheet = [[UIActionSheet alloc] initWithTitle:@"What do you want to do with the file?"
                                                             delegate:self
                                                    cancelButtonTitle:@"Cancel"
                                               destructiveButtonTitle:@"Delete it"
                                                    otherButtonTitles:@"Copy", @"Move", @"Duplicate", nil];

    [actionSheet showInView:self.view];
}

Before you test it, open the ViewController.h file and make our class conform to the UIActionSheetDelegate protocol. That’s necessary to fix the warning Xcode appears in the line where we declare self as the delegate of the action sheet. So, modify the interface header line as follows:

@interface ViewController : UIViewController 

Build and run the application now for first time. Click on the Normal Action Sheet button, and the action sheet will appear. Pretty nice, don’t you think? With just a couple of lines we managed to implement an option menu and present it to the user.

Tap on any button you want and the action sheet will disappear. Even though it gets dismissed, for the time being we are unable to handle the tapped button. Don’t worry about that, we’ll fix it later on.

Customizing UIActionSheet Options

In the previous example, we created our first action sheet and we saw how it looks like when all of the buttons are used. However, such an action sheet might not always be suitable for every case you may encounter, and then you’ll definitely need to adjust the displayed options only to those you desire. I already mentioned previously that you can skip a button’s appearance if you simply set the nil value to the respective parameter value, and in this part of the tutorial we’ll see a couple of such examples.

Let’s begin working with the second button we added to the view, titled Delete Confirmation Action Sheet. Let’s suppose that you have a table view full of contacts, and before deleting one you want to show a confirmation action sheet to the user. In that case, you would like to use a delete button to perform the actual deletion, and a cancel button just to dismiss it. This can be achieved easily, as long as you set to the otherButtonTitles parameter the nil value. The following IBAction implementation demonstrates exactly that (make sure you work on the ViewController.m file):

- (IBAction)showDeleteConfirmation:(id)sender {
    UIActionSheet *actionSheet = [[UIActionSheet alloc] initWithTitle:@"Really delete the selected contact?"
                                                             delegate:self
                                                    cancelButtonTitle:@"No, I changed my mind"
                                               destructiveButtonTitle:@"Yes, delete it"
                                                    otherButtonTitles:nil];

    [actionSheet showInView:self.view];
}

As you see, the title of the action sheet is in accordance to the current occasion. Further than that, you see that you can set any title you wish to both the delete and cancel buttons.

Now, run once again the application, and tap (or click on the Simulator) on the second button. Here’s you what you should see:

Let’s see now one more example. Let’s suppose you want to present an action sheet to let users select a color among five possible values, you don’t need of course to have a destructive button, and you don’t want to provide a cancel button too. In this case, you have to set the nil values to both the destructive and cancel button titles, and simply provide the nil terminated string with all the colors titles. The implementation of the next IBAction method shows just that:

- (IBAction)showColorsActionSheet:(id)sender {
    UIActionSheet *actionSheet = [[UIActionSheet alloc] initWithTitle:@"Pick a color:"
                                                             delegate:self
                                                    cancelButtonTitle:nil
                                               destructiveButtonTitle:nil
                                                    otherButtonTitles:@"Red", @"Green", @"Blue", @"Orange", @"Purple", nil];

    [actionSheet showInView:self.view];
}

If you run the application now, you’ll see that only simple buttons are displayed on the action sheet, while the destructive and cancel buttons have been omitted. Here’s a sample of what you should see on your screen when tapping on the third button:

Through these two examples it was made clear how you can use the provided kinds of buttons depending on your project’s needs. It’s amazingly easy to create a menu of options and show them to the user, make various button combinations, and as you’ll see right next, it’s very easy to handle the user response too. The only drawback is that you cannot modify the sheet’s visual style, and that can consist of a prohibitive reason for not using it to customized applications.

Handling Actions

The UIActionSheetDelegate protocol we previously adopted, provides a few delegate methods that can be used in order to fully control the user response to action sheets. In this section we are going to talk about all of them, and we’ll begin by the most commonly used one, the actionSheet:clickedButtonAtIndex:.

This method as you probably correctly guess, returns the index of the button that was tapped to an action sheet. You should always keep in mind that the index of the top most button is 0 (zero), and moving towards bottom the index gets increased by one. There will be times that you’ll want to get the title of the tapped button instead of its index. That’s easy to get, as the actionSheet parameter object supports a method named buttonTitleAtIndex:. Providing it simply with the tapped button index, you get the appropriate title. Also, in most of the times you’ll probably use a switch or an if structure in order to perform the appropriate action, depending on the user response.

When you have just one action sheet in your view controller, then it’s simple to handle it using this delegate method. However, when you have multiple action sheets just like here, then you must define in which one a button has been tapped. That can be achieved by setting a tag value to each action sheet. So, go to all three IBAction methods we previously implemented and set to each action sheet a tag value as shown below:

// showNormalActionSheet:
actionSheet.tag = 100;

// showDeleteConfirmation:
actionSheet.tag = 200;

// showColorsActionSheet:
actionSheet.tag = 300;

In the following implementation of the delegate method, we’ll show a message in the debugger, customized depending on the displayed action sheet. Also, we’ll log the tapped button index and its title:

-(void)actionSheet:(UIActionSheet *)actionSheet clickedButtonAtIndex:(NSInteger)buttonIndex{
    if (actionSheet.tag == 100) {
        NSLog(@"The Normal action sheet.");
    }
    else if (actionSheet.tag == 200){
        NSLog(@"The Delete confirmation action sheet.");
    }
    else{
        NSLog(@"The Color selection action sheet.");
    }

    NSLog(@"Index = %d - Title = %@", buttonIndex, [actionSheet buttonTitleAtIndex:buttonIndex]);
}

Test the app now. Depending on what action sheet you display and the button you tap, the respective message appears on the debugger.

Let’s go back to code, and let’s examine the rest of the delegate methods, which you may find useful in many situations during your programming life. The first one is the actionSheet:didDismissWithButtonIndex: method. This one works just like the previous one, but it gets called after the action sheet has been dismissed. The next code segment illustrates a simple use of it, where firstly we make sure that the dismissed action sheet’s tag value equals to 300, and then display the selected color name:

-(void)actionSheet:(UIActionSheet *)actionSheet didDismissWithButtonIndex:(NSInteger)buttonIndex{
    if (actionSheet.tag == 300) {
        NSLog(@"From didDismissWithButtonIndex - Selected Color: %@", [actionSheet buttonTitleAtIndex:buttonIndex]);
    }
}

Run the app once again, and tap on the third button. Select a color and look at your debugger. You’ll notice that the message from this method is logged with a small delay, and after the action sheet has disappeared.

Besides that method, there’s also the actionSheet:willDismissWithButtonIndex: one. On contrary to the above delegate method, this one is called before the action sheet gets dismissed. Implement it and add the same code as previously:

-(void)actionSheet:(UIActionSheet *)actionSheet willDismissWithButtonIndex:(NSInteger)buttonIndex{
    if (actionSheet.tag == 300) {
        NSLog(@"From willDismissWithButtonIndex - Selected Color: %@", [actionSheet buttonTitleAtIndex:buttonIndex]);
    }
}

Run the application again and watch your debugger. You’ll see that the message coming from this method is appeared before the action sheet disappears.

These are the delegate methods provided, but it’s almost certain that in 98% of cases the first one is what you’ll use.

Action Sheet on iPad

Up to this point, we’ve managed to learn the basic principles regarding the UIActionSheet, and the ways the user response can be handled. Also, our implementation was limited to iPhone-style devices only, as this is our primary device target when messing around with new stuff. However, now that theUIActionSheet essentials have become known, it’s important to see how action sheets should be treated when working on iPad devices, as things change a bit here.

If you ever developed for iPad, or if you are simply an iPad user, then you know that it contains a pretty nice view controller, not available on iPhone or iPod devices, the UIPopoverController. As I have already said in the introduction of the tutorial, the UIPopoverController is quite useful when it’s necessary to show contents next to a button, cell, or anything else that has triggered an action. iPad devices are suitable for using them, as the big screen leaves enough room to display them in various sizes.

So, going back to our previous talk, when an action sheet is necessary to be presented to an iPad, iOS encloses it into a UIPopoverController view. The really important clue here is that the cancel button does not appear on the action sheet, because the result of that button is the same to tapping out of the popover controller; both of those dismiss popover controller/action sheet without performing any task. The existence of the cancel button would be confusing for users, so Apple engineers designed it that way so it gets removed when the target device is an iPad.

Apart from the above, there are also differences on the way an action sheet is shown, programmatically speaking this time. Before getting into those details though, it would be more meaningful and rewarding to see everything in practice, so let me make a turn and guide you from another path.

On the Project Navigator pane, click on the Main_iPad.storyboard file to let the iPad interface appear in the Interface Builder. Add the three buttons we added on the iPhone interface here too, as my goal is to demonstrate how similar things are handled differently in both devices. The button details:

Button #1:
1. Title: Normal Action Sheet
2. Frame: X=313, Y=459, Width=142, Height=30

Button #2:
1. Title: Delete Confirmation Action Sheet
2. Frame: X=270, Y=497, Width=229, Height=33

Button #3:
1. Title: Colors Action Sheet
2. Frame: X=316, Y=535, Width=137, Height =30

Finish with the button preparation and then connect the existing IBAction methods to them appropriately. When you are ready, go to the ViewController.m file and in the implementation of the showNormalActionSheet: method. If you followed the steps in the previous sections of the tutorial, here’s what it should look like:

- (IBAction)showNormalActionSheet:(id)sender {
    UIActionSheet *actionSheet = [[UIActionSheet alloc] initWithTitle:@"What do you want to do with the file?"
                                                             delegate:self
                                                    cancelButtonTitle:@"Cancel"
                                               destructiveButtonTitle:@"Delete it"
                                                    otherButtonTitles:@"Copy", @"Move", @"Duplicate", nil];

    [actionSheet showInView:self.view];

    actionSheet.tag = 100;
}

Run the app, but make sure to either select an iPad simulator device, or connect a real device directly. You must be watching a view similar to the next one if you tap (or click) on the first button:

What you see is the default way an action sheet appears to an iPad, and as you notice the cancel button is missing. When tapping anywhere out of the popover view, you’ll see in the debugger the message from the actionSheet:clickedButtonAtIndex: method, just like if you were tapping on the cancel button.

The way the action sheet appears is not the best possible solution, as the purpose of the popover controller is to be displayed next to the control that triggers its appearance, and even more, an arrow pointing to that control should be visible too. Very rarely, almost never one could say, an action sheet appears just like that in the centre of the screen.

So, what can we do to overcome this? Well, only two steps are required. The first one is to define whether the device the app works is an iPhone/iPod or an iPad. In the second case, we just have to change the way the action sheet appears on the screen. In action now, go to the IBAction method, and right below the initialization of the action sheet, add the next condition:

if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) {
        // In this case the device is an iPad.

    }
    else{
        // In this case the device is an iPhone/iPod Touch.
        [actionSheet showInView:self.view];
    }

With the UI_USER_INTERFACE_IDIOM() macro you can check if you have an iPad or iPhone user interface, and ultimately follow the one or another path. In the above code, we use the else case to present the action sheet normally to an iPhone/iPod Touch device.

If you run the app now, you’ll find out that when tapping on the first button nothing happens, and that’s totally normal as there’s nothing to be executed in the if clause. Return to the code, and add in the if body the next line:

[actionSheet showFromRect:[(UIButton *)sender frame] inView:self.view animated:YES];

This action sheet method accepts three parameters: The frame to be shown from, the view that it will be shown to, and a flag indicating an animating appearance or not. In our case, we want the popover controller of the action sheet to originate from the button that triggers its display, so in the showFromRect parameter we specify the frame of the sender button. The rest is easy. Now run the app again and tap on the first button. The result is the proper and desired one:

Below you are given all three IBAction methods modified appropriately, so the properly work for all devices:

- (IBAction)showNormalActionSheet:(id)sender {
    UIActionSheet *actionSheet = [[UIActionSheet alloc] initWithTitle:@"What do you want to do with the file?"
                                                             delegate:self
                                                    cancelButtonTitle:@"Cancel"
                                               destructiveButtonTitle:@"Delete it"
                                                    otherButtonTitles:@"Copy", @"Move", @"Duplicate", nil];

    if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) {
        // In this case the device is an iPad.
        [actionSheet showFromRect:[(UIButton *)sender frame] inView:self.view animated:YES];
    }
    else{
        // In this case the device is an iPhone/iPod Touch.
        [actionSheet showInView:self.view];
    }

    actionSheet.tag = 100;
}

- (IBAction)showDeleteConfirmation:(id)sender {
    UIActionSheet *actionSheet = [[UIActionSheet alloc] initWithTitle:@"Really delete the selected contact?"
                                                             delegate:self
                                                    cancelButtonTitle:@"No, I changed my mind"
                                               destructiveButtonTitle:@"Yes, delete it"
                                                    otherButtonTitles:nil];

    if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) {
        // In this case the device is an iPad.
        [actionSheet showFromRect:[(UIButton *)sender frame] inView:self.view animated:YES];
    }
    else{
        // In this case the device is an iPhone/iPod Touch.
        [actionSheet showInView:self.view];
    }

    actionSheet.tag = 200;
}


- (IBAction)showColorsActionSheet:(id)sender {
    UIActionSheet *actionSheet = [[UIActionSheet alloc] initWithTitle:@"Pick a color:"
                                                             delegate:self
                                                    cancelButtonTitle:nil
                                               destructiveButtonTitle:nil
                                                    otherButtonTitles:@"Red", @"Green", @"Blue", @"Orange", @"Purple", nil];

    if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) {
        // In this case the device is an iPad.
        [actionSheet showFromRect:[(UIButton *)sender frame] inView:self.view animated:YES];
    }
    else{
        // In this case the device is an iPhone/iPod Touch.
        [actionSheet showInView:self.view];
    }

    actionSheet.tag = 300;
}

Now you know how to distinguish the device in which your app runs, and how to properly present an action sheet. Go ahead and try out all three buttons to see how the action sheet appears on iPad:

You may notice that when showing the colors action sheet and then tapping out of the popover controller, the app crashes. That’s because there is not a cancel button. To counterattack it, in the showColorsActionSheet: method either instead of nil set a cancel button title, or at the top of the method add the next line:

NSString *cancelTitle = (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) ? @"Cancel" : nil;

and in the cancelButtonTitle parameter set the cancelTitle value. This time it will work perfectly.

Action Sheet Showing Extras

Until the last section of this tutorial we saw two ways for presenting an action sheet. The first one:

[actionSheet showInView:self.view];

works on all devices, while the next one:

[actionSheet showFromRect:[(UIButton *)sender frame] inView:self.view animated:YES];

has effect only on iPad. Further than those two methods, there are a few more that I consider as a good idea I should refer to, so let’s give them a quick look.

The first method we’ll talk about, is the showFromTabBar:, which as you guess is useful when there is a tab bar in your application. It mostly works on iPhone/iPod Touch devices, and its purpose is to allow an action sheet to properly appear without get overlapped by the tab bar. Actually, the action sheet originates from it and not from the view’s bottom side. On iPad the action sheet will simply appear on the centre of the screen, without any arrow pointing to some point.

Similar to the above is the showFromToolbar: method. It’s used when a toolbar exists at the bottom side of the view, and the action sheet must be properly shown without be overlapped by the toolbar.

Finally, there’s also the showFromBarButtonItem:animated: method, which is helpful on iPad for displaying an action sheet with its popover view pointing to the bar button item that triggered the appearing.

As you see, there are methods suitable for iPhone devices, and methods suitable for iPad devices. However, this doesn’t mean that they cannot be used the other way round. On iPhone, all methods have the same result and the action sheet is shown from the bottom side of the screen, or from the tab bar/toolbar. On iPad methods that do not display the popover with the action sheet to a specific place with a pointing arrow, they just show it to the centre of the screen. When displaying action sheets, always make sure that you use the appropriate method for presenting them so as to make sure that you are aligned to the recommended interface guidelines.

Working with UIPopoverController

Now that we have talked about action sheets and how they are displayed on both iPhone and iPad devices, let’s do some more discussion about the UIPopoverController. Until now we referenced it a lot of times, but still we haven’t made any implementation that allow us to manually create and show one. So, in this part we will see how it can be used in general cases, as the purpose of its existence lies to usages other than simply displaying action sheets.

The great with the popover controller is that it can display the contents of any view controller to the position you define, usually near the button that triggers its appearance. It can get any size you want, and the arrow that points to the button that originates from, along with the fade effect, result to a very fancy, convenient and useful tool for presenting content on top of other content when working on iPad.

We will see how popover controller works through a practical example. We will use a new view controller and we will display its contents in the popover. This view controller will contain a sample user data form, where some basic info can be filled in and selected (user name, age range and gender). The following Interface Builder screenshot will make it more clear:

Also, the view controller will have its own xib file with the interface designed in it, which will be called upon initialization. Finally, through the implementation of a protocol and a delegate method we’ll get the entered/selected data from the new view controller back to the normal one.

To focus on the important stuff, we won’t manually create the new view controller. Instead, please go ahead to download the related files now, and add them to the project. Make sure you add all of the following files:

• TestViewController.h
• TestViewController.m
• TestViewController.xib

Supposing at this point that you have downloaded and added all files and you are ready to proceed, let’s create a new button to the iPad interface. Click on the Main_iPad.storyboard file, and let Interface Builder appear. Then, get a UIButton from the Object Library, and set the next properties:

1. Frame: X=310, Y=239, Width=149, Height=30
2. Title: User Data Entry Form

After that, open the ViewController.h file, and declare the following IBAction method:

- (IBAction)showUserDataEntryForm:(id)sender;

Return to the Interface Builder, and connect that action method to the newly added button.

Now, open once again the ViewController.h file, and firstly import the TestViewController class as shown below:

#import "TestViewController.h"

Also, make the ViewController class conform to the TestViewControllerDelegate protocol by adding it to the interface header line like below:

@interface ViewController : UIViewController 

By adopting the above protocol, we’ll be able to use the delegate method of the TestViewController class later on and to get the entered data.

Now, let’s go to the most essential part of this section, to the implementation of the IBAction method we previously declared and to the usage of the popover controller. For starters though, we must declare a private class property for the popover, so open the ViewController.m and go to the private section of the interface. In there, add the following property declaration:

@interface ViewController ()

@property (nonatomic, strong) UIPopoverController *userDataPopover;

@end

Now, move straight ahead to the IBAction method implementation, where we will initialize and use the above object. As I already said in the beginning of this section, the special characteristic of the popover controller is the ability to display the contents of another view controller, therefore the first step we must make is to initialize an object of the TestViewController class.

- (IBAction)showUserDataEntryForm:(id)sender {
    TestViewController *testViewController = [[TestViewController alloc] initWithNibName:@"TestViewController" bundle:nil];
    testViewController.delegate = self;

}

As you see, upon initialization we load the view controller’s xib file as well, and beyond that, we make our class the delegate of the testViewController object. Now that we have a view controller on our hands, let’s use the popover controller object we privately declared and let it finally appear. We only need to add three commands, which we’ll see step by step. Initially, let’s perform the initialization:

self.userDataPopover = [[UIPopoverController alloc] initWithContentViewController:testViewController];

It’s obvious that the view controller we want to display is directly given as a parameter to the popover controller. That’s why we first declared and initialized the TestViewController object. The next step is to define the popover size, which usually matches the contained view’s size:

self.userDataPopover.popoverContentSize = CGSizeMake(320.0, 400.0);

Finally, let’s display it:

[self.userDataPopover presentPopoverFromRect:[(UIButton *)sender frame]
                                       inView:self.view
                     permittedArrowDirections:UIPopoverArrowDirectionAny
                                     animated:YES];

This method accepts four parameters as you can notice. The first one is the frame from which the popover originates, and usually is the button’s frame that is used to present it. The next one, is the view in which the popover controller will appear to. As you understand, it’s not always necessary to display it in the default view, but that’s the most common case. The third parameter specifies the direction of the arrow that appears on the popover controller, pointing to the button that originates from. Unless you make sure that the popover controller will always be displayed on the same place, then you’d better use UIPopoverArrowDirectionAny parameter to allow the system decide the position of the arrow. Don’t forget that when changing iPad’s orientation the popover controller can be re-positioned to a new place, and is quite possible that the arrow should point towards another direction. Finally, the last parameter specifies whether the popover will appear using animation or not, and usually that value is set to YES.

Here’s the whole IBAction method:

- (IBAction)showUserDataEntryForm:(id)sender {
    TestViewController *testViewController = [[TestViewController alloc] initWithNibName:@"TestViewController" bundle:nil];
    testViewController.delegate = self;

    self.userDataPopover = [[UIPopoverController alloc] initWithContentViewController:testViewController];
    self.userDataPopover.popoverContentSize = CGSizeMake(320.0, 400.0);
    [self.userDataPopover presentPopoverFromRect:[(UIButton *)sender frame]
                                       inView:self.view
                     permittedArrowDirections:UIPopoverArrowDirectionAny
                                     animated:YES];


}

If you give the app a try now, then when tapping on the new button existing on the interface you’ll see the popover controller appearing and containing the TestViewController interface. Cool and fast way to show some content, right?

Back to code now, let’s implement the delegate method of the TestViewController class, in which we’ll simply log on the debugger the entered and selected data, and the we will dismiss the popover controller. There’s nothing especially hard in it, so here I give you its implementation:

-(void)userDataChangedWithUsername:(NSString *)username andAgeRange:(NSString *)ageRange andGender:(NSString *)gender{
    NSLog(@"Your name is %@, your age range is %@ and your gender is %@", username, ageRange, gender);

    [self.userDataPopover dismissPopoverAnimated:YES];
}

Run the app once again now. You’ll find out that the Done button properly works, and on the debugger you see all the data you entered on the form. Also, the popover controller gets disappeared from the screen.

In most of cases, what you read in here is the way that you’ll need to use the popover controller. The “hard” thing is to prepare the view controller that it will be contained, along with all the logic behind it, not the popover itself. However, in the rare cases you might need to use delegate methods, first make sure that your class conforms to the UIPopoverControllerDelegate, and then proceed to the implementation. The provided delegates methods are:

1. popoverControllerShouldDismissPopover: This one is called before the popover controller disappears from the screen.
2. popoverControllerDidDismissPopover: This one is called after the popover controller has disappeared from the screen.

Use any, or both of them depending on your needs.

Summary

Reaching the end of this tutorial, it becomes clear that using action sheets and popover controllers consist of a very easy, fast and convenient way to present menus and content to the user. The great common element on both of them, is the fact that they can be presented almost instantly, with a little effort. The only drawback is that they may do not fit to the ecosystem on highly customized applications, but that’s something that developers know from the beginning. Closing, in case you don’t use any or both of these view controllers, I would advise you to start doing so, as they are time-saving tools and even more, it’s possible to make your apps look even more professional. Happy… action-taking!

For your reference, you can download the complete Xcode project from here. Again, leave me comment if you have any questions.