PleaseHold

Quick and easy progress UIView to place in your app.

What is PleaseHold?

In the moments when you need to show a blocking progress UIView in your app, PleaseHold is a quick way to put one in your app. Configured with default settings that will work for most use cases, but customizable enough to cover more. Do us all a favor, and avoid blocking views as much as you can 😉.

Why use PleaseHold?

• Swift API
• Lightweight. Zero dependencies.
• UI testing friendly.
• Setup with default values that should work for 95% of your use cases. Customizable for those other cases.
• Full test suite.
• Full documentation.

I recommend you check out 2 other libraries that work nicely with PleaseHold: Empty and Swapper.

Installation

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

pod 'PleaseHold', '~> version-here'

Replace version-here with: as this is the latest version at this time.

Getting started

• Create an instance of PleaseHoldView in your UIViewController. You can do this with Storyboard by adding a UIView to Storyboard and setting the UIView class to PleaseHoldView, or create an instance in your Swift code:

let pleaseHoldView: PleaseHoldView = {
    let view = PleaseHoldView()
    view.title = nil // title is optional 
    view.message = nil // message is optional 
    view.translatesAutoresizingMaskIntoConstraints = false    
    return view
}()

• Add the PleaseHoldView to your UIViewController. Pretty simple.

If you want to change the text of the title or message UILabels, you can change them at runtime:

pleaseHoldView.title = "New title"
pleaseHoldView.message = "New message"

Or, if you want to hide one of the labels, you can just set nil:

pleaseHoldView.title = nil 
pleaseHoldView.message = nil 

Configure PleaseHold

PleaseHold works great without any configuration necessary. However, if you wish to customize it yourself, you can.

If you want to change the default values of all instances of PleaseHold in your app, change the values in the default singleton:

PleaseHold.defaultConfig.viewPadding = 10.0

Or, you can configure 1 single instance of PleaseHold:

let pleaseHoldView = PleaseHoldView()
pleaseHoldView.config.newTitleLabel = {
    let label = PleaseHoldViewConfig.defaultTitleLabel
    label.textColor = .blue
    return label
}
pleaseHoldView.title = "Set title here, it will have blue text color!"

To make re-useable configurations for PleaseHoldView, it's recommended to create an PleaseHoldViewConfigPresent:

/// Convenient set of `UIView`s that are dark in color. Great for light colored backgrounds.
public struct DarkPleaseHoldViewConfigPreset: PleaseHoldViewConfigPreset {
    /// Dark colored title label.
    public var titleLabel: UILabel {
        let label = PleaseHoldViewConfig.defaultTitleLabel
        label.textColor = .darkText
        return label
    }

    /// Dark colored message label.
    public var messageLabel: UILabel {
        let label = PleaseHoldViewConfig.defaultMessageLabel
        label.textColor = .darkText
        return label
    }

    /// Dark colored activity indicator.
    public var activityIndicator: UIActivityIndicatorView {
        let indicator = PleaseHoldViewConfig.defaultActivityIndicator
        indicator.style = .gray
        return indicator
    }
}

let pleaseHoldView = PleaseHoldView()
pleaseHoldView.config = DarkPleaseHoldViewConfigPreset().config

For convenience, PleaseHold comes with a light and dark colored present: DarkPleaseHoldViewConfigPreset and LightPleaseHoldViewConfigPreset that you can use or extend.

There are many things you can configure for PleaseHold. For a list of all the configuration options, view the docs on PleaseHoldViewConfig

Example

PleaseHold comes with an example app you can use to play with the library. To run the example project, clone the repo, and run pod install from the Example directory first. Then, open the workspace in XCode.

Development

PleaseHold is a pretty simple CocoaPods library project. Follow the directions below for the optimal development experience.

• Install cocoapods/gems and setup workspace:

$> bundle install
$> cd PleaseHold/Example
$> pod install

• Setup git hooks via overcommit to run misc tasks for you when using git.

$> overcommit --install

Author

• Levi Bostian - GitHub, Twitter, Website/blog

Contribute

PleaseHold is open for pull requests. Check out the list of issues for tasks I am planning on working on. Check them out if you wish to contribute in that way.

Want to add features to PleaseHold? Before you decide to take a bunch of time and add functionality to the library, please, create an issue stating what you wish to add. This might save you some time in case your purpose does not fit well in the use cases of PleaseHold.

License

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