Introduction

Popup Dialog is a simple, customizable popup dialog written in Swift.

Features

• Easy to use API with hardly any boilerplate code
• Convenient default view with image, title, message
• Supports custom view controllers
• Slick transition animations
• Fully themeable via appearance, including fonts, colors, corner radius, shadow, overlay color and blur, etc.
• Can be dismissed via swipe and background tap
• Objective-C compatible
• Works on all screens and devices supporting iOS 8.0+

Installation

Cocoapods

PopupDialog is available through CocoaPods. For best results with Swift 3, I recommend installing CocoaPods version 1.1.0 (which might be a prerelease as of this release). Simply add the following to your Podfile:

use_frameworks!target'<Your Target Name>'pod'PopupDialog','~> 0.5'

Please note that this version is compatiable with iOS8

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. A minimum version of 0.17 is required.

To install, simply add the following lines to your Cartfile:

github"Orderella/PopupDialog" ~> 0.5

Manually

If you prefer not to use either of the above mentioned dependency managers, you can integrate PopupDialog into your project manually by adding the files contained in the Classes folder to your project.

Example

You can find this and more example projects in the repo. To run it, clone the repo, and run pod install from the Example directory first.

import PopupDialog
// Prepare the popup assets
lettitle="THIS IS THE DIALOG TITLE"letmessage="This is the message section of the popup dialog default view"letimage=UIImage(named:"pexels-photo-103290")
// Create the dialog
letpopup=PopupDialog(title: title, message: message, image: image)
// Create buttons
letbuttonOne=CancelButton(title:"CANCEL"){print("You canceled the car dialog.")}letbuttonTwo=DefaultButton(title:"ADMIRE CAR"){print("What a beauty!")}letbuttonThree=DefaultButton(title:"BUY CAR", height:60){print("Ah, maybe next time :)")}
// Add buttons to dialog
// Alternatively, you can use popup.addButton(buttonOne)
// to add a single button
popup.addButtons([buttonOne, buttonTwo, buttonThree])
// Present dialog
self.present(popup, animated:true, completion:nil)

Usage

PopupDialog is a subclass of UIViewController and as such can be added to your view controller modally. You can initialize it either with the handy default view or a custom view controller.

Default Dialog

publicconvenienceinit(
title:String?,
message:String?,
image:UIImage?=nil,
buttonAlignment:UILayoutConstraintAxis=.vertical,
transitionStyle:PopupDialogTransitionStyle=.bounceUp,
gestureDismissal:Bool=true,
completion:(()->Void)?=nil)

The default dialog initializer is a convenient way of creating a popup with image, title and message (see image one and two).

Bascially, all parameters are optional, although this makes no sense at all. You want to at least add a message and a single button, otherwise the dialog can't be dismissed, unless you do it manually.

If you provide an image it will be pinned to the top/left/right of the dialog. The ratio of the image will be used to set the height of the image view, so no distortion will occur.

Custom View Controller

publicinit(
viewController:UIViewController,
buttonAlignment:UILayoutConstraintAxis=.vertical,
transitionStyle:PopupDialogTransitionStyle=.bounceUp,
gestureDismissal:Bool=true,
completion:(()->Void)?=nil)

You can pass your own view controller to PopupDialog (see image three). It is accessible via the viewController property of PopupDialog, which has to be casted to your view controllers class to access its properties. Make sure the custom view defines all constraints needed, so you don't run into any autolayout issues.

Buttons are added below the controllers view, however, these buttons are optional. If you decide to not add any buttons, you have to take care of dismissing the dialog manually. Being a subclass of view controller, this can be easily done via dismissViewControllerAnimated(flag: Bool, completion: (() -> Void)?).

Transition Animations

You can set a transition animation style with .BounceUp being the default. The following transition styles are available

publicenumPopupDialogTransitionStyle:Int{case bounceUp
case bounceDown
case zoomIn
case fadeIn
}

Button Alignment

Buttons can be distributed either .Horizontal or .Vertical, with the latter being the default. Please note distributing buttons horizontally might not be a good idea if you have more than two buttons.

publicenumUILayoutConstraintAxis:Int{case horizontal
case vertical
}

Gesture Dismissal

Gesture dismissal allows your dialog being dismissed either by a background tap or by swiping the dialog down. By default, this is set to true. You can prevent this behavior by setting gestureDismissal to false in the initializer.

Completion

This completion handler is called when the dialog was dismissed. This is especially useful for catching a gesture dismissal.

Default Dialog Properties

If you are using the default dialog, you can change selected properties at runtime:

// Create the dialog
letpopup=PopupDialog(title: title, message: message, image: image)
// Present dialog
self.present(popup, animated:true, completion:nil)
// Get the default view controller and cast it
// Unfortunately, casting is necessary to support Objective-C
letvc= popup.viewController as!PopupDialogDefaultViewController
// Set dialog properties
vc.image =UIImage(...)
vc.titleText ="..."
vc.messageText ="..."
vc.buttonAlignment =.horizontal
vc.transitionStyle =.bounceUp

Styling PopupDialog

Appearance is the preferred way of customizing the style of PopupDialog. The idea of PopupDialog is to define a theme in a single place, without having to provide style settings with every single instantiation. This way, creating a PopupDialog requires only minimal code to be written and no "wrappers".

This makes even more sense, as popup dialogs and alerts are supposed to look consistent throughout the app, that is, maintain a single style.

Dialog Default View Appearance Settings

If you are using the default popup view, the following appearance settings are available:

vardialogAppearance=PopupDialogDefaultView.appearance()
dialogAppearance.backgroundColor =UIColor.white
dialogAppearance.titleFont =UIFont.boldSystemFont(ofSize:14)
dialogAppearance.titleColor =UIColor(white:0.4, alpha:1)
dialogAppearance.titleTextAlignment =.center
dialogAppearance.messageFont =UIFont.systemFont(ofSize:14)
dialogAppearance.messageColor =UIColor(white:0.6, alpha:1)
dialogAppearance.messageTextAlignment =.center
dialogAppearance.cornerRadius =4
dialogAppearance.shadowEnabled =true
dialogAppearance.shadowColor =UIColor.black

Overlay View Appearance Settings

This refers to the view that is used as an overlay above the underlying view controller but below the popup dialog view. If that makes sense ;)

letoverlayAppearance=PopupDialogOverlayView.appearance()
overlayAppearance.color =UIColor.black
overlayAppearance.blurRadius =20
overlayAppearance.blurEnabled =true
overlayAppearance.liveBlur =false
overlayAppearance.opacity =0.7

Note

Turning on liveBlur, that is realtime updates of the background view, results in a significantly higher CPU usage /power consumption and is therefore turned off by default now. Choose wisely whether you need this feature or not ;)

Button Appearance Settings

The standard button classes available are DefaultButton, CancelButton and DestructiveButton. All buttons feature the same appearance settings and can be styled seperately.

varbuttonAppearance=DefaultButton.appearance()
// Default button
buttonAppearance.titleFont =UIFont.systemFont(ofSize:14)
buttonAppearance.titleColor =UIColor(red:0.25, green:0.53, blue:0.91, alpha:1)
buttonAppearance.buttonColor =UIColor.clear
buttonAppearance.separatorColor =UIColor(white:0.9, alpha:1)
// Below, only the differences are highlighted
// Cancel button
CancelButton.appearance().titleColor =UIColor.lightGray
// Destructive button
DestructiveButton.appearance().titleColor =UIColor.red

Moreover, you can create a custom button by subclassing PopupDialogButton. The following example creates a solid blue button, featuring a bold white title font. Separators are invisble.

publicfinalclassSolidBlueButton:PopupDialogButton{overridepublicfunc setupView(){
defaultFont =UIFont.boldSystemFont(ofSize:16)
defaultTitleColor =UIColor.white
defaultButtonColor =UIColor.blue
defaultSeparatorColor =UIColor.clear
super.setupView()}}

These buttons can be customized with the appearance settings given above as well.

Dark mode example

The following is an example of a Dark Mode theme. You can find this in the Example project AppDelegate, just uncomment it to apply the custom appearance.

// Customize dialog appearance
letpv=PopupDialogDefaultView.appearance()
pv.titleFont =UIFont(name:"HelveticaNeue-Light", size:16)!
pv.titleColor =UIColor.white
pv.messageFont =UIFont(name:"HelveticaNeue", size:14)!
pv.messageColor =UIColor(white:0.8, alpha:1)
// Customize the container view appearance
letpcv=PopupDialogContainerView.appearance()
pcv.backgroundColor =UIColor(red:0.23, green:0.23, blue:0.27, alpha:1.00)
pcv.cornerRadius =2
pcv.shadowEnabled =true
pcv.shadowColor =UIColor.black
// Customize overlay appearance
letov=PopupDialogOverlayView.appearance()
ov.blurEnabled =true
ov.blurRadius =30
ov.liveBlur =true
ov.opacity =0.7
ov.color =UIColor.black
// Customize default button appearance
letdb=DefaultButton.appearance()
db.titleFont =UIFont(name:"HelveticaNeue-Medium", size:14)!
db.titleColor =UIColor.white
db.buttonColor =UIColor(red:0.25, green:0.25, blue:0.29, alpha:1.00)
db.separatorColor =UIColor(red:0.20, green:0.20, blue:0.25, alpha:1.00)
// Customize cancel button appearance
letcb=CancelButton.appearance()
cb.titleFont =UIFont(name:"HelveticaNeue-Medium", size:14)!
cb.titleColor =UIColor(white:0.6, alpha:1)
cb.buttonColor =UIColor(red:0.25, green:0.25, blue:0.29, alpha:1.00)
cb.separatorColor =UIColor(red:0.20, green:0.20, blue:0.25, alpha:1.00)

I can see that there is room for more customization options. I might add more of them over time.

Screen sizes and rotation

Rotation and all screen sizes are supported. However, the dialog will never exceed a width of 340 points. This way, the dialog won't be too big on devices like iPads. However, landscape mode will not work well if the height of the dialog exceeds the width of the screen.

Working with text fields

If you are using text fields in your custom view controller, popup dialog makes sure that the dialog is positioned above the keybord whenever it appears. You can opt out of this behaviour by setting keyboardShiftsView to false on a PopupDialog.

Testing

PopupDialog exposes a nice and handy method that lets you trigger a button tap programmatically:

publicfunc tapButtonWithIndex(index:Int)

Other than that, PopupDialog unit tests are included in the root folder.

Objective-C

PopupDialog can be used in Objective-C projects as well. Here is a basic example:

#import<PopupDialog/PopupDialog-Swift.h>
PopupDialog *popup = [[PopupDialog alloc] initWithTitle:@"TEST"message:@"This is a test message!"image:nilbuttonAlignment:UILayoutConstraintAxisHorizontal
transitionStyle:PopupDialogTransitionStyleBounceUp
gestureDismissal:YEScompletion:nil];
CancelButton *cancel = [[CancelButton alloc] initWithTitle:@"CANCEL"dismissOnTap:YESaction:^{
// Default action
}];
DefaultButton *ok = [[DefaultButton alloc] initWithTitle:@"OK"dismissOnTap:YESaction:^{
// Ok action
}];
[popup addButtons: @[cancel, ok]];
[selfpresentViewController:popup animated:YEScompletion:nil];

Requirements

Minimum requirement is iOS 8.0. This dialog was written with Swift 3, for 2.2 compatible versions please specify the X release.

Changelog

• 0.5.4 Fixed bug where blur view would reveal hidden layer
  Improved view controller lifecycle handling
  Scroll views can now be used with gesture dismissal
• 0.5.3 Fixed memory leak with custom view controllers
  Added UI automation & snapshot tests
• 0.5.2 Fixed image scaling for default view
• 0.5.1 Introduced custom button height parameter
  Reintroduced iOS8 compatibility
• 0.5.0 Swift 3 compatibility / removed iOS8
• 0.4.0 iOS 8 compatibility
• 0.3.3 Fixes buttons being added multiple times
• 0.3.2 Dialog repositioning when interacting with keyboard
  Non dismissable buttons option
  Additional completion handler when dialog is dismissed
• 0.3.1 Fixed Carthage issues
• 0.3.0 Objective-C compatibility
• 0.2.2 Turned off liveBlur by default to increase performance
• 0.2.1 Dismiss via background tap or swipe down transition
• 0.2.0 You can now pass custom view controllers to the dialog. This introduces breaking changes.
• 0.1.6 Defer button action until animation completes
• 0.1.5 Exposed dialog properties
  (titleText, messageText, image, buttonAlignment, transitionStyle)
• 0.1.4 Pick transition animation style
• 0.1.3 Big screen support
  Exposed basic shadow appearance
• 0.1.2 Exposed blur and overlay appearance
• 0.1.1 Added themeing example
• 0.1.0 Intitial version

Author

Martin Wildfeuer, mwfire@mwfire.de for Orderella Ltd., orderella.co.uk
You might also want to follow us on Twitter, @theMWFire | @Orderella

Thank you

Thanks to everyone who uses, enhances and improves this library, especially the contributors.

Images in the sample project

The sample project features two images from Markus Spiske raumrot.com:
Vintage Car One | Vintage Car Two
Thanks a lot for providing these :)

License

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