CBPWordPress is an iOS library that will allow you to easily include content from a WordPress blog. The library can fetch lists of posts, individual posts and submit comments.
It is, of course, available on GitHub under the MIT License as well as via CocoaPods.
Background
Over the last few years, I’ve built an maintained the accompanying iOS app for Broadsheet.ie. It’s nearly tradition now for me to release a new version every year
The Example App
Included in the repo is an example app that is the basis for the new Broadsheet.ie app. This app will allow you to browse the site content, search for posts and submit comments.
The app also refreshes itself in the background, reminds the user of its existence in the morning and evenings and updates the logo on the home screen every 6 hours.
The full app includes Google Analytics and Mobile Ad SDK, Crashlytics and Conveser.io and has its own fork.
Installing the Plugin
Before you can use CBPWordPress, you must install the WP-JSON-API plugin to provide the data to the app. This is a slightly modified fork that provides a few extra fields to make things a bit smoother for the app.
If you want to be able to submit comments via the app, remember to turn on the Respond controller in the JSON API settings section.
Getting Started With The Example
Check out the repo from GitHub and initialise the Example pods:
git clone https://github.com/kmonaghan/CBPWordPress.git cd CBPWordPress/Example pod install
If you open the example project workspace and build and run the app, it should pull the latest 10 posts from Broadsheet.ie.
Using CBPWordPress In Your Own App
CocoaPods
The easiest way to use CBPWordPress is to install it via CocoaPods. To do that, just add the following line to your Podfile and then run ‘pod update’.
pod 'CBPWordPress'
Add the CBPWordPress project to your project
If you don’t use CocoaPods, add all the files in the CBPWordPress folder to your project. Then simply include the CBPWordPress.h header file where you want to use the library.
Note that you will also have to include AFNetworking in your project.
Usage
Pointing the library at your own WordPress installation is trivial. The first call to the library should be to set the root URL for the API.
[CBPWordPressAPIClient rootURI:@"http://YOUR-API-URL];
Once that is set, the calls to the API will use that URL.
Fetching A List Of Posts
To get a list of posts, you use the fetchPostsWithParams:withBlock: method from the NSURLSessionDataTask category.
In the example below, the first page of the recent posts is retrieved and the posts assigned to an array.
__weak typeof(self) weakSelf = self;
[NSURLSessionDataTask fetchPostsWithParams:@{@"page": @(1)}
withBlock:^(CBPWordPressPostsContainer *data, NSError *error) {
if (error) {
//Handle Error
return;
}
__strong typeof(weakSelf) strongSelf = weakSelf;
strongSelf.posts = data.posts;
}];
The allowed parameters are:
- page: The page you want to fetch. Starts at 1.
- count: The number of posts to retrieve. Defaults to 10.
Fetching A Post
If you know the post id, you can fetch a post using the fetchPostWithId:withBlock: method from the NSURLSessionDataTask category. The example below fetches post 1234 and assigns it to a local post variable.
__weak typeof(self) weakSelf = self;
[NSURLSessionDataTask fetchPostWithId:1234
withBlock:^(CBPWordPressPost *post, NSError *error){
if (error) {
//Handle Error
return;
}
__strong typeof(weakSelf) strongSelf = weakSelf;
strongSelf.post = post;
}];
If you have the URL of the post, you can use the fetchPostWithURL:withBlock: method instead. You pass the full URL of the post as the parameter.
Comment On A Post
To comment on a post, the postComment:withBlock: method from the NSURLSessionDataTask category is used. The method takes a CBPWordPressComment object as the first parameter. Below is an example comment being initialised.
CBPWordPressComment *newComment = [CBPWordPressComment new]; newComment.postId = 1234; newComment.email = @"example@example.com"; newComment.name = @"Jonny Appleseed"; newComment.content = @"This is a comment!"; //Optional newComment.url = @"http://somewebsite.com"; //If the comment is replying to another comment newComment.parent = 1234;
Note that the URL and parent properties are optional but everything else is required. The parent property should be only be set if the user is replying to a comment and should be that comment’s id.
Once the comment is initialised, pass it to the postComment:withBlock: method. In the following example, the new comment is submitted and on success is set to the returned comment object.
__weak typeof(self) weakSelf = self;
[NSURLSessionDataTask postComment:newComment
withBlock:^(CBPWordPressComment *comment, NSError *error){
__strong typeof(weakSelf) strongSelf = weakSelf;
if (error) {
//Handle error
return;
}
strongSelf.comment = newComment;
Known issue: if WordPress detects a duplicate comment, the resulting return is HTML rather than JSON.
To Do
The library is very much a work in progress. Some of the planned functionality to add is:
- Add option to fetch data from WP-API plugin
- Implement helper methods for each WP-JSON-API endpoint (get_category_posts, get_tag_posts etc.)
- Add a Today Extension to the example app
Contributing
Contributions via pull requests and suggestions are also welcome (although no promises that anything will be added).
If you do use this for your own app, I’d love to hear from you.