Contentful.swift
A delightful Swift interface to Contentful's content delivery API.
Install / Use
/learn @contentful/Contentful.swiftREADME
contentful.swift - Swift Content Delivery Library for Contentful
<p align="center"> <img src="https://img.shields.io/badge/Status-Maintained-green.svg" alt="This repository is actively maintained" /> <a href="LICENSE"> <img src="https://img.shields.io/badge/license-MIT-brightgreen.svg" alt="MIT License" /> </a> <a href="https://travis-ci.org/contentful/contentful.swift"> <img src="https://img.shields.io/travis/contentful/contentful.swift/master.svg?style=flat" alt="Build Status"> </a> <a href="https://codebeat.co/projects/github-com-contentful-contentful-swift"> <img src="https://codebeat.co/badges/6ebc67e8-29ca-459f-a4b7-b32a84fa9074" alt="Codebeat badge"> </a> </p> <p align="center"> <a href="https://cocoapods.org/pods/Contentful"> <img src="https://img.shields.io/cocoapods/v/Contentful.svg?style=flat" alt="Version"> </a> <a href="https://github.com/Carthage/Carthage"> <img src="https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat" alt="Carthage compatible"> </a> <a href="https://swift.org/package-manager/"> <img src="https://rawgit.com/jlyonsmith/artwork/master/SwiftPackageManager/swiftpackagemanager-compatible.svg" alt="Swift Package Manager compatible"> </a> <a href="https://swift.org/package-manager/"> <img src="https://img.shields.io/cocoapods/p/Contentful.svg?style=flat" alt="iOS | macOS | watchOS | tvOS"> </a> </p>Swift library for the Contentful Content Delivery API and Content Preview API. It helps you to easily access your Content stored in Contentful with your Swift applications.
What is Contentful?
Contentful provides content infrastructure for digital teams to power websites, apps, and devices. Unlike a CMS, Contentful was built to integrate with the modern software stack. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enable developers and content creators to ship their products faster.
<details> <summary>Table of contents</summary> <!-- TOC -->- contentful.swift - Swift Delivery library for Contentful
Core Features
- Content retrieval through Content Delivery API and Content Preview API.
- Link resolution
- Rich query syntax for type-safe queries
- Synchronization
- Localization support
- Up-to-date with the latest Swift development stack: Swift 4.x | Xcode 10.x
- Supports Environments (v2.0.0+)
- Experimental: to render Rich Text on iOS apps, check out rich-text-renderer.swift on Github.
Getting started
In order to get started with the Contentful Swift library you'll need not only to install it, but also to get credentials which will allow you to have access to your content in Contentful.
Installation
CocoaPods installation
platform :ios, '9.0'
use_frameworks!
pod 'Contentful'
You can specify a specific version of Contentful depending on your needs. To learn more about operators for dependency versioning within a Podfile, see the CocoaPods doc on the Podfile.
pod 'Contentful', '~> 5.0.0'
Carthage installation
You can also use Carthage for integration by adding the following to your Cartfile:
github "contentful/contentful.swift" ~> 5.0.0
Swift Package Manager [swift-tools-version 5.0]
Add the following line to your array of dependencies:
.package(url: "https://github.com/contentful/contentful.swift", .upToNextMajor(from: "5.0.0"))
Your first request
The following code snippet is the most basic one you can use to fetch content from Contentful with this library:
import Contentful
let client = Client(spaceId: "cfexampleapi",
environmentId: "master", // Defaults to "master" if omitted.
accessToken: "b4c0n73n7fu1")
client.fetch(Entry.self, id: "nyancat") { (result: Result<Entry, Error>) in
switch result {
case .success(let entry):
print(entry)
case .failure(let error):
print("Error \(error)!")
}
}
Accessing the Preview API
To access the Content Preview API, use your preview access token and set your client configuration to use preview as shown below.
let client = Client(spaceId: "cfexampleapi",
accessToken: "e5e8d4c5c122cf28fc1af3ff77d28bef78a3952957f15067bbc29f2f0dde0b50",
host: Host.preview) // Defaults to Host.delivery if omitted.
Authorization
Grab credentials for your Contentful space by navigating to the "APIs" section of the Contentful Web App. If you don't have access tokens for your app, create a new set for the Delivery and Preview APIs. Next, pass the id of your space and delivery access token into the initializer like so:
Map Contentful entries to Swift classes via EntryDecodable
The EntryDecodable protocol allows you to define a mapping between your content types and your Swift classes that entries will be serialized to. When using methods such as:
let query = QueryOn<Cat>.where(field: .color, .equals("gray"))
client.fetchArray(of: Cat.self, matching: query) { (result: Result<ArrayResponse<Cat>>) in
guard let cats = result.value?.items else { return }
print(cats)
}
The asynchronously returned result will be an instance of ArrayResponse in which the generic type parameter is the same type you've passed into the fetch method. If you are using a Query that does not restrict the response to contain entries of one content type, you will use methods that return MixedArrayResponse instead of ArrayResponse. The EntryDecodable protocol extends the Decodable protocol in Swift 4's Foundation standard SDK. The library provides helper methods for resolving relationships between EntryDecodables and also for grabbing values from the fields container in the JSON for each resource.
In the example above, Cat is a type of our own definition conforming to EntryDecodable and FieldKeysQueryable. In order for the library to properly create your model types when receiving JSON, you must pass in these types to your Client instance:
let contentTypeClasses: [EntryDecodable.Typ
