BulletinBoard：在底部卡片式显示公告信息及交互按钮

BulletinBoard is an iOS library that generates and manages contextual cards displayed at the bottom of the screen. It is especially well suited for quick user interactions such as onboarding screens or configuration.

It has an interface similar to the cards displayed by iOS for AirPods, Apple TV configuration and NFC tag scanning.

It has built-in support for accessibility features such as VoiceOver and Switch Control.

Here are some screenshots showing what you can build with BulletinBoard:

Requirements

iOS 9 and later
Swift 3.2 and later

Demo

A demo application is included in the BulletinBoard workspace. It demonstrates how to:

integrate the library (setup, data flow)
create standard page cards
create custom page subclasses to add features
create custom cards from scratch

Build and run the Instanimal scheme to use it.

Here's a video showing it in action:

Installation

BulletinBoard is available via CocoaPods and Carthage.

CocoaPods

To install BulletinBoard using CocoaPods, add this line to your Podfile:

pod "BulletinBoard"

Carthage

To install BulletinBoard using Carthage, add this line to your Cartfile:

github "alexaubry/BulletinBoard"

Usage

The Basics

The BulletinManager class generates, manages and displays bulletin cards. Cards are created using bulletin items. Bulletin items are objects that conform to the BulletinItem protocol.

The library provides a standard item type: PageBulletinItem. If you need to customize the items, you can override this class, or create new item types from scratch.

Displaying Bulletins

To display bulletins you first need to create the root item to display (explained in the next sections).

With this root item, you need to create a BulletinManager. We recommend putting it in the view controller that will display the bulletin.

class ViewController: UIViewController {

    lazy var bulletinManager: BulletinManager = {

        let rootItem: BulletinItem = // ... create your item here
        return BulletinManager(rootItem: rootItem)

    }()

}

To present your bulletin, call this method:

bulletinManager.prepare()
bulletinManager.presentBulletin(above: self)

Always call prepare() before calling presentBulletin()! Failure to do so will cause a precondition failure (TL;DR your app will crash).

For the case of onboarding, you can call it in viewWillAppear(animated:) after checking if the user has already completed onboarding.

Creating Page Items

You can create standard page items using the PageBulletinItem class.

It takes care of generating a user interface with standard components:

a title (required)
an icon image (should be 128x128px or less)
a description text
a large action button
a smaller alternative button

For example, this interface was created using a PageBulletinItem:

To recreate this interface, use this code:

let page = PageBulletinItem(title: "Push Notifications")
page.image = UIImage(named: "...")

page.descriptionText = "Receive push notifications when new photos of pets are available."
page.actionButtonTitle = "Subscribe"
page.alternativeButtonTitle = "Not now"

If you omit an optional property, the page won't generate a view for it. For instance, if you set alternativeButtonTitle to nil, the card won't display an alternative button.

Customizing the Appearance

Colors

You can customize the colors on the page by using the interfaceFactory property.

This property references a BulletinInterfaceFactory, which is responsible for generating the standard components (more on this later).

There are two properties that you can change:

tintColor - the tint color of the buttons (defaults to iOS blue)
actionButtonTitleColor - the color of action button titles

You need to set these before you present / push the item. Changing them after presentation will have no effect.

Example

page.interfaceFactory.tintColor = UIColor(red: 0.294, green: 0.85, blue: 0.392, alpha: 1) // green
page.interfaceFactory.actionButtonTitleColor = .white

This produces a card with the following appearance:

Handling Button Taps

To handle taps on buttons, set a closure for these properties:

actionHandler - called when the action button is tapped.
alternativeHandler - called when the alternative button is tapped.

page.actionHandler = { (item: PageBulletinItem) in
    print("Action button tapped")
}

This prints "Action button tapped" when the action button is tapped.

page.alternativeHandler = { (item: PageBulletinItem) in
    print("Alternative button tapped")
}

This prints "Alternative button tapped" when the alternative button is tapped.

Use these handlers as an opportunity to change the presented item, dismiss the bulletin and/or pass data to your model.

Changing the Presented Item

The BulletinItem protocol exposes a manager property that is set when the item is currently being displayed by a manager.

You can use it to interact with the presented bulletin. Call:

manager?.popItem() to go back to the previous item
manager?.popToRootItem() to go back to the first item
manager?.push(item:) with a BulletinItem to present a new item
manager?.dismissBulletin(animated:) to dismiss the bulletin

You need to call these methods from the main thread. Never force unwrap manager, as this property will be unset as soon as the item is removed from the bulletin.

It is also possible to set the nextItem property to the BulletinItem that should be displayed next and call the displayNextItem() method when you want to display it.

For instance, to present a new card when the user taps the action button:

page.nextItem = makeLocationPage() // Creates a new PageBulletinItem

page.actionHandler = { (item: PageBulletinItem) in
    item.displayNextItem()
}

This creates the following interaction:

If you need to perform a task between the moment the user taps a button and the moment you'll be able to change the presented item, you can call displayActivityIndicator() method on the item manager to hide the current card and display an activity indicator.

This is especially useful if you need to fetch data from a server (in-app purchase price, subscription status, ...) or save data (e.g. Core Data).

Once your task is finished, call one of the methods described in Changing the Presented Item.

Example:

page.actionHandler = { (item: PageBulletinItem) in
    item.manager?.displayActivityIndicator()
    // do your task
    // ...
    // when your task is finished, transition to the appropriate bulletin item
    item.displayNextItem()
}

This creates the following interaction:

Dismissal

If you set the isDismissable property to true, the user will be able to dismiss the bulletin by tapping outside of the card or by swiping the card down.

You should set this property to true for the last item.

Creating Custom Items

To create custom bulletin items, create a class that implements the BulletinItem protocol. To learn with a concrete example, you can read the implementation of PageBulletinItem.

Conforming to `BulletinItem`

To conform to this protocol, you need to add the required properties and implement two methods:

`makeArrangedSubviews()`

This method should return all the elements to display on the card.

Please note that the alpha and isHidden properties will be ignored.

`tearDown()`

In this method, clear all the resources allocated for the item (such as notification observers or button targets). After this method is called, the manager will be set to nil and the arranged subviews will be hidden and removed from the card.

Generating Standard Views

Even though you are creating a custom card, you may still want to display some standard elements, such as title labels or action buttons.

To generate standard elements, use the methods of BulletinInterfaceFactory:

makeTitleLabel() to create a title label
makeDescriptionLabel(isCompact:) to create a description label
makeActionButton(title:) to create an action button
makeAlternativeButton(title:) to create an alternative button
makeGroupStack(spacing:) to create a vertical stack view with the given spacing

Internals

BulletinBoard uses stack views and Auto Layout to display and manage cards. It automatically adapts to changes in width and height. iPad and iPhone X are supported out of the box.

If you are interested in learning how it works in more details, look at the implementation of BulletinManager, BulletinViewController and BulletinInterfaceFactory.

Contributing

Thank you for your interest in the project! Contributions are welcome and appreciated.

Make sure to read these guides before getting started:

Apps Using BulletinBoard

Feel free to submit a PR if you’re using this library in your apps.

Author

Written by Alexis Aubry. You can find me on Twitter.

License

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