Contentful SDK for iOS

Published

April 4, 2014

Author

Setup

There are three different ways for integrating the SDK into your own apps, described in detail in the README. For the purpose of this article, we will use CocoaPods, a dependency manager for Objective-C, which makes it easiest to keep the SDK up-to-date:

However, you are free to use Git submodules or [download a static framework][6] if that suits your workflow better.

Configuring the API client

The class CDAClient manages all requests to the API. For most apps, you will have a single Space which contains all your data. In this case, it is recommended to create a singleton category on top of CDAClient to make it simple to dispatch requests from any part of your app:

For creating a client object, the Space key and a Content Delivery API access token are required.

Accessing data

Now that the client is available everywhere, you can fetch entries:

A CDAArray contains a list of CDAResource objects whose concrete type depends on the query. In this case, the *items* property will contain a list of CDAEntry objects.

Each CDAEntry has a fields property, containing the values for Fields defined in the content model. To decouple your app from Contentful, you can register custom subclasses for Content Types, like this:

The BBUPlace class defines properties like:

so that you can deal with Entries like with any other value object.

In the guide app, the class also implements the *MKAnnotation* protocol, which enables directly showing Entries in a map view.

Simple views for your data

The initial view of the guide app is a list of all coffee places it knows about. For common tasks like this, the SDK brings some UI components which can be customized to your needs. In this case, we will create a subclass of CDAEntriesViewController, a UITableViewController optimized for showing a list of Entries matching a certain query.

The basic setup is done in your subclasse's init method:

The cell mapping is a dictionary for specifying which property of the UITableViewCell corresponds to properties in the content model. In addition to that, the shared client is specified as the client to use and the entries are limited to a certain Content Type. Setting the query property is optional, in that case all Entries will be shown.

If you want to show Resources in a UICollectionView, there is CDAResourcesCollectionViewController. It works similar to the Entries view controller:

You need to specify a layout, just like in a normal UICollectionViewController and there is also the cell mapping again. For convenience, there is a ready made collection view cell class which fetches images from the URL in its imageURL property, so that is what we are going to use in this example. The resourceType property defines which type of Resource is going to be fetched, in this case Assets. A CDAAsset has a direct accessor for the URL which is used in the cell mapping here. Finally, the client needs to be specified, like in the previous example.

Presenting data your own way

Of course, it is also possible and often needed to write normal UIViewController subclasses and just pull in some data from Contentful. The class BBULocationViewController from the guide app does just that, utilising the BBUPlace class mentioned earlier. That way, it does not have specific knowledge about the Contentful SDK.

Two things to consider here:

Links might not be resolved, depending on your query. If that is the case, use the resolveWithSuccess:failure: method on any CDAResource. This should be done inside your custom class, look at the fetchPictureAssetsWithCompletionBlock: method from BBUPlace for an example.

Fields can include Markdown. There is another example app which shows how to use the Bypass library for converting Markdown into NSAttributedString which can be displayed in a UITextView since iOS 7. Depending on your use case and target platform, you might want to evaluate other options, for example converting to HTML.

With this, our walk through the coffee guide app is done. You should have everything you need to start building your own iOS apps with Contentful. Check out the SDK and start building.

For more information about managing content in native iOS, watchOS, tvOS and OS X apps, see our article: Selecting an iOS CMS.

[1]: https://www.contentful.com/developers/docs/references/content-delivery-api/
[2]: https://github.com/contentful/guide-app-ios
[3]: https://www.contentful.com/blog/2014/03/26/contentful-hackathon/
[4]: https://github.com/contentful/contentful.objc/blob/master/README.md
[5]: https://cocoapods.org/
[6]: https://static.contentful.com/downloads/iOS/ContentfulDeliveryAPI-0.7.0.zip
[7]: http://cocoadocs.org/docsets/ContentfulDeliveryAPI/0.7.0/Classes/CDAClient.html
[8]: http://cocoadocs.org/docsets/ContentfulDeliveryAPI/0.7.0/Classes/CDAArray.html
[9]: http://cocoadocs.org/docsets/ContentfulDeliveryAPI/0.7.0/Classes/CDAResource.html
[10]: http://cocoadocs.org/docsets/ContentfulDeliveryAPI/0.7.0/Classes/CDAEntry.html
[11]: http://cocoadocs.org/docsets/ContentfulDeliveryAPI/0.7.0/Classes/CDAEntriesViewController.html
[12]: http://cocoadocs.org/docsets/ContentfulDeliveryAPI/0.7.0/Classes/CDAResourcesCollectionViewController.html
[13]: http://cocoadocs.org/docsets/ContentfulDeliveryAPI/0.7.0/Classes/CDAAsset.html
[14]: https://github.com/contentful/guide-app-ios/blob/master/Code/BBULocationViewController.m
[15]: https://www.contentful.com/developers/docs/concepts/links/
[16]: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters
[17]: https://www.contentful.com/blog/2014/02/28/here-be-bold-headlines/
[18]: https://github.com/contentful-labs/contentful-qa-app
[19]: http://uncodin.github.io/bypass/
[20]: https://github.com/contentful/contentful.objc
[200]: https://www.contentful.com/r/knowledgebase/ios-cms/