Waterwheel Swift SDK for Drupal
Waterwheel makes using Drupal as a backend with iOS, macOS, tvOS, or watchOS enjoyable by combining the most used features of Drupal's API's in one SDK. - Formerly known as Drupal iOS SDK.
Features • Configuration • Usage • Installation • Requirements
Features in 4.x
- Session management
- Basic Auth
- Cookie Auth
- Entity CRUD
- Local caching
- LoginViewController
- AuthButton
- Views integration into Table Views
Configuration
import waterwheel- (Optional) If you're not using HTTPS you will have to enable the NSAppTransportSecurity
Usage
The code below will give you access to the baseline of features for communicating to a Drupal site.
// Sets the URL to your Drupal site.
waterwheel.setDrupalURL("http://waterwheel-swift.com")
It is important to note that waterwheel makes heavy uses of Closures, which allows us to pass functions as returns, or store them in variables.
Login
The code below will set up Basic Authentication for each API call.
// Sets HTTPS Basic Authentication Credentials.
waterwheel.setBasicAuthUsernameAndPassword("test", password: "test2");
If you do not want to use Basic Auth, and instead use a cookie, waterwheel provides an authentication method for doing so. Sessions are handled for you, and will restore state upon closing an app and reopening it.
waterwheel.login(usernameField.text!, password: passwordField.text!) { (success, response, json, error) in
if (success) {
print("logged in")
} else {
print("failed to login")
}
}
Waterwheel provides a waterwheelAuthButton to place anywhere in your app. The code below is iOS specific because of its dependence on UIKit.
let loginButton = waterwheelAuthButton()
// When we press Login, lets show our Login view controller.
loginButton.didPressLogin = {
waterwheel.login(usernameField.text!, password: passwordField.text!) { (success, response, json, error) in
if (success) {
print("successful login")
} else {
print("failed to login")
}
}
}
loginButton.didPressLogout = { (success, error) in
print("logged out")
}
self.view.addSubview(loginButton)
Taking this one step further, waterwheel also provides a waterwheelLoginViewController. You can subclass this controller and overwrite if needed. For our purposes we will use the default implementation.
First, we build our waterwheelLoginViewController and set our loginRequestCompleted and logoutRequestCompleted closures:
// Lets build our default waterwheelLoginViewController.
let vc = waterwheelLoginViewController()
//Lets add our closure that will be run when the request is completed.
vc.loginRequestCompleted = { (success, error) in
if (success) {
// Do something related to a successful login
print("successful login")
self.dismissViewControllerAnimated(true, completion: nil)
} else {
print (error)
}
}
vc.logoutRequestCompleted = { (success, error) in
if (success) {
print("successful logout")
// Do something related to a successful logout
self.dismissViewControllerAnimated(true, completion: nil)
} else {
print (error)
}
}
Once that is done we can now tell our waterwheelAuthButton what to do when someone presses Login. Of course this can all be handled manually in your own implementation, but for our purposes, were just using what waterwheel provides.
Here we instantiate a new waterwheelAuthButton and tell it what we want to happen when someone presses login, and logout.
let loginButton = waterwheelAuthButton()
// When we press Login, lets show our Login view controller.
loginButton.didPressLogin = {
// Lets Present our Login View Controller since this closure is for the loginButton press
self.presentViewController(vc, animated: true, completion: nil)
}
loginButton.didPressLogout = { (success, error) in
print("logged out")
}
self.view.addSubview(loginButton)
Because these two Views know whether you are logged in or out, they will always show the correct state of buttons(Login, or Logout) and perform the approriate actions. The UI is up to you, but at its default you get username, password, submit, and cancel button. With all that said, you can ingore these classes and use the methods that waterwheel provides and deeply integrate into your own UI.
Node Methods
Get
// Get Node 36
waterwheel.nodeGet(nodeId: "36", params: nil, completionHandler: { (success, response, json, error) in
print(response)
})
Create/post
//build our node body
let body = [
"type": [
[
"target_id": "article"
]
],
"title": [
[
"value": "Hello World"
]
],
"body": [
[
"value": "How are you?"
]
]
]
// Create a new node.
waterwheel.entityPost(entityType: .Node, params: body) { (success, response, json, error) in
if (success) {
print(response)
} else {
print(error)
}
}
Update/Put/PATCH
// Update an existing node
waterwheel.nodePatch(nodeId: "36", node: body) { (success, response, json, error) in
print(response);
}
Delete
// Delete an existing node
waterwheel.nodeDelete(nodeId: "36", params: nil, completionHandler: { (success, response, json, error) in
print(response)
})
Entity Requests
Since Node is rather specific, Watherweel provides entity methods as well for all entityTypes
Entity Get
waterwheel.entityGet(entityType: .Node, entityId: "36", params: params, completionHandler: completionHandler)
Entity Post
waterwheel.sharedInstance.entityPost(entityType: .Node, params: node, completionHandler: completionHandler)
Entity Patch
waterwheel.entityPatch(entityType: .Node, entityId: "36", params: nodeObject, completionHandler: completionHandler)
Entity Delete
waterwheel.entityDelete(entityType: .Node, entityId: entityId, params: params, completionHandler: completionHandler)
Installation
Waterwheel offers two installations paths. Pick your poison!
Installation
CocoaPods
If you're using CocoaPods, just add this line to your Podfile:
pod 'waterwheel'
Install by running this command in your terminal:
pod install
Then import the library in all files where you use it:
import waterwheel
Carthage
Just add to your Cartfile:
github "acquia/waterwheel-swift"
Run carthage update to build the framework and drag the built waterwheel.framework into your Xcode project.
Communication
- If you need help, use Stack Overflow. (Tag 'waterwheel-swift')
- If you found a bug, open an issue.
- If you have a feature request, open an issue.
- If you want to contribute, submit a pull request.
Drupal Compatibility
The framework is tracking Drupal 8. As new features come out in 8, they will be added ASAP. Since Drupal 7 and Drupal 8 are completely different in terms of API's, you will need to use the correct version of waterwheel depending on your Drupal version.
Requirements
- iOS 8.0+ / Mac OS X 10.9+ / tvOS 9.0+ / watchOS 2.0+
- Xcode 7.3+
| waterwheel version | Drupal Version |
|---|---|
| 4.x | Drupal 8 (Swift) |
| 3.x | Drupal 8 (Obj-C) |
| 2.x | Drupal 6-7 (Obj-C) |
74 Nov 3, 2022
955 Dec 12, 2022
2 Apr 5, 2022
11 Jan 22, 2022
95 Sep 9, 2022
107 Nov 8, 2022
19 Dec 9, 2022
19 Jun 28, 2022
260 Dec 22, 2022
171 Jun 18, 2022
74 Dec 2, 2020
2.4k Dec 30, 2022
3 Aug 16, 2022
5 Oct 28, 2022
124 Nov 17, 2022
52 Jul 11, 2019
132 Aug 10, 2022
100 Jan 6, 2023
105 Nov 16, 2022