SwiftEntryKit – simple and easy to use iOS notifications/pop-ups open source library

Banners or Pop-Ups are called Entries.

• The entries are displayed in a separated UIWindow (of type EKWindow), so the user is able to navigate the app freely while entries are being displayed in a non intrusive manner.
• The kit offers some beautiful presets that can be themed with your app colors and fonts.
• Customization: Entries are highly customizable
  • Can be displayed either at the top, center, or the bottom of the screen.
  • Can be displayed within or outside the screen’s safe area.
  • Can be stylized: have a border, drop-shadow and round corners.
  • Their content’s and the screen’s background can be blurred, dimmed, colored or have a gradient style.
  • Transition animations are customizable – Entrance, Exit and Pop (by another entry).
  • The user interactions with the entry or the screen can be intercepted.
  • Entries have an optional rubber banding effect in panning.
  • Entries can be optionally dismissed using a simple swipe gesture.
  • Entries have display priority attribute. That means that an entry can be dismissed only be other entry with equal or higher priority.
  • Entries can be optionally injected with lifecycle events: will and did appear/disappear.
  • The status bar style is settable for the display duration of the entry.
  • SwiftEntryKit supports custom views as well.

You can either use the terminal or git client such as Source Tree. The zip file doesn’t contain a necessary dependency (QuickLayout).

Cloning the from github.com/huri000/Swi… also setups QuickLayout as submodule.

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ gem install cocoapodsCopy the code

To integrate SwiftEntryKit into your Xcode project using CocoaPods, specify it in your Podfile:

The source 'https://github.com/cocoapods/specs.git' platform: ios, '9.0' use_frameworks! Pod 'SwiftEntryKit', '0.4.2'Copy the code

Then, run the following command:

$ pod installCopy the code

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthageCopy the code

To integrate SwiftEntryKit into your Xcode project using Carthage, specify the following in your Cartfile:

Making "huri000 / SwiftEntryKit" = = 0.4.2Copy the code

No setup is needed! Each time you wish to display an entry, just create your view and initialize an EKAttributes struct. See also the preset usage example, and the example project. likewise:

// Customized view let customView = SomeCustomView() /* Do some customization on customView */ // Attributes struct that  describes the display, style, user interaction and animations of customView. var attributes = EKAttributes() /* Adjust preferable attributes */Copy the code

And then, just call:

SwiftEntryKit.display(entry: customView, using: attributes)Copy the code

The kit will replace the application main window with the EKWindow instance and display the entry.

Entries can be displayed above the application main window, above the status bar, above the alerts window or even have a custom level (UIWindowLevel).

For example, set the window level to normal, likewise:

attributes.windowLevel = .normalCopy the code

This causes the entry to appear above the application key window and below the status bar.

The display priority of the entry determines whether it dismisses other entries or be dismissed by them. An entry can be dismissed only by an entry with an equal or a higher display priority.

let highPriorityAttributes = EKAttributes()
highPriorityAttributes.displayPriority = .high

let normalPriorityAttributes = EKAttributes()
normalPriorityAttributes.displayPriority = .normal

// Display high priority entry
SwiftEntryKit.display(entry: view1, using: highPriorityAttributes)

// Display normal priority entry (ignored!)
SwiftEntryKit.display(entry: view2, using: normalPriorityAttributes)Copy the code

view2 won’t be displayed!

Constraints that tie the entry tightly to the screen contexts, for example: Height, Width, Max Width, Max Height, Additional Vertical Offset & Safe Area related info.

For example:

Ratio edge-so that the Ratio of the width edge has a Ratio of 0.9 of the screen’s width.

Let widthConstraint = EKAttributes. PositionConstraints. Edge. Thewire (value: 0.9)Copy the code

Intrinsic edge – signifies that the wanted height value is the content height – Decided by the entries vertical constraints

let heightConstraint = EKAttributes.PositionConstraints.Edge.intrinsicCopy the code

Create the entry size constraints likewise:

attributes.positionConstraints.size = .init(width: widthConstraint, height: heightConstraint)Copy the code

You can also set attributes.positionConstraints.maxSize in order to make sure the entry does not exceeds predefined limitations. This is useful on device orientation change.

Safe Area – can be used to override the safe area or to color it (More examples are in the example project) That snippet implies that the safe area insets should be kept and not be a part of the entry.

attributes.positionConstraints.safeArea = .empty(fillSafeArea: false)Copy the code

Vertical Offset – An additional offset that can be applied to the entry (Other than the safe area).

attributes.positionConstraints.verticalOffset = 10Copy the code

Keyboard Releation – used to bind an entry to the keyboard once the keyboard is displayed.

let offset = EKAttributes.PositionConstraints.KeyboardRelation.Offset(bottom: 10, screenEdgeResistance: 20)
let keyboardRelation = EKAttributes.PositionConstraints.KeyboardRelation.bind(offset: offset)
attributes.positionConstraints.keyboardRelation = keyboardRelationCopy the code

In the example above the entry’s bottom is tuned to have a 10pts offset from the top of the keyboard (while it shows) Because the entry’s frame might exceed the screen bounds, the user might not see all the entry – we wouldn’t want that. Therefore, an additional associated value has been added – screenEdgeResistance with value of 20pts. That is, to make sure that the entry remains within the bounds of the screen, and always visible to the user. The extreme situation might occur as the device orientation is landscape and the keyboard shows up (See example project form presets for more information).

Describes the entry behavior when it’s being scrolled, that is, dismissal by a swipe gesture and a rubber band effect much similar to a UIScrollView.

Disable the pan and swipe gestures on the entry:

attributes.scroll = .disabledCopy the code

Enable swipe and stretch and pullback with jolt effect:

attributes.scroll = .enabled(swipeable: true, pullbackAnimation: .jolt)Copy the code

Enable swipe and stretch and pullback with an ease-out effect:

attributes.scroll = .enabled(swipeable: true, pullbackAnimation: .easeOut)Copy the code

Enable swipe but disable stretch:

attributes.scroll = .edgeCrossingDisabled(swipeable: true)Copy the code

The device can produce a haptic feedback, thus adding an additional sensory depth to each entry.

The entry and the screen can have various background styles, such as blur, color, gradient and even an image.

The default value is .clear. This example implies clear background for both the entry and the screen:

attributes.entryBackground = .clear
attributes.screenBackground = .clearCopy the code

Colored entry background and dimmed screen background:

attributes.entryBackground = .color(color: .white)
attributes.screenBackground = .color(color: UIColor(white: 0.5, alpha: 0.5))Copy the code

Gradient entry background (diagonal vector):

let colors: [UIColor] = [.red, .green, .blue]
attributes.entryBackground = .gradient(gradient: .init(colors: colors, startPoint: .zero, endPoint: CGPoint(x: 1, y: 1)))Copy the code

Visual Effect entry background:

attributes.entryBackground = .visualEffect(style: .light)Copy the code

Round corners around the entry.

Only top left and right corners with radius of 10:

attributes.roundCorners = .top(radius: 10)Copy the code

Only bottom left and right corners with radius of 10:

attributes.roundCorners = .bottom(radius: 10)Copy the code

All corners with radius of 10:

attributes.roundCorners = .all(radius: 10)Copy the code

No round corners:

attributes.roundCorners = .noneCopy the code

Describes how the entry animates into and out of the screen.

• Each animation descriptor can have up to 3 types of animations at the same time. Those can be combined to a single complex one!
• Translation animation anchor can be explicitly set but it receives a default value according to position of the entry.

Example for translation from top with spring, scale in and even fade in as a single entrance animation:

Attributes. EntranceAnimation =. The init (translate: init (duration: 0.7, anchorPosition: top, spring: the init (damping: InitialVelocity: 0)), scale:.init(from: 0.6, to: 1, duration: 0.7), fade:.init(from: 0.8, to: 1, duration: 0.3))Copy the code

The status bar appearance can be modified during the display of the entry. In order to enable this feature, set View controller-based status bar appearance to NO in your project’s info.plist file.

Setting the status bar style is fairly simple:

Status bar becomes visible and gets a light style:

attributes.statusBar = .lightCopy the code

The status bar becomes hidden:

attributes.statusBar = .hiddenCopy the code

The status bar appearance is inferred from the previous context (won’t be changed):

attributes.statusBar = .inferredCopy the code

In case there is an already presenting entry with lower/equal display priority, the status bar will change it’s style When the entry is removed the status bar gets it’s initial style back.

EKAttributes’ interface is as follows:

public struct EKAttributes

    // Display
    public var windowLevel: WindowLevel
    public var position: Position
    public var displayPriority: DisplayPriority
    public var displayDuration: DisplayDuration
    public var positionConstraints: PositionConstraints

    // User Interaction
    public var screenInteraction: UserInteraction
    public var entryInteraction: UserInteraction
    public var scroll: Scroll
    public var hapticFeedbackType: NotificationHapticFeedback
    public var lifecycleEvents: LifecycleEvents

    // Theme & Style
    public var entryBackground: BackgroundStyle
    public var screenBackground: BackgroundStyle
    public var shadow: Shadow
    public var roundCorners: RoundCorners
    public var border: Border
    public var statusBar: StatusBar
    
    // Animations
    public var entranceAnimation: Animation
    public var exitAnimation: Animation
    public var popBehavior: PopBehavior
}Copy the code

// Generate top floating entry and set some properties var attributes = EKAttributes.topFloat attributes.entryBackground  = .gradient(gradient: .init(colors: [.red, .green], startPoint: .zero, endPoint: CGPoint(x: 1, y: 1))) Attributes =.animated(animation:.init(Duration: 0.3), scale:.init(from: 1, to: 0, duration: 0))) Attributes =.active(with:.init(color:.black, opacity: 0.5, radius: 10, offset: 0) .zero)) attributes.statusBar = .dark attributes.scroll = .enabled(swipeable: true, pullbackAnimation: .jolt) attributes.positionConstraints.maxSize = .init(width: .constant(value: UIScreen.main.minEdge), height: .intrinsic) let title = EKProperty.LabelContent(text: titleText, style: .init(font: titleFont, color: textColor)) let description = EKProperty.LabelContent(text: descText, style: .init(font: descFont, color: textColor)) let image = EKProperty.ImageContent(image: UIImage(named: imageName)! , size: CGSize(width: 35, height: 35)) let simpleMessage = EKSimpleMessage(image: image, title: title, description: description) let notificationMessage = EKNotificationMessage(simpleMessage: simpleMessage) let contentView = EKNotificationMessageView(with: notificationMessage) SwiftEntryKit.display(entry: contentView, using: attributes)Copy the code

As from version 0.4.0, View Controllers are supported As well

SwiftEntryKit.display(entry: customViewController, using: attributes)Copy the code

Inject a trailing closure to be executed after the entry dismissal.

SwiftEntryKit.dismiss {
    // Executed right after the entry has been dismissed
}Copy the code

Entries can be panned vertically (This ability can be enabled using the scroll attributes). Thefore it’s only natural that an entry can be dismissed using a swipe-like gesture.

Enable swipe gesture. When the swipe gesture fails (doesn’t pass the velocity threshold) ease it back.

attributes.scroll = .enabled(swipeable: true, pullbackAnimation: .easeOut)Copy the code

Enable swipe gesture. When the swipe gesture fails throw it back out with a jolt.

attributes.scroll = .enabled(swipeable: true, pullbackAnimation: .jolt)Copy the code

The PullbackAnimation values (duration, damping & initialSpringVelocity) can be customized as well.

Swipe	Jolt

SwiftEntryKit supports iOS 11.x.y and is backward compatible to iOS 9.x.y, so the status bar area is treated as same as the safe area in earlier iOS versions.

Unable to use example project – In case you are unable to install the example project please review this thread and the Example Project Installation section.