Home

Awesome

EVCloudKitDao

<!--- [![Circle CI](https://img.shields.io/circleci/project/evermeer/EVCloudKitDao.svg?style=flat)](https://circleci.com/gh/evermeer/EVCloudKitDao) -->

Build Status Issues Stars Documentation Version Awesome

Language Platform Support License

Git Twitter LinkedIn Website eMail

Discuss EVCloudKitDao : Join the chat at https://gitter.im/evermeer/EVCloudKitDao

What is this

With Apple CloudKit, you can focus on your client-side app development and let iCloud eliminate the need to write server-side application logic. CloudKit provides you with Authentication, private and public database, structured and asset storage services - all for free with very high limits. For more information see Apple CloudKit documentation

This is a library to simplify the access to Apple's CloudKit data and notifications (see a more detailed description below)

There is a dependency with EVReflection This will automatically be setup if you are using cocoapods.

See the Quick Help info for method descriptions or the documentation at cocoadocs.org

The AppMessage demo is a complete functional messaging app based on CloudKit:

I'm looking for feedback. Please let me know if you want something changed or added to the library or the demo.

A picture says more than 1000 words

Here are screenshots of the included demo app chat functionality:

Screenshot0 Screenshot1

Screenshot2 Screenshot3

Documentation

Documentation is now available at cocoadocs.org

Main features of EVCloudKitDao:

Main features of EVCloudData:

Main features of EVglobal

Known issues (Swift limitations)

External components for the demo

The AppMessage demo is using the following components which can be installed using CocoaPods. See instructions below. Because of dependency compatibility the AppMessage demo requires Xcode 6.2 or later.

Besides these the dependency to EVCloudKitDao has been skipped by just using the classes directly

Using EVCloudKitDao or EVCloudData in your own App

'EVCloudKitDao' is now available through the dependency manager CocoaPods. You do have to use cocoapods version 0.36. At this moment this can be installed by executing:

[sudo] gem install cocoapods

If you have installed cocoapods version 0.36 or later, then you can just add EVCloudKitDao to your workspace by adding the folowing 2 lines to your Podfile:

use_frameworks!
pod "EVCloudKitDao"

I have now moved on to Swift 2. If you want to use EVCloudKitDao with Swift 1.2, then get that version by using the podfile command:

use_frameworks!
pod 'EVReflection', :git => 'https://github.com/evermeer/EVReflection.git', :branch => 'Swift1.2'
pod 'SwiftTryCatch'
pod 'EVCloudKitDao', '~> 2.6'

Version 0.36 of cocoapods will make a dynamic framework of all the pods that you use. Because of that it's only supported in iOS 8.0 or later. When using a framework, you also have to add an import at the top of your swift file like this:

import EVCloudKitDao

If you want support for older versions than iOS 8.0, then you can also just copy the Cloudkit folder containing the 5 classes EVCloudKitDao, EVCloudData, EVReflection, EVCloudData and EVglobal to your app.

When you have added EVCloudKitDao to your project, then have a look at the AppMessage code for how to implement push notifications and how to connect to CloudKit data (see AppDelegate.swift and LeftMenuViewController.swift) For contacts see the RightMenuViewController.swift and for other usage see the TestsViewController.swift

Building the AppMessage demo

  1. Clone the repo to a working directory

  2. CocoaPods is used to manage dependencies. Pods are setup easily and are distributed via a ruby gem. Follow the simple instructions on the website to setup. After setup, run the following command from the toplevel directory of AppMessage to download the dependencies for AppMessage:

pod install

  1. Open the AppMessage.xcworkspace in Xcode.

  2. Go to AppMessage target settings and update the:

  1. Build and Run the app. In the AppDelegate there is a call to initiate all objects (createRecordTypes). All required CloudKit objects will be created.

  2. Open the CloudKit dashboard, select all recordtypes and enable all 'Metadata Indexes'

  3. Disable the call to .createRecordTypes in AppDelegate and run the app again.

  4. Make sure you run the app on 2 devices, each using a diverent iCloud account and each device having the other account in it's contact list.

and you are ready to go!

How to use the EVCloudData

Below is all the code you need to setup a news feed including push notification handling for any changes.

// Just enherit from CKDataObject so that you have access to the CloudKit metadata
class News : CKDataObject {
    var Subject : String = ""
    var Text : String = ""
}

class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?

    func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: NSDictionary?) -> Bool {
        // Make sure we receive subscription notifications
        application.registerUserNotificationSettings(UIUserNotificationSettings(forTypes: .Alert | .Badge | .Sound, categories: nil))
        application.registerForRemoteNotifications()
        return true
    }

    func application(application: UIApplication!, didReceiveRemoteNotification userInfo: [NSObject : NSObject]!) {
        EVLog("Push received")
        EVCloudData.publicDB.didReceiveRemoteNotification(userInfo, {
            EVLog("Not a CloudKit Query notification.")            
        })
    }

    func applicationDidEnterBackground(application: UIApplication) {
        // If you do a backup then this backup will be reloaded after app restart.
        EVCloudData.publicDB.backupData()        
    }
}


class LeftMenuViewController: UIViewController {
    var newsController: NewsViewController!

    override func viewDidLoad() {
        super.viewDidLoad()
        connectToNews()
        // Only already setup CloudKit connect's will receive these notifications (like the News above)
        EVCloudData.publicDB.fetchChangeNotifications()        
    }

    deinit {
        EVCloudData.publicDB.disconnect("News_All")
    }

    func connectToNews() {
        EVCloudData.publicDB.connect(News()
        , predicate: NSPredicate(value: true)
        , filterId: "News_All"
        , configureNotificationInfo: { notificationInfo in
            notificationInfo.alertBody = "New news item"
            notificationInfo.shouldSendContentAvailable = true }
        , completionHandler: { results in
            EVLog("There are \(results.count) existing news items")
            self.newsController.tableView.reloadData()
            return results.count < 200 // Continue reading if we have less than 200 records and if there are more.
        }, insertedHandler: {item in
            Helper.showStatus("New News item: '\(item.Subject)'")
            self.newsController.tableView.reloadData()
        }, updatedHandler: {item in
            Helper.showStatus("Updated News item:'\(item.Subject)'")
            self.newsController.tableView.reloadData()
        }, deletedHandler: {recordId in
            Helper.showStatus("News item was removed")
            self.newsController.tableView.reloadData()
        }, dataChangedHandler : {
            EVLog("Some News data was changed")
        }, errorHandler: {error in
            Helper.showError("Could not load news: \(error.description)")
        })
    }
}


class NewsViewController : UIViewController, UITableViewDataSource, UITableViewDelegate, RESideMenuDelegate {
	...
    func tableView(tableView: UITableView, cellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell {
        var cell:UITableViewCell! = tableView.dequeueReusableCellWithIdentifier(cellIdentifier) as? UITableViewCell
        ...
        //This line all you need to get the correct data for the cell
        var news:News = EVCloudData.publicDB.data["News_All"]![indexPath.row] as News

        cell.textLabel?.text = news.Subject
        cell.detailTextLabel?.text = news.Body
        return cell;
    }
}

How to use the EVCloudKitDao

// Just enherit from CKDataObject so that you have access to the CloudKit metadata
class Message : CKDataObject {
    var From : String = ""
    var To : String = ""
    var Text : String = ""
}

let dao: EVCloudKitDao = EVCloudKitDao.publicDB
let dao2 = EVCloudKitDao.publicDBForContainer("iCloud.nl.evict.myapp")

var message = Message()
message.From = "me@me.com"
message.To = "you@me.com"
message.Text = "This is the message text"

dao.saveItem(message, completionHandler: {record in
        createdId = record.recordID.recordName;
        EVLog("saveItem : \(createdId)");
    }, errorHandler: {error in
        EVLog("<--- ERROR saveItem");
    })

dao.query(Message()
    , completionHandler: { results in
        EVLog("query : result count = \(results.count)")
    }, errorHandler: { error in
        EVLog("<--- ERROR query Message")
    })

All you need for a keyword search (async autocomplete)

var queryRunning:Int = 0
var data:[Message] = []

func searchDisplayController(controller: UISearchDisplayController!, shouldReloadTableForSearchString searchString: String!) -> Bool {
    self.filterContentForSearchText(searchString)
    return false
}

func searchDisplayController(controller: UISearchDisplayController!, shouldReloadTableForSearchScope searchOption: Int) -> Bool {
    self.filterContentForSearchText(self.searchDisplayController!.searchBar.text)
    return false
}

func filterContentForSearchText(searchText: String) {
    EVLog("Filter for \(searchText)")
    networkSpinner(1)
    EVCloudKitDao.publicDB.query(Message(), tokens: searchText, completionHandler: { results in
        EVLog("query for tokens '\(searchText)' result count = \(results.count)")
        self.data = results
        NSOperationQueue.mainQueue().addOperationWithBlock {
            self.searchDisplayController!.searchResultsTableView.reloadData()
            self.tableView.reloadData()
            self.networkSpinner(-1)
        }
    }, errorHandler: { error in
        EVLog("ERROR: query Message for words \(searchText)")
        self.networkSpinner(-1)
    })
}

func networkSpinner(adjust: Int) {
    self.queryRunning = self.queryRunning + adjust
    UIApplication.sharedApplication().networkActivityIndicatorVisible = self.queryRunning > 0
}

override func tableView(tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    return data.count
}

override func tableView(tableView: UITableView, cellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell {
    let cellIdentifier = "Folowin_Search_Cell";
    var cell:UITableViewCell! = tableView.dequeueReusableCellWithIdentifier(cellIdentifier) as? UITableViewCell
    if cell == nil {
        cell = UITableViewCell(style: .Subtitle, reuseIdentifier: cellIdentifier)
    }

    var item:Message = data[indexPath.row]
    cell.textLabel?.text = item.Text
    return cell;
}

Error handling

All cloudkit function have an errorHandler codeblock. You should handle the error appropriate. There is a helper function for getting a functional error status. In most cases you would get something like the code below. When you are doing data manupilations you should also handle the .RecoverableError

func initializeCommunication(retryCount: Double = 1) {
    ...
    }, errorHandler: { error in
        switch EVCloudKitDao.handleCloudKitErrorAs(error, retryAttempt: retryCount) {
            case .Retry(let timeToWait):
                Async.background(after: timeToWait) {
                    self.initializeCommunication(retryCount: retryCount + 1)
                }
            case .Fail:
                if error.code == .limitExceeded {
                    //TODO: try again with a smaller load?
                }            
                Helper.showError("Could not load messages: \(error.localizedDescription)")
            default: // For here there is no need to handle the .Success, and .RecoverableError
                break
        }
    })
}

License

EVCloudKitDao is available under the MIT license. See the LICENSE file for more info.

My other libraries:

Also see my other open source iOS libraries:

Evolution of EVReflection (Gource Visualization)

Evolution of EVReflection (Gource Visualization)