Message Banner

This library provides an easy to use and fully customizable class to show notifications views on top/bottom/center of the screen.

The messages banners are regrouped in 4 different type : Error, Warning, Message and Success.

Each different type of banner can have different and fully customizable appearance and behavior. (See configuration section)

Each banner can show a title, a subtitle, an image and a button.

ScreenShots

Installation

Manually

Dependency :

The project use HexColors and FXBlurView You need to also install them manually. Please consult their installation requirement on their github pages.

MBLMessageBanner manual installation

Download Message banner project. You can download it directly from his github page
or via the command line :

$ git clone https://github.com/Loadex/Message-Banner.git

Drag the Message Banner folder into your project.

Quick Start Guide

Add the import to the top of classes that will use it. :

#import <MBLMessageBanner.h>

To show a basic notification use one of the following call :

[MBLMessageBanner showMessageBannerInViewController:aViewController
                                           title:@"aTitle"
                                        subtitle:@"aSubtitle"];

// ------------------------- OR -------------------------

    [MBLMessageBanner showMessageBannerInViewController:self
                                               title:@"aTitle"
                                            subtitle:@"aSubtitle"
                                               image:[UIImage imageNamed:@"icon.png"]
                                                type:MBLMessageBannerTypeMessage
                                            duration:MBLMessageBannerDurationDefault
                              userDissmissedCallback:^(MBLMessageBannerView *bannerView) {
                                  return;
                              }
                                         buttonTitle:@"BtnTitile"
                           userPressedButtonCallback:^(MBLMessageBannerView *banner) {
                                  return;
                              }
                                          atPosition:MBLMessageBannerPositionTop
                                canBeDismissedByUser:YES delegate:self];

Class documentation

MBLMessageBanner class documentation

The MBLMessageBanner class provide the following methods

+ (void)setDefaultViewController:(UIViewController *)aViewController;

Allow you to set a default view controller where the banners will be attached.
Default value : UIApplication sharedApplication].keyWindow.rootViewController

+ (void)setMessageBannerDelegate:(id<MBLMessageBannerDelegate>)aDelegate;

Allow to set the delegate of MBLMessageBanner class
See delegate documentation

+ (void)showMessageBannerInViewController:(UIViewController *)viewController
                                    title:(NSString *)title
                                 subtitle:(NSString *)subtitle;

+ (void)showMessageBannerInViewController:(UIViewController *)viewController
                                    title:(NSString *)title
                                 subtitle:(NSString *)subtitle
                               atPosition:(MBLMessageBannerPosition)messagePosition;

+ (void)showMessageBannerInViewController:(UIViewController *)viewController
                                    title:(NSString *)title
                                 subtitle:(NSString *)subtitle
                                     type:(MBLMessageBannerType)type
                               atPosition:(MBLMessageBannerPosition)messagePosition;

+ (void)showMessageBannerInViewController:(UIViewController *)viewController
                                    title:(NSString *)title
                                 subtitle:(NSString *)subtitle
                                     type:(MBLMessageBannerType)type
                                 duration:(NSTimeInterval)duration
                               atPosition:(MBLMessageBannerPosition)messagePosition;

+ (void)showMessageBannerInViewController:(UIViewController *)viewController
                                    title:(NSString *)title
                                 subtitle:(NSString *)subtitle
                                     type:(MBLMessageBannerType)type
                                 duration:(NSTimeInterval)duration
                   userDissmissedCallback:(void (^)(MBLMessageBannerView* bannerView))userDissmissedCallback
                               atPosition:(MBLMessageBannerPosition)messagePosition
                     canBeDismissedByUser:(BOOL)dismissingEnabled;

+ (void)showMessageBannerInViewController:(UIViewController *)viewController
                                    title:(NSString *)title
                                 subtitle:(NSString *)subtitle
                                    image:(UIImage *)image
                                     type:(MBLMessageBannerType)type
                                 duration:(NSTimeInterval)duration
                   userDissmissedCallback:(void (^)(MBLMessageBannerView* bannerView))userDissmissedCallback
                               atPosition:(MBLMessageBannerPosition)messagePosition
                     canBeDismissedByUser:(BOOL)dismissingEnabled;

+ (void)showMessageBannerInViewController:(UIViewController *)viewController
                                   title:(NSString *)title
                                subtitle:(NSString *)subtitle
                                   image:(UIImage *)image
                                    type:(MBLMessageBannerType)type
                                duration:(NSTimeInterval)duration
                                userDissmissedCallback:(void (^)(MBLMessageBannerView* bannerView))userDissmissedCallback
                             buttonTitle:(NSString *)buttonTitle
                          userPressedButtonCallback:(void (^)(MBLMessageBannerView* banner))userPressedButtonCallback
                              atPosition:(MBLMessageBannerPosition)messagePosition
                    canBeDismissedByUser:(BOOL)dismissingEnabled
                                 delegate:(id <MBLMessageBannerDelegate>)aDelegate;


+ (void)showMessageBanner:(MBLMessageBannerView *)messageBannerView;

Add a new MBLMessageBannerView to be displayed. Each MBLMessageBannerView is shown on the screen alone. If multiple calls, the MBLMessageBanner will show it when the previous message banner views disappeared.
Parameters description

• viewController: The view controller to show the message banner in. Can also be a UINavigationController. If nil, will use the default view controller instead.
• title: The title in the message banner view.
• subtitle: The subtitle in the message banner view.
• image: The left image showed in the message banner view.
• type: The message banner view type (See type section for available values). The message type allow to load the correct design in the design configuration file. (See configuration file section)
• duration: The message banner displaying duration in seconds. (See duration section for custom values)
• userDissmissedCallback: The block that should be executed when a user dismiss a message banner. (see dismiss gestures section to see possible dismiss gestures)
• buttonTittle: The title of the button. If set will allow a button to be created otherwise the message banner won't have a button.
• userPressedButtonCallback: The block that should be executed when a user hit the button if not nil.
• messagePosition: The message position on the viewController. (see position section to see possible positions)
• dismissingEnabled: Enable or disable the user dismissing methods on the message banner view.
• aDelegate: Set the delegate of the message banner (See delegate documentation to see available delegate methods)
• messageBannerView: An existing instance of a MessageBannerView to show next or instantly in not any are showed.

+ (BOOL) hideMessageBanner;
+ (BOOL) hideMessageBannerWithCompletion:(void (^)())completion;

Hide the currently displayed message banner
Parameters description

• completion: The block that should be executed when the message banner is hidden.
  Return value
• BOOL: Return YES if a message banner has been dismissed, NO otherwise.

MBLMessageBannerView class documentation

The MBLMessageBannerView class provide the following methods:

+ (BOOL)addMessageBannerDesignFromFileNamed:(NSString *)file;

Load a custom message banner design file.
Parameters description

• file:The name of the JSON config file. (See design configuration file section for syntax)
  Return value: YES if the file is corretly loaded. NO otherwise.

Delegate methods

The message banner class implements a delegate protocol with the following optional methods:

- (void)messageBannerViewWillAppear:(MBLMessageBannerView *)messageBanner;
- (void)messageBannerViewDidAppear:(MBLMessageBannerView *)messageBanner;
- (void)messageBannerViewWillDisappear:(MBLMessageBannerView *)messageBanner;
- (void)messageBannerViewDidDisappear:(MBLMessageBannerView *)messageBanner;

Parameters description

• messageBanner The message banner about to be displayed/hidden

NSNotifications

The MBLMessageBanner class also send signals when the message banner is about or did appear/disappear. Each notification is directly sent by the MBLMessageBannerView. The signals sent are:

Message Positions

Each Message Banner View has a position. By default or if not set, the message banner view will have the position defined by MBLMessageBannerPositionTop Available positions are:

• MBLMessageBannerPositionTop: The message banner will be displayed on the top of the view controller, right under the status bar or the navigation controller if the view has one.
• MBLMessageBannerPositionCenter: The message banner will be displayed on the middle of the view controller.
• MBLMessageBannerPositionBottom: The message banner will be displayed on the bottom of the view controller, or just above the toolbar if the view has one.
  

Message types

Each Message Banner is defined by his type. The desig in the config file is loaded according to the his type. Available type with their already setted design are :

• MBLMessageBannerTypeError: The error message banner.
• MBLMessageBannerTypeWarning: The warning message banner.
• MBLMessageBannerTypeMessage: The standart message banner.
• MBLMessageBannerTypeSuccess: The success message banner.
  

Message duration

Each Message Banner has a "stay on screen" time. This duration can be manually setted by the method parameter. However, the class also provide custom durations :

• MBLMessageBannerDurationDefault: The duration will be automatically calculated according to the size of the message banner view.
• MBLMessageBannerDurationEndless: The message banner will be displayed until the user dismiss it or it is dismissed programatically.

Dismiss methods

The message banner can be dismissed with multiple user gesture. The user can dismiss it with a single tap on the view and swipes gesture. The swipes dismiss gesture are different according to the position of the banner.

• MBLMessageBannerPositionTop: The user can swipe to the top of the screen to dismiss the banner.
• MBLMessageBannerPositionCenter: The user can swipe both to the left and right to dismiss the banner.
• MBLMessageBannerPositionBottom: The user can swipe to the bottom of the screen to dismiss the banner.

Design configuration file

The configuration file is a JSON formated file.

The JSON file is formatted this way :

{
    "MessageBannerTypeName": {
        "PropertyName"    : "Property value"
        ,"AnotherProperty" : 1.0
    },

    "AnOtherMessageBannerTypeName": {
        "PropertyName"    : "Property value"
        ,"AnotherProperty" : 1.0
    }
}

This library come with 4 differents type of banner, with the following corresponding name for the JSON design file format :

Each type of banner can have the following properties :

General properties

Title properties

Subtitle properties

Button properties

Roadmap

Current Version : 1.0.3

• V1.0:

  • Eventual bug fixes
  • Finish Readme.md documentation
  • Fix incorrect project organisation
  • Create Pod Module

• V1.1:

  • Create JSON View Behavior Config File
    • Create Config for custom dismiss methods
    • Create config for custom animation times
    • Create config for custom stay in screen time automatic mode calculation
    • Add default image enabled or not
      

• V1.2:

  • Create Manager JSON config File
    • Create config for multipopups (then to move in behavior cfg to separate for each type)
    • Create config to add “shadow” or “blur” on given View Controller (Or view on screen if its a navigation controller)
    • Create config to allow or not user interaction on the presented view (then to move in behavior cfg to separate for each type)
    • Create Auto depop when screen change var

• V1.3:

  • Add auto-Banner for Network problem + config

• V2.0:

  • Create Swift Version

FAQ

No question asked so far.

Requirements

This project require :

• iOS7
• ARC

Licence

MIT Licence
Copyright (c) 2014 Thibault Carpentier [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Repository Infos

Owner:      Thibault Carpentier
GitHub:     https://github.com/Loadex
LinkedIn:   www.linkedin.com/in/CarpentierThibault/
StackOverflow:  http://stackoverflow.com/users/1324369/loadex