The Waterwheel Swift SDK provides classes to natively connect iOS, macOS, tvOS, and watchOS applications to Drupal 7 and 8.
Swift Shell Other

README.md

Waterwheel - Drupal SDK

Drupal version CocoaPods CocoaPods Carthage compatible Swift version

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.

FeaturesConfigurationUsageInstallationRequirements


Features in 4.x

  • Session management
  • Basic Auth
  • Cookie Auth
  • Entity CRUD
  • True entities
  • Local caching
  • LoginViewController
  • SignupViewController
  • AuthButton
  • 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://drupal-8-2-0-beta1.dd")

If 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 button 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 = {
    let vc = waterwheelLoginViewController()
    // 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)

Taking this one step furthure, waterwheel also provides a LoginViewController. You can subclass this controller and overwrite it however you want. For our purposes we will use the default implementation.

let loginButton = waterwheelAuthButton()
// When we press Login, lets show our Login view controller.
loginButton.didPressLogin = {
    // Lets build our default waterwheelLoginViewController.
    let vc = waterwheelLoginViewController()
    //Lets add our function that will be run when the request is completed.
    vc.loginRequestCompleted = { (success, error) in
        if (success) {
            // Do something related to a successfull login
            print("successfull login")
            self.dismissViewControllerAnimated(true, completion: nil)
        } else {
            print (error)
        }
    }
    vc.logoutRequestCompleted = { (success, error) in
        if (success) {
            print("successfull logout")
            // Do something related to a successfull logout
            self.dismissViewControllerAnimated(true, completion: nil)
        } else {
            print (error)
        }
    }
    // 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 items know whether you are logged in or out, they will always show the correct state of buttons. The UI is up to you, but at its default you get username, password and submit button.

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+
waterwheel version Drupal version Notes
4.x Drupal 8 (Swift)
3.x Drupal 8 (Obj-C)
2.x Drupal 6-7 (Obj-C) Requires Services module

Back to Top