Session: CCE5048 - Enhance your Catalog Items with Contextual Popups!

Hey There!

If you've wound up here after watching my session and wanted to see the nitty-gritty of how you can improve your service portal experience, keep reading. If you've found this article from the community, check out the session link above to see how you can use the spModal directive within catalogue client scripts to improve your end-user experience of your service portal.

The Bad & The Ugly

Calling this bad/ugly is probably a little harsh and hypocritical as I've used this option myself several times and it does the job. But that doesn't meet our needs of our customer nor does it fit in with the portal theming.

The window.alert() and window.confirm() options just don't allow for a good customer journey as they depend on the browsers' implementation of the functions to which you could have additional text added which adds confusion for the user.

The Good

spModal is a lightweight wrapper for Angular UI bootstrap $uibModal that is used frequently in Service portal widgets to present various forms of popups. But did you know it can be used within a catalog client script!

spModal Alert

This is one of the simplest implementations and is a direct replacement for the window.alert() method. It takes in a message and will display a popup with the instance theming.

function onLoad() {

    spModal.alert("You're not authorised to do this")
        .then(function(answer){
        console.log(answer);
    });
}

What's this .then() all about? All modals instantiate a promise which invokes the function within the .then() parameter on the closure of the modal. This allows you to do some funky things with the other spModal versions. For spModal.alert() this just returns true if the user clicks the ok button.

spModal Confirm

Similar to spModal.alert(), the confirm option has the same basic setup but with a cancel button in addition to the ok button.

function onLoad() {

    spModal.confirm("You're not authorised to do this")
        .then(function(answer){
        //If they pressed ok
        console.log(answer);
    } , function(answer){
        //If they pressed cancel
        console.log("didn't accept/select ok");
    });
}

spModal Prompt

As the name might suggest, this option gives you the ability to prompt the user for a value which is then passed back to the promise for you to use. You can pass a default value that the user can overtype.

function onLoad() {

    spModal.prompt("What is your favourite colour?" , "Blue")
        .then(function(answer){
        //If they pressed ok - returns the prompt value or default value
        console.log(answer);
    } , function(answer){
        //If they pressed cancel
        console.log("didn't accept/select ok");
    });
}

spModal Open

This is by far my favourite option as it gives you direct access to the functionality available in $uibModal and greater flexibility. It might seem a little intimidating due to the number of options but it's definitely worth it.

Key	Purpose	Default
title	A string that can be HTML that goes in the header of the modal	empty
message	A string that can be HTML that goes in the body.	empty
buttons	An array that contains the buttons to show on the modal	Cancel & Ok
input	Boolean - whether an input box should appear similar to confirm	false
value	A string default to appear in the input	empty
widget	A string or sys_id of a widget that is embedded into the modal	empty
widgetInput	An object to send to the embedded widget as the input parameter available in its server script	null
shared	A client-side object to share data with the embedded widget client script
size	Size of the modal window. Options are here 'sm' or 'lg'	calculated based on content
animate	specify whether the modal should ease in from the top of the window	true
backdrop	Controls the presence of a backdrop.true (Darkens the screen to focus the modal)false (No backdrop)static (Disables the ability to exit the modal by clicking outside its area)	true
keyboard	Indicates whether the dialog should be closable by hitting the ESC key	true
noDismiss	Removes the header containing the X button to close the modal. Setting this to true also removes the header title	false

License Confirmation

An example used in the session demonstration was the ability to ask the user to actively confirm whether a licensed product is required. This spModal open uses the following object key:value pairs:

• title - This sets the modal header text.
• message - Sets the descriptive value in the body of the modal. In this example, I'm passing in the newValue of the license_type variable.
• buttons - Ok & Cancel don't provide context and can be misinterpreted. The buttons used contain natural language along with using the primary option to set the button we want users to click.
• backdrop - Using static prevents the user from clicking outside the modal and dismissing it.
• keyboard - Setting this to false prevents the ESC key from closing the modal.

The promise sets the license_type to free if the primary button is selected. You can add another function to capture if the cancel/dismiss button is selected to perform another action.

function onChange(control, oldValue, newValue, isLoading) {
   if (isLoading || newValue == '') {
      return;
   }

    if(newValue == 'free') return;

    spModal.open({
        "title" : "Licensed Product",
        "message" : "Power BI " + newValue + " is a paid for product and will require approval",
        "buttons" : [
            {label: "✘ Downgrade to Free" , primary: true},
            {label: "✔ I understand the cost" , cancel: true}
        ],
        "backdrop" : "static",
        "keyboard": false
    }).then(function(){
        g_form.setValue('license_type' , 'free');
    });

}

Terms & Conditions

I often see people add a checkbox to a form to ask people to confirm whether they agree to some sort of T's & C's or EULA. It's functional but isn't pretty and customers aren't going to be clicking on your hyperlink to a knowledge article to read them. This method intercepts the user ordering/submitting and prompts them to read it. If they accept, it'll submit the order for them, else it'll take them back to the page.

function onSubmit() {

    if (typeof spModal != 'undefined' && !g_form._hasConfirmed) {

        spModal.open({
            message: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ut consequat risus, vel maximus augue. Aliquam in velit ut justo consequat pharetra lacinia a magna. Donec egestas quis massa ut lobortis. Nullam non nisi dui. In euismod nisl at bibendum malesuada. Sed iaculis felis non iaculis viverra. Duis interdum felis mi, convallis porta lectus commodo quis. Nam aliquam nulla turpis, vitae mollis nisi facilisis et. Morbi vel augue vel enim pulvinar molestie in vitae neque. Ut eu vehicula odio, a condimentum tortor. Etiam viverra tincidunt nisi sed ultrices. Sed rutrum turpis non faucibus suscipit. Nunc aliquet ante non quam ullamcorper pulvinar. Ut sed dolor nec nulla euismod facilisis sed at eros. Ut in lectus et mauris consectetur vestibulum non sed magna.', 
            title: 'Agree to Terms & Conditions',
            buttons: [ 
                {label:'✘ Disagree', cancel: true},
                {label:'✔ I Accept', primary: true}
            ]
        }).then(function(confirm){
            if (confirm){
                g_form._hasConfirmed = true;
                if (typeof g_form.orderNow != 'undefined') {
                    g_form.orderNow();
                } else {
                    g_form.submit();
                }
            }
        });

        return false;
    }
}

Popup Widget

A bit more advanced, and for those who like to create service portal widgets. spModal supports passing in a widget and input parameter that will be displayed inside the modal window. This uses a custom widget, that is attached, and is designed to make picking a hierarchy location a lot easier.

function onChange(control, oldValue, newValue, isLoading) {
    if (isLoading || newValue == '') {
        return;
    }
    _callPopup();
    function _callPopup(){
        spModal.open({
            "title" : "Select Device Location",
            "widget" : "location-picker",
            "widgetInput" : {"account" : g_form.getValue('account')},
            "shared" : shared,
            "buttons": [
                {label:'✔ Confirm', primary: true}
            ]
        });
    }

}

Conclusion

spModal provides a great visual enhancement to your portal with only a small amount of effort required. If you're already creating a client script, you might as well use this instead of alert() or confirm()! If you any questions, don't hesitate to add them below and I'll endeavour to help out where I can.