PrimeNGAdvancedGrowl

Table of Contents generated with DocToc

• AdvGrowlModul
  • Demo and Blogposts
  • What is missing on PrimeNG?
  • What is the AdvGrowlModule offering?
  • How do you use PrimeNGAdvancedGrowl?
    • installation
    • Angular 6
    • AdvGrowlComponent
      • Input
      • Output
    • Models
    • AdvGrowlService
    • Examples
      • Avoid creating success messages with same Summary
      • Passing additional properties to the message
      • Do not let error messages disappear automatically

AdvGrowlModul

The AdvGrowlModule is a wrapper around the growl module from PrimeNG. This wrapper was created because PrimeNG is missing some features.

• If you have a feature request or noticed a bug please open an issue under: https://github.com/kreuzerk/primeNG-advanced-growl/issues
• If you have questions about the module or want to discuss new ideas or improvements please use our chat at: https://gitter.im/primeNG-advanced-growl/Lobby
• Contributions are welcome. Just fork the repo and create a Pull Request.

Demo and Blogposts

• You can find a working demo of the growl module on the following link: https://primeng-advanced-growl.firebaseapp.com/
• A blogpost that explains how to make sure that your users do not miss error messages is availbale under: https://medium.com/@kevinkreuzer/primeng-advanced-growl-make-sure-your-users-see-the-errors-6988f722fb8f

What is missing on PrimeNG?

• PrimeNG growl offers us to define a sticky property to remove the messages. When we set the lifetime of the messages to 3 seconds all messages will be removed after the specified time. The problem comes when a message gets created 2 seconds after the first message. This message will not be removed after the specified 3 seconds. This message will be removed 1 seconds after creation. This is the point where the 3 seconds from the first message have passed.

What is the AdvGrowlModule offering?

• It allows you to choose a default lifetime for each message. Each message receives this lifetime when it is created. This feature differs from the original primeng growl module because the lifetime is unique for each message. 
• It allows you to choose if you want to freeze all messages on hover. If you enable this feature and hover over a message all messages will internally stop their timer and wait until you leave the messages again. Each message will restart its timer with the remaining time.
• In addition to freezing all messages you also have the possibility to freeze only one message on hover.
• You can limit the number of messages that will be displayed on screen. Notice that all other messages that can not be displayed are cached and will be displayed as soon as another spot is available.
• You can optionally pas additional properties to each of your messages. You can then retrieve those properties by clicking on a message as an output event. 
• The newest and one of the most powerful features was released in the 3.1.0-reindeer version. Additionally to the default lifetime you can now specify a new unique lifeTime for each message. This means you can say I want to create a info message with a lifetime of 2 seconds, a success message with a lifetime of 3 seconds and so on. This is also the feature we are going to use to make sure that our users do not miss error messages.

How do you use PrimeNGAdvancedGrowl?

installation

PrimeNGAdvancedGrowl is an node_module and therefore it is provided over npm. To install it node and npm are required.

npm install --save primeng-advanced-growl 

To have all the primeNG styles available you need to import the following stylesheets in your application:

"../node_modules/font-awesome/scss/font-awesome.scss", "../node_modules/primeng/resources/primeng.css", "../node_modules/primeng/resources/themes/omega/theme.scss" 

To use the AdvGrowlService and the AdvGrowlComponent you need to import the AdvGrowlModul in your appliction.

import {AdvGrowlModule} from 'primeng-advanced-growl';  @NgModule({     declarations: [AppComponent],     imports: [AdvGrowlModule] }) ...

Angular 6

Please notice that only versions 4.x are Angular 6 compatible.

AdvGrowlComponent

The AdvGrowlModule exports a component named AdvGrowlComponent. You need to include this component once in your app.component.html. With the help of this component the advanced PrimeNG growl messages can be displayed.

<app-navbar></app-navbar> <adv-growl></adv-growl> <div class="container">     <router-outlet></router-outlet> </div>

The advanced growl messages component has the following in- and outputs.

Input

Output

Models

export interface AdvPrimeMessage {     id: string;     severity: string;     summary: string;     detail: string;     additionalProperties?: any; }

AdvGrowlService

The AdvGrowlService allows you to create and delete messages. The AdvGrowlService can be accessed over dependency injection inside your component.

import {AdvGrowlService} from 'primeng-advanced-growl';  @Component({     selector: ...,     templateUrl: ... }) export class SampleComponent{      constructor(private advGrowlService: AdvGrowlService){     } }

The AdvGrowlService provides the following methods to create messages. Each method expects the message content and a message title. If you wish you can also add additional properties. Additional properties are emitted when you click on a message. All of the methods below will use the lifetime you specified on the component via the life input property.

• createSuccessMessage(messageContent: string, summary: string, additionalProperties?: any): AdvPrimeMessage
• createInfoMessage(messageContent: string, summary: string, additionalProperties?: any): AdvPrimeMessage
• createWarningMessage(messageContent: string, summary: string, additionalProperties?: any): AdvPrimeMessage
• createErrorMessage(messageContent: string, summary: string, additionalProperties?: any): AdvPrimeMessage

If you want to create messages that have another lifetime than the one you provided via the life input property you can use the Timed message service methods. Those methods are similar to the methods above but they accept an additional lifeTime property. This lifetime will then be used.

• createTimedSuccessMessage(messageContent: string, summary: string, lifeTime: number, additionalProperties?: any): void
• createTimedInfoMessage(messageContent: string, summary: string, lifeTime: number, additionalProperties?: any): void
• createTimedWarningMessage(messageContent: string, summary: string, lifeTime: number, additionalProperties?: any): void
• createTimedErrorMessage(messageContent: string, summary: string, lifeTime: number, additionalProperties?: any): void

To clear all messages you can call the clearMessages() method from the AdvGrowlService.

Examples

Inside the test folder you can find different examples how to use the library. Below we listed some code samples for common use cases.

Avoid creating success messages with same Summary

If we want to avoid the creation of multiple messages with the same summary or type we could do the following inside our component.

import {AdvPrimeMessage} from '../../lib/messages/adv-growl.model';  @Component({     selector: 'sample-app',     template: `<adv-growl [life]="2500"                 (onMessagesChanges)="onMessages($event)">                </adv-growl>                <button pButton type="button"                     (click)="createNonDuplicatedSuccessMessage()"                     class="ui-button-success"                     label="Create success message if none on screen">                </button>                ` }) export class AppComponent {      messages = [];      constructor(private advMessagesService: AdvGrowlService) {     }      public createSuccessMessage(): void {         this.advMessagesService.createSuccessMessage('Awesome success message content', 'Awesome success', {           clickMessage: 'Awesome click'         });     }      public onMessages(messages) {         this.messages = messages;     }      public createNonDuplicatedSuccessMessage(): void {         const index = this.messages.findIndex(message => message.summary === 'Awesome success');         if (index < 0) {             this.createSuccessMessage()         }     } }

Passing additional properties to the message

If you want to pass some additional informations to your message you can do this by passing those as last optional parameter to the success, warning, info or error method. When you click on your message the event will then contain your additionalProperties.

import {AdvPrimeMessage} from '../../lib/messages/adv-growl.model';  @Component({     selector: 'sample-app',     template: `<adv-growl [life]="2500"                 (onMessagesChanges)="onMessages($event)"                 (onClick)="logMessage($event)">                </adv-growl>                <button pButton type="button"                     (click)="createSuccessMessageWithAdditionalInfos()"                     class="ui-button-success"                     label="Create success message with additional properties">                </button>                ` }) export class AppComponent {      messages = [];      constructor(private advMessagesService: AdvGrowlService) {     }      public createSuccessMessageWithAdditionalInfos(): void {         this.advMessagesService.createSuccessMessage('Awesome success message content', 'Awesome success', {           clickMessage: 'Awesome click'         });     }      public logMessage(message: AdvPrimeMessage) {         if (message.additionalProperties) {             console.log(message.additionalProperties.clickMessage)         } else {             console.log('You clicked on message', message)         }     } }

Do not let error messages disappear automatically

Letting messages disappear within the given time is a cool feature. But sometimes you do not want let messages disappear automatically because you are then risking that the user misses the message. This is often the case with error messages. Primeng-advanced-growl allows you to use the "timed" methods to specify the message for each created message. This gives you a lot of power. With this API you can easily create all messages with a lifeTime of 0. Rember that 0 is equal to sticky.

import {AdvPrimeMessage} from '../../lib/messages/adv-growl.model';  @Component({     selector: 'sample-app',     template: `<adv-growl [life]="2500"                 (onMessagesChanges)="onMessages($event)"                 (onClick)="logMessage($event)">                </adv-growl>                <button pButton type="button"                     (click)="createTimedErrorMessage()"                     class="ui-button-success"                     label="Create sticky error message">                </button>                ` }) export class AppComponent {      messages = [];      constructor(private advMessagesService: AdvGrowlService) {     }      public createTimedErrorMessage(): void {         this.advMessagesService.createTimedErrorMessage('Click me or I will stay forever', 'Watch out', 0, {           clickMessage: 'Awesome click'         });     } }