Displaying User Notifications with the Lightning Component Framework

image


In this blog post, we explore a Lightning event and a component that displays user notifications: toasts and modals. We’ll share best practices and sample code for each of these components.

Toasts

Toasts are the simplest form of notification a developer can use to display a notification dynamically.


image

They are used to provide basic user feedback with a limited amount of text (if the text is too long, consider using a modal). Unless set to “sticky” mode, they’re displayed for a limited duration and don’t block user interactions.

In Lightning Experience, Salesforce1, and Lightning communities, you aren’t required to directly inject the toast component markup in your code. Instead, you can fire a force:showToast (documentation) application event. The one.app container handles this event and takes care of the markup, placement, and animation of the toast so that you can focus on the content itself.

You simply fire the event from your component’s controller or helper:

var toastEvent = $A.get("e.force:showToast");
toastEvent.setParams({
    title: "Success!",
    message: "Congrats, it works!",
    type: "success"
});
toastEvent.fire();

Toasts displayed by firing the force:showToast event:

  • Are displayed above all content at the top center of the screen
  • Stack up to display up to three toasts
  • Don’t support HTML at all (characters are escaped)
  • Only support links when a message template is specified (check the documentation for more details)

Feel free to try it out with this sample gist.

Modals

Modals are a more advanced way of interacting with users. Unlike toasts, modals focus user interactions by applying an overlay over the screen. Modals are more versatile as they can display a long message, act as a confirmation dialog, capture data with a form, or display a loading message such as file upload progress.

When using modals, consider these UX best practices:

  • Avoid displaying a series of modals.
  • Don’t use a modal to display a success message, use a toast instead.
  • When displaying long content in a modal, add a vertical scroll bar to the modal’s body (the modal footer and its buttons must be kept visible).

Modals come up with several configuration options (optional header and footer, optional close icon, extra wide body, and so on). But these require more code as there’s no Base Lightning component available out of the box for now. That’s subject to change (forward-looking statement) in Winter ’18 according to our Lightning component roadmap.


image

As a convenience, I’ve built and open sourced such a Lightning modal component (AppExchange listing, GitHub repository) that you can freely reuse in your projects. This means that you’re no longer required to rebuild the modal markup and logic each time you need one.

This component can be declared via the following markup:


        Here's a tagline if you need it.
    
Hello, this is the modal's message.
It supports any type of markup including Lightning components

Then, it’s displayed with this line of code in your component’s controller or helper:

component.find("theStaticModal").openModal();

As an alternative to declaring the modal with markup, you can create the modal dynamically with this JavaScript code:

$A.createComponent(
    "ui_modal:modal", {'aura:id': 'theDynamicModal'},
    function(newModal, status, errorMessage){
        if (status === "SUCCESS") {
            //Add the new modal to the app body
            var body = component.get("v.body");
            body.push(newModal);
            component.set("v.body", body);
            // Display an alert modal with a title, a message and an OK button
            // This method is a shorthand that:
            // - pre-populates the modal attributes
            // - displays the modal
            newModal.openModalAlert("Alert", "Hello world!");
        } else {
            console.log("Failed to create modal");
            console.log("Error status: " + status);
            console.log("Error message: " + errorMessage);
        }
    }
);

Conclusion

You now have a better understanding of displaying user notifications using a Lightning Component Framework. Toasts are the simplest form of notification for a limited amount of text. Modals can display a long message, act as a confirmation dialog, capture data with a form, or display a loading message. I provided sample code for each of these components for you to explore.

You now have the tools and knowledge that enable you to display the right type of user notifications from your custom Lightning components.

Remember to keep an eye out for the Lightning component roadmap as two user feedback components are coming up in Winter ’18 (forward-looking statement): lightning:modal and lightning:notifications.

Resources

  • Lightning force:showToast event
  • Lightning modal component

Also found at : Displaying User Notifications with the Lightning Component Framework

Post author

Dustin Gurley is an Designer, Developer, Artist, Instructor, Critical Theorist and Systems Engineer. He has an extensive background working professionally with 2D/2.5D/3D Motion Graphics, Compositing, Film, Video, Photography and client-side performance techniques as it pertains to web development. Dustin recently completed work on his Master of Fine Art degree in Motion Media Design (Motion Graphics) from the Savannah College of Art and Design. Prior to beginning his graduate work, Dustin obtained a Bachelor of Art degree in Communication Studies with a concentration in Broadcast and Emerging Media from the University of North Carolina at Wilmington. In addition to design and modeling, Dustin enjoys toying with his view camera, working with scratch film, authoring media related material and contributing to various industry conferences. When not in front of a computer, Dustin can be found with his wife, Regina Everett Gurley. The couple enjoys dividing their time between their home just outside of Raleigh, North Carolina and the beautiful North Carolina coast. Currently, Dustin serves as the Lead Instructor of Internet Technologies for Wake Technical Community College in Raleigh, North Carolina.