SDK for ButterCMS API.
For a comprehensive list of examples, check out the API documentation.
- open XCode->File->Add Package
- search buttercms-swift
- amend dependency if required
- click Add package
- Install CocoaPods if not installed already
$ brew install cocoapods
- Create a Podfile in the root directory of your project
$ pod init
- Open generated Podfile, for example
$ open -a Xcode Podfile
- Update podfile
target 'YourAppName' do
use_frameworks!
pod 'ButterCMSSDK', '1.0.7'
end
- Install ButterCMS pod
$ pod install
To get started with the Butter API, instantiate the ButterCMSClient with the API key found in the Butter Admin Settings.
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
Given the client is based on URLSession - meaning, in case you need more custom setting for URLSession you can pass one into constructor:
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY", urlSession: yourURLSession)
Since version 1.0.9 the SDK allows to switch ON/OFF the preview mode globaly. If sent ON all APIs which are using the .preview parameter will inherently have ti set to .preview(value: 1) by default.
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY", previewMode=true)
On particular API level (e.g. getPosts) this global setting can be overwritten following way:
butter.getPosts(parameters: [ .preview(value: 0)]) { result in
....
}
In can be also changed later on the butter instance level:
butter.previewMode = false
All APIs are asynchronous and expects a completion() as a parameter. The completion() is called when the asynchronous call is finished. The completion() takes respective Response or Error encapsulated in the Result object as a parameter.
API may take additional array of parameters which specify either what data shall be returned or how they shall be returned. Check Butter API doc for additional details. Every API parameters has its respective Enum listing allowed parameters and their value types. For example:
public enum PostsParameters: Parameters {
case preview(value: Int)
case page(value: Int)
case pageSize(value: Int)
case excludeBody
case authorSlug(value: String)
case categorySlug(value: String)
case tagSlug(value: String)
}
XCode can then suggest appropriate parameters as you type your code.
Typical way how to call an API is as follows:
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.getPosts(parameters: [
.preview(value: 1),
.excludeBody,
.page(value: 1),
.pageSize(value: 10)
]) { result in
switch result {
case .success(let posts):
//Do something on success
print("Count: \(posts.meta.count)")
posts.data.compactMap() { print("Post: \($0.title)") }
case .failure(let error):
//Do something on failure
print("getPost failed with Error: \(error)")
}
}
getPost(slug: String, completion: @escaping (Result<PostResponse, Error>) -> Void)
getPosts(parameters: [PostsParameters] = [], completion: @escaping (Result<PostsResponse, Error>) -> Void)
searchPosts(parameters: [PostSearchParameters] = [], completion: @escaping (Result<PostsResponse, Error>) -> Void)
getAuthor(slug: String, parameters: [AuthorParameters] = [], completion: @escaping (Result<AuthorResponse, Error>) -> Void)
getAuthors(parameters: [AuthorParameters] = [], completion: @escaping (Result<AuthorsResponse, Error>) -> Void)
getCategory(slug: String, parameters: [CategoryParameters] = [], completion: @escaping (Result<CategoryResponse, Error>)
getCategories(parameters: [CategoryParameters] = [], completion: @escaping (Result<CategoriesResponse, Error>) -> Void)
getTag(slug: String, parameters: [TagParameters] = [], completion: @escaping (Result<TagResponse, Error>) -> Void)
getTags(parameters: [TagParameters] = [], completion: @escaping (Result<TagsResponse, Error>) -> Void)
getFeeds(name: String, parameters: [FeedsParameters] = [], completion: @escaping (Result<FeedResponse, Error>) -> Void)
The Pages in Butter CMS has configurable schema. See ButterCMS doc for details how to create page. The schema defines fileds which can exist on the page. Individual fields can be of basic types like Strings as well as custom Structs or Classes. The SDK requires you to model the Page shema as a Codable Struct and pass it to getPages API. This allows the SDK to deserialize the page data for you.
ButerCMS also provides a concept of Page types and you can get all pages of the same type by getPages() API. To read more about the Page types refer to ButterCMS doc.
The API page methods has following prescription:
getPage<T: Decodable>(slug: String, parameters: [PageParameters] = [], pageTypeSlug: String, type: T.Type, completion: @escaping (Result<PageResponse<T>, Error>) -> Void)
public func searchPages<T: Decodable>(parameters: [PageSearchParameters], type: T.Type, completion: @escaping (Result<PagesResponse<T>, Error>) -> Void)
getPages<T: Decodable>(parameters: [PagesParameters] = [], pageTypeSlug: String, type: T.Type, completion: @escaping (Result<PagesResponse<T>, Error>) -> Void)
The ButterCMS account came equiped with the Case Study page type which can be modeled following way:
private struct CaseStudyPageFields: Codable {
var title: String
var content: String
var industry: String
var subindustry: String
var featuredImage: String
var reviewer: String
var studyDate: Date
}
And here is how it can be used to get pages with method searchPages:
butter.searchPages(parameters: [
.query(value: "Automotive"),
.pageType(value: "case_studies"),
.locale(value: "en"),
.page(value: 1),
.pageSize(value: 10)
], type: CaseStudyPageFields.self) { result in
switch result {
case .success(let pages):
.....
case .failure(let error):
.....
}
}
Similar as Pages the Collections has also configurable schema. See ButterCMS doc for more details. The schema again define fields which composes the collection item. The SDK requires you to model the collection item as a class an provide it as a parameter to the API. The collection item class must implement the CollectionItem protocol.
private class FaqItem: CollectionItem {
var meta: CollectionItemMeta
var question: String = ""
var answer: String = ""
}
butter.getCollection(slug: "faq", type: FaqItem.self) { result in
// do something with the result
}
Here you can download the sample application: https://github.com/ButterCMS/buttercms-ios.git [email protected]:ButterCMS/buttercms-ios.git