Banner Notification

Overview

Notifications are used to inform the user of an event occurring or a special status.

Notifications come in four different types:

• Success: Indicates a successful or positive action.
• Information: Indicates a neutral informative change or action.
• Warning: Indicates a warning that might need attention. Warnings typically do not halt forward progress with the current action.
• Error: Indicates an error or potentially negative action. Errors often halt forward progress with the current action.

Notifications display in one of 3 formats: inline notifications, popup notifications and banner notifications.

This document describes banner notifications.

Banner notifications display in a popup window at the top of the viewport, covering the application header. They do not take up any real estate in the screen, displaying above the screen in a popup.

Banner notifications remain visible until the user presses the X button.

Development

Web component development

Implementation

Angular applications can display a banner notification by firing the appropriate custom event.

This custom event is handled by the jha-app component, which displays the banner notification on your behalf. The banner notification is embedded within the jha-app component, so you don’t have to embed a component in your app to display banner notifications.

Before your app can display banner notifications, bind the includeBannerNotification property in the jha-app component to a value of true. This signals the jha-app component to prepare to handle banner notification requests.

When your app is ready to display a banner notification, first construct a bannerDetail object that describes the banner type (one of “success”, “information”, “warning”, or “error”) and banner text for the banner. Then create and dispatch a new CustomEvent named rui-show-banner-notification and pass a JSON stringified version of the bannerDetail object as the event detail.

public showBanner() {
    // Specify banner type and banner text
    const bannerDetail = {
        bannerType: 'warning',
        bannerText: 'This application will be unavailable between the hours of 12:00 and 2:00 AM due to planned maintenance'
    };

    // Fire custom event: jha-app handles this event and displays the banner notification
    let showBannerEvent = new CustomEvent('rui-show-banner-notification', {
        detail: JSON.stringify(bannerDetail),
        bubbles: true,
        composed: true
    });
    dispatchEvent(showBannerEvent);
}

If you need to hide the default close button and add custom buttons add a bannerButtonsArray to your bannerDetail object that includes an array of id and text for each custom button. The text will be displayed as the button label, and the id will be returned if clicked when listening to the rui-banner-notification-custom-button-click event.

public showBanner() {
    let bannerButtons = [
        { text: 'Accept', id: 'note-custom-btn-approve' },
        { text: 'Reject', id: 'note-custom-btn-reject' }
    ]
    // Specify banner type and banner text
    const bannerDetail = {
        bannerType: 'warning',
        bannerText: 'Please Accept or Reject our Terms of Service',
        bannerButtonsArray: buttonsArray
    };

    // Fire custom event: jha-app handles this event and displays the banner notification
    let showBannerEvent = new CustomEvent('rui-show-banner-notification', {
        detail: JSON.stringify(bannerDetail),
        bubbles: true,
        composed: true
    });
    dispatchEvent(showBannerEvent);

    // Handle event that specifies when the banner notification custom button is clicked
    @HostListener('window:rui-banner-notification-custom-button-click', ['$event'])
    private customButtonClicked(e) {
        console.log('Custom button with id of "' + e.detail + '" clicked on banner notification');
    }
}

If you need to know when the banner notification has been shown or hidden, create an event listener for the rui-banner-notification-is-visible-change event on the window object. The event detail is a boolean value specifying whether the banner notification is shown or not.

// Handle event that specifies when the banner notification is shown or hidden
@HostListener('window:rui-banner-notification-is-visible-change', ['$event'])
private bannerClosed(e) {
    console.log('Banner notification is now ' + (e.detail ? 'shown' : 'hidden'));
}

Angular wrapper development

Implementation

A banner notification can be initiated by calling the JhaNotificationService. You can show the banner notification by calling the DisplayBannerNotification method.

Start by importing the JhaNotificationsModule module into your application.

// import into app.module
import { JhaNotificationsModule } from '@jkhy/responsive-ui-angular/jha-notifications';

@NgModule({
    imports: [
        ...
        JhaNotificationsModule,
        ...
    ]
})

export class AppModule(){}

Within your component TypeScript, import JhaNotificationService and JhaNotificationTypes and add the service to the constructor.

// import into your component
import { JhaNotificationService } from '@jkhy/responsive-ui-angular/jha-notifications';
import { JhaNotificationTypes } from '@jkhy/responsive-ui-angular/jha-notifications';

export class BannerNotificationComponent {
    constructor(private jhaNotificationService: JhaNotificationService) {}
}

Call jhaNotificationService.DisplayBannerNotification(notificationText: string, notificationType: JhaNotificationTypes, notificationCallback?: Function) to display a banner notification.

• notificationText is the string message to display.
• notificationType is one of Information, Success, Warning, or Error, all values in the JhaNotificationTypes enum. This will determine which icon is displayed.
• notificationCallback (optional) is a callback function to execute when the user clicks the Close button on the notification.
• notificationButtonsArray (optional) can be used to hide the default close button and add custom buttons.

public showSuccessBannerNotificationService() {
    this.jhaNotificationService.DisplayBannerNotification('This is a Success banner notification', JhaNotificationTypes.Success,
       () => { this.notificationCallback(); });
}

public notificationCallback(): void {
    console.log('Banner notification was closed');
}

If you need to hide the default close button and add custom buttons, add a notificationButtonsArray argument supplying an array with text and id. Then listen for the rui-banner-notification-custom-button-click event which will return the id of the clicked button.

public bannerButtons: Array<any> = [
    { text: 'Approve', id: 'note-custom-btn-approve' },
    { text: 'Reject', id: 'note-custom-btn-reject' }
];

public showSuccessBannerNotificationService() {
    this.jhaNotificationService.DisplayBannerNotification('Please Accept or Reject our Terms of Service', JhaNotificationTypes.Warning,
       () => { this.notificationCallback(); }, this.bannerButtons);
}

public notificationCallback(): void {
    console.log('Banner notification was closed');
}

// Handle event that specifies when the banner notification custom button is clicked
@HostListener('window:rui-banner-notification-custom-button-click', ['$event'])
private customButtonClicked(e) {
    console.log('Custom button with id of "' + e.detail + '" clicked on banner notification');
}

If you need to hide the banner through code, call the jhaNotificationService.HideBannerNotification(notificationCallback?: Function) method.

• notificationCallback (optional) is a callback function to execute when the banner notification has been hidden.

public hideBannerNotificationService() {
    this.jhaNotificationService.HideBannerNotification(() => { this.hideNotificationCallback(); });
}

public hideNotificationCallback(): void {
    console.log('Banner notification was hidden');
}

Component playground

Design

Figma design

Banner notifications display at the top of the viewport, obscuring the header and spanning the full width of the viewport. These notifications display until closed by the user.

Adobe XD design

Banner notifications display at the top of the viewport, obscuring the header and spanning the full width of the viewport. These notifications display until closed by the user.