contentful.objc

Objective-C SDK for Contentful’s Content Delivery API.

Contentful is a content management platform for web applications, mobile apps and connected devices. It allows you to create, edit & manage content in the cloud and publish it anywhere via powerful API. Contentful offers tools for managing editorial teams and enabling cooperation between organizations.

Usage

The CDAClient manages all your interaction with the Contentful Delivery API.

CDAClient* client = [[CDAClient alloc] initWithSpaceKey:@"cfexampleapi" accessToken:@"b4c0n73n7fu1"];
[client fetchEntryWithIdentifier:@"nyancat"
                         success:^(CDAResponse *response, CDAEntry *entry) {
                             NSLog(@"%@", entry.fields);
                         }
                         failure:^(CDAResponse *response, NSError *error) {
                             NSLog(@"%@", error);
                         }];

You can query for entries, assets, etc. with query options similar to what is described in the Delivery API Documentation:

[client fetchEntriesMatching:@{ @"content_type": @"cat" }
                     success:^(CDAResponse *response, CDAArray *entries) {
                         NSLog(@"%@", [[entries.items firstObject] fields]);
                     }
                     failure:^(CDAResponse *response, NSError *error) {
                         NSLog(@"%@", error);
                     }];

Results are returned as object of classes CDAEntry, CDAAsset, CDAContentType or CDASpace, depending on the fetch method being called. If there are multiple results, they will be returned as a CDAArray instance, which encapsulates the actual resources in the items property.

This repository contains multiple examples, demonstrating the use in common real world scenarios and also showing the different ways you can integrate the SDK into your own project.

Using Custom Entry Classes

You might want to subclass CDAEntry to store additional data alongside Entries or to decouple the rest of your app from the Contentful SDK’s API. For this purpose, it is possible to register your own custom classes for specific Content Types, like this:

[client registerClass:[MYSuperCoolClass class] forContentTypeWithIdentifier:@"MyContentType"];

Each time, the receiver needs to create a new Entry object of the given Content Type, it will create instances of MYSuperCoolClass. Make sure that the class inherits from CDAEntry or this mechanism will break at runtime.

Offline Support

Mobile devices will not always have a data connection, so it makes sense to cache data received from Contentful for offline use. The SDK brings two mechanisms which can help with that:

All Resource classes support NSCoding and bring convenience methods for storing and loading from flat files:

[someEntry writeToFile:@"/some/path"];
CDAEntry* readEntry = [CDAEntry readFromFile:@"/some/path" client:client];

Most of the UIKit extensions have an offlineCaching property which transparently uses this mechanism for showing content when offline.

If you rather use another solution, there is the abstract CDAPersistenceManager class with a sample implementation for Core Data. It supports mapping Resources to another method for managing your object graph easily and ties this to the Contentful synchronization API. Check out the Core Data example app for integrating it yourself.

In both cases, you can use the offlineCaching_cda property of the SDK’s UIImageView category to make any image view transparently cache its contents in a flat file on disk. This will only cache images that the user has viewed once while the app was online.

Preview Mode

The Content Delivery API only returns published Entries. However, you might want to preview content in your app before making it public for your users. For this, you can use the preview mode, which will return all Entries, regardless of their published status:

CDAConfiguration* configuration = [CDAConfiguration defaultConfiguration];
configuration.previewMode = YES;

CDAClient* client = [[CDAClient alloc] initWithSpaceKey:@"YourSpaceKey"
                                            accessToken:@"YourAccessToken"
                                          configuration:configuration];

Apart from the configuration option, you can use the SDK without modifications with one exception: you need to obtain a preview access token, which you can get in the API tab of the Contentful app. In preview mode, data can be invalid, because no validation is performed on unpublished entries. Your app needs to deal with that. Be aware that the access token should in no case be shipped with a production app.

UIKit Extensions

The SDK contains some extensions of UIKit classes for common use cases. You can see a lot of them in action in the examples or read this blog post with details on some of them.

Documentation

For further information, check out the Developer Documentation or browse the API documentation. The latter can also be loaded into Xcode as a Docset.

Installation

CocoaPods

CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries like the Contentful Delivery API in your projects.

platform :ios, '7.0'
pod 'ContentfulDeliveryAPI'

This is the easiest way to keep your copy of the Contentful Delivery API updated.

For Swift support using iOS 8, you can enable framework support usage in CocoaPods:

platform :ios, '8.0'
use_frameworks!
pod 'ContentfulDeliveryAPI'

Manual integration

In the case you prefer to manage your dependencies manually, you can just drag all files from the Code subdirectory into your project or integrate the ContentfulDeliveryAPI static library target into your build process. It might be a good idea to add this repository as a Git submodule if you choose this path.

Be aware that the Contentful Delivery API requires both AFNetworking and ISO8601 to compile successfully, so you need to provide these dependencies if you do manual integration.

Static Framework

You can download the Contentful Delivery API as an universal static framework for iOS. Integrate it into your project by unzipping and dragging the ContentfulDeliveryAPI.framework into the Frameworks group of your project. You can also download the UFO example application including the static framework, as an example of integrating it into an Xcode project.

The static framework contains AFNetworking and ISO8601, but they are prefixed so that they do not clash with any copies that might already be part of your application.

It depends on the SystemConfiguration.framework not included by default in iOS projects, so open your project file on the General tab.

Click the + button in the Linked Frameworks and Libraries section at the bottom.

Search for SystemConfiguration and add the framework to your project.

Repeat that with MobileCoreServices, as that framework is also required to be in your project.

Unit Tests

The Contentful Delivery API is fully unit tested.

To run the tests, do the following steps:

$ gem install xcpretty cocoapods cocoapods-testing
$ make test

or run them directly from Xcode.