kylebrowning / Waterwheel.swift

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

• [x] Session management
• [x] Basic Auth
• [x] Cookie Auth
• [x] Entity CRUD
• [x] Local caching
• [x] LoginViewController
• [x] AuthButton
• [x] Views integration into Table Views

Back to Top

Configuration

1. import waterwheel
2. (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.

Back to Top

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+

Back to Top