LKAlertController

An easy to use UIAlertController builder for swift

Code Quality Rank: L5

Programming language: Swift

License: MIT License

Tags: UI     Alerts    

Latest version: v1.12.2

README

LKAlertController

An easy to use UIAlertController builder for swift

Features

• Short and simple syntax for creating both Alerts and ActionSheets from UIAlertController
• String together methods to build more complex alerts and action sheets

Basic Usage

Alert

Alert(title: "Title", message: "Message")
    .addAction("Cancel")
    .addAction("Delete", style: .Destructive, handler: { _ in
        //Delete the object
    }).show()

Action Sheet

ActionSheet(title: "Title", message: "Message")
    .addAction("Cancel")
    .addAction("Delete", style: .Destructive, handler: { _ in
        //Delete the object
    }).show()

Detailed Usage

There are two seperate classes for creating UIAlertControllers, Alert, and ActionSheet. These are used to simplify the creation of the controller. Both can be initialized with or without both a title and message.

Alert()
ActionSheet()

Alert(title: "My title")
ActionSheet(title: "My title")

Alert(message: "My message")
ActionSheet(message: "My message")

Alert(title: "My title", message: "My message")
ActionSheet(title: "My title", message: "My message")

Add various actions to the controller using addAction. By default the button will be styled Cancel, but this can be configured on a per button basis, along with the handler that is called if the button is clicked. The possible styles are Cancel, Default, and Destructive. These methods can be strung together to add more buttons to the controller.

ActionSheet()
    .addAction("Cancel")
    .addAction("Save", style: .Default) {
        saveTheObject()
    }
    .addAction("Delete", style: Destructive) {
        deleteTheObject()
    }

The controller can be presented by calling show(). It will be animated by default.

Alert()
    .addAction("Okay")
    .show()

ActionSheet()
    .addAction("Delete", style: .Destructive) {
        delete()
    }
    .addAction("Cancel")
    .show(animated: true) {
        controllerWasPresented()
    }

Alert Specific Configuration

There is a shortcut on alerts to show with an okay button: showOkay

Alert(title: "Stuff has happened").showOkay()

You can also add your own shortcut show method. The following adds a showNevermind button that adds a Nevermind button and shows the alert.

extension Alert {
    ///Shortcut method for adding a nevermind button and showing the alert
    public func showNevermind() {
        addAction("Nevermind", style: .Cancel, preferredAction: false, handler: nil)
        show()
    }
}

Text fields can also be added to alerts. To add a text field, initialize a text field first, and configure it, then pass it in with the alert. Note that text fields must be initialized as var rather than let

var textField = UITextField()
textField.placeholder = "Password"
textField.secureTextEntry = true

Alert().addTextfield(&textField).showOkay()

You can also configure the preferredAction property on an alert. This will highlight the text of the action, and pressing the return key on a physical keyboard will trigger this action.

Alert()
    .addAction("Okay", style: .Default, preferredAction: true)
    .show()

ActionSheet Specific Configuration

If presenting on iPad, ActionSheets need to be configured with where it is presenting from. This is done by using the setBarButtonItem or setPresentingSource function. Note that this has no effect on iPhone, so it is safe, and recommended, to call this method if your app supports both iPad and iPhone.

ActionSheet()
    .addAction("Delete", style: .Destructive) {
        delete()
    }
    .addAction("Cancel")
    .setBarButtonItem(navigationController.rightBarButtonItem)
    .show(animated: true) {
        controllerWasPresented()
    }

ActionSheet()
    .addAction("Delete", style: .Destructive) {
        delete()
    }
    .addAction("Cancel")
    .setPresentingSource(buttonThatWasPressed)
    .show(animated: true) {
        controllerWasPresented()
    }

Testing

You can add an override for the show method to make it easy to add unit tests for your alerts.

func testDeleteOpensConfirmationAlert() {
    let expectation = expectationWithDescription("Show override")

    LKAlertController.overrideShowForTesting { (style, title, message, actions, fields) -> Void in 

        XCTAssertEquals(title, "Are you sure you want to delete?", "Alert title was incorrect")

        expectation.fulfill()
    }

    model.delete()

    //If the override is never called, and the expectation is not fulfilled, the test will fail
    waitForExpectations(0.5, handler: nil)
}

This will allow you to test the controller was presented as well as the title, message, actions and fields of the alert or action sheet.

Installation

LKAlertController is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "LKAlertController"

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate LKAlertController into your Xcode project using Carthage, specify it in your Cartfile:

github "lightningkite/LKAlertController"

Run carthage update to build the framework and drag the built LKAlertController.framework into your Xcode project.

Issues Questions and Contributing

Have an issue, or want to request a feature? Create an issue in github.

Want to contribute? Add yourself to the authors list, and create a pull request.

Author

Erik Sargent, [email protected]

License

LKAlertController is available under the MIT license. See the LICENSE file for more info.