Contentful.swift : Swift Delivery SDK for Contentful

Related tags

Image contentful
Overview

header

Join Contentful Community Slack   Join Contentful Community Forum

contentful.swift - Swift Delivery SDK for Contentful

Swift SDK 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.

This repository is actively maintained   MIT License   Build Status   Coverage Status   Codebeat badge

Version   Carthage compatible   Swift Package Manager compatible   iOS | macOS | watchOS | tvOS  

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.

Table of contents

Core Features

Getting started

In order to get started with the Contentful Swift SDK 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:

5.0.0">
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 SDK:

) in switch result { case .success(let entry): print(entry) case .error(let error): print("Error \(error)!") } }">
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>) in
    switch result {
    case .success(let entry):
        print(entry)
    case .error(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:

>) in guard let cats = result.value?.items else { return } print(cats) }">
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 library. The SDK 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 SDK to properly create your model types when receiving JSON, you must pass in these types to your Client instance:

let contentTypeClasses: [EntryDecodable.Type] = [
    Cat.self
    Dog.self,
    Human.self
]

let client = Client(spaceId: spaceId,
                    accessToken: deliveryAPIAccessToken,
                    contentTypeClasses: contentTypeClasses)

The source for the Cat model class is below; note the helper methods the SDK adds to Swift 4's Decoder type to simplify for parsing JSON returned by Contentful. You also need to pass in these types to your Client instance in order to use the fetch methods which take EntryDecodable type references:

.self, forKey: .likes) self.lives = try fields.decodeIfPresent(Int.self, forKey: .lives) try fields.resolveLink(forKey: .bestFriend, decoder: decoder) { [weak self] linkedCat in self?.bestFriend = linkedCat as? Cat } } enum FieldKeys: String, CodingKey { case bestFriend case name, color, likes, lives } }">
final class Cat: EntryDecodable, FieldKeysQueryable {

    static let contentTypeId: String = "cat"

    // FlatResource members.
    let id: String
    let localeCode: String?
    let updatedAt: Date?
    let createdAt: Date?

    let color: String?
    let name: String?
    let lives: Int?
    let likes: [String]?

    // Relationship fields.
    var bestFriend: Cat?

    public required init(from decoder: Decoder) throws {
        let sys         = try decoder.sys()
        id              = sys.id
        localeCode      = sys.locale
        updatedAt       = sys.updatedAt
        createdAt       = sys.createdAt

        let fields      = try decoder.contentfulFieldsContainer(keyedBy: Cat.FieldKeys.self)

        self.name       = try fields.decodeIfPresent(String.self, forKey: .name)
        self.color      = try fields.decodeIfPresent(String.self, forKey: .color)
        self.likes      = try fields.decodeIfPresent(Array<String>.self, forKey: .likes)
        self.lives      = try fields.decodeIfPresent(Int.self, forKey: .lives)

        try fields.resolveLink(forKey: .bestFriend, decoder: decoder) { [weak self] linkedCat in
            self?.bestFriend = linkedCat as? Cat
        }
    }

    enum FieldKeys: String, CodingKey {
        case bestFriend
        case name, color, likes, lives
    }
}

If you want to simplify the implementation of an EntryDecodable, declare conformance to Resource and add let sys: Sys property to the class and assign via sys = try decoder.sys() during initialization. Then, id, localeCode, updatedAt, and createdAt are all provided via the sys property and don't need to be declared as class members. However, note that this style of implementation may make integration with local database frameworks like Realm and CoreData more cumbersome.

Additionally, the SDK requires that instances of a type representing an entry or asset must be a class instance, not a structβ€”this is because the SDK ensures that the in-memory object graph is complete, but also that it has no duplicates.

Documentation & References

Reference Documentation

The SDK has 100% documentation coverage of all public variables, types, and functions. You can view the docs on the web or browse them in Xcode. For further information about the Content Delivery API, check out the Content Delivery API Reference Documentation.

Tutorials & other resources

  • This library is a wrapper around our Contentful Delivery REST API. Some more specific details such as search parameters and pagination are better explained on the REST API reference, and you can also get a better understanding of how the requests look under the hood.
  • Check the Contentful for Swift page for Tutorials, Demo Apps, and more information on other ways of using Swift with Contentful

Swift playground

If you'd like to try an interactive demo of the API via a Swift Playground, do the following:

git clone --recursive https://github.com/contentful/contentful.swift.git
cd contentful.swift
make open

Then build the "Contentful_macOS" scheme, open the playground file and go! Note: make sure the "Render Documentation" button is switched on in the Utilities menu on the right of Xcode, and also open up the console to see the outputs of the calls to print.

Example application

See the Swift iOS app on Github and follow the instructions on the README to get a copy of the space so you can see how changing content in Contentful affects the presentation of the app.

Migration

We gathered all information related to migrating from older versions of the library in our Migrations.md document.

Swift Versioning

It is recommended to use Swift 5.0, as older versions of the SDK will not have fixes backported. If you must use older Swift versions, see the compatible tags below.

Swift version Compatible Contentful tag
Swift 5.0 [ β‰₯ 5.0.0 ]
Swift 4.2 [ β‰₯ 4.0.0 ]
Swift 4.1 [2.0.0 - 3.1.2]
Swift 4.0 [0.10.0 - 1.0.1]
Swift 3.x [0.3.0 - 0.9.3]
Swift 2.3 0.2.3
Swift 2.2 0.2.1

Reach out to us

Have questions about how to use this library?

  • Reach out to our community forum: Contentful Community Forum
  • Jump into our community slack channel: Contentful Community Slack

You found a bug or want to propose a feature?

  • File an issue here on GitHub: File an issue. Make sure to remove any credential from your code before sharing it.

You need to share confidential information or have other questions?

  • File a support ticket at our Contentful Customer Support: File support ticket

Get involved

PRs Welcome

We appreciate any help on our repositories. For more details about how to contribute see our Contributing.md document.

License

This repository is published under the MIT license.

Code of Conduct

We want to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of gender identity and expression, sexual orientation, disability, physical appearance, socioeconomic status, body size, ethnicity, nationality, level of experience, age, religion (or lack thereof), or other identity markers.

Read our full Code of Conduct.

You might also like...
GPUImage 3 is a BSD-licensed Swift framework for GPU-accelerated video and image processing using Metal.
GPUImage 3 is a BSD-licensed Swift framework for GPU-accelerated video and image processing using Metal.

GPUImage 3 Janie Clayton http://redqueengraphics.com @RedQueenCoder Brad Larson http://www.sunsetlakesoftware.com @bradlarson [email protected]

A lightweight generic cache for iOS written in Swift with extra love for images.
A lightweight generic cache for iOS written in Swift with extra love for images.

Haneke is a lightweight generic cache for iOS and tvOS written in Swift 4. It's designed to be super-simple to use. Here's how you would initalize a J

A lightweight and fast image loader for iOS written in Swift.

ImageLoader ImageLoader is an instrument for asynchronous image loading written in Swift. It is a lightweight and fast image loader for iOS. Features

A Swift implementation of fastimage. Supports PNG, GIF, and JPEG.
A Swift implementation of fastimage. Supports PNG, GIF, and JPEG.

ImageScout ImageScout is a Swift implementation of fastimage. It allows you to find the size and type of a remote image by downloading as little as po

A Swift client library for generating URLs with imgix

imgix-swift is a client library for generating image URLs with imgix. Written in Swift, but can be used with Objective-C codebases as well. Installati

Kingfisher is a powerful, pure-Swift library for downloading and caching images from the web
Kingfisher is a powerful, pure-Swift library for downloading and caching images from the web

Kingfisher is a powerful, pure-Swift library for downloading and caching images from the web. It provides you a chance to use a pure-Swift way to work

🍁πŸ₯“ Lightweight and fast Swift library for image downloading, caching and transformations
🍁πŸ₯“ Lightweight and fast Swift library for image downloading, caching and transformations

MapleBacon Introduction MapleBacon is a lightweight and fast Swift library for downloading and caching images. Example The folder Example contains a s

An image download extension of the image view written in Swift for iOS, tvOS and macOS.
An image download extension of the image view written in Swift for iOS, tvOS and macOS.

Moa, an image downloader written in Swift for iOS, tvOS and macOS Moa is an image download library written in Swift. It allows to download and show an

❄️  SVG in Swift
❄️ SVG in Swift

Snowflake ❀️ Support my apps ❀️ Push Hero - pure Swift native macOS application to test push notifications PastePal - Pasteboard, note and shortcut ma

Owner
An Tran
An Tran
A free, multiplatform SDK for real-time facial motion capture using blendshapes, and rigid head pose in 3D space from any RGB camera, photo, or video.

mocap4face by Facemoji mocap4face by Facemoji is a free, multiplatform SDK for real-time facial motion capture based on Facial Action Coding System or

Facemoji 537 Sep 22, 2022
iOS SDK to share JPEG images with an expiration date

Ebblink iOS SDK A library to integrate Ebblink private image sharing capabilities into your iOS app. Table of Contents Getting Started Requirements Se

null 4 Apr 6, 2018
Lokalise iOS SDK

Lokalise iOS SDK Lokalise lets you manage keys and translations of your app, game, or website – either on your own or with a team of collaborators. Bu

Lokalise 47 Aug 15, 2022
PhotoEditor SDK: A fully customizable photo editor for your app.

About PhotoEditor SDK for iOS Our SDK provides tools for adding photo editing capabilities to your iOS application with a big variety of filters that

IMG.LY 114 Sep 5, 2022
API surface for Swift plug-ins using the Swift Plugin Manager

SwiftPlugin The minimal API surface required for the Swift Plugin Manager to create instances from a loaded plugin. Additional documentation and refer

Joakim Hassila 2 Mar 25, 2022
Swift Package Manager command plugin for Swift-DocC

Swift-DocC Plugin The Swift-DocC plugin is a Swift Package Manager command plugin that supports building documentation for SwiftPM libraries and execu

Apple 201 Sep 26, 2022
Agrume - πŸ‹ An iOS image viewer written in Swift with support for multiple images.

Agrume An iOS image viewer written in Swift with support for multiple images. Requirements Swift 5.0 iOS 9.0+ Xcode 10.2+ Installation Use Swift Packa

Jan Gorman 572 Sep 6, 2022
BlockiesSwift - Unique blocky identicons generator for Swift

βš—οΈ BlockiesSwift This library is a Swift implementation of the Ethereum fork of Blockies which is intended to be used in iOS, watchOS, tvOS and macOS

null 56 Aug 17, 2022
FacebookImagePicker is Facebook album photo picker written in Swift.

Features β€’ Installation β€’ Usage β€’ Translation β€’ License GBHFacebookImagePicker is Facebook's album photo picker written in Swift, built to provide a s

Florian Gabach 228 May 19, 2022
GPUImage 2 is a BSD-licensed Swift framework for GPU-accelerated video and image processing.

GPUImage 2 Brad Larson http://www.sunsetlakesoftware.com @bradlarson [email protected] Overview GPUImage 2 is the second generation of th

Brad Larson 4.8k Sep 19, 2022