Modal Dialogs in SCIS
The SCIS extensibility API enables you to create extensions for SCIS. It lets you show modal dialogs in response to events that occur in the cart, such as adding an item to the cart, applying a discount, or voiding a line.
The steps to create an SCIS extension are similar to the steps to create an extension for SuiteCommerce or SuiteCommerce Advanced:
-
Download and install the extension developer tools.
-
Create a baseline extension. Select
SuiteCommerce InStorein the supported extension step. See Create a Baseline Extension for more information. -
Add your extension code.
-
Test the extension locally, and then deploy.
When you create a baseline extension for SCIS, the developer tools generates the directory structure for the extension, as well as the JavaScript file for the initial module. You can find the initial module file in the directory structure at [workspace folder]/[extension name]/Modules/JavaScript.
The initial module file contains some basic scaffolding code to get started. The module name is generated from the information you entered when creating the baseline extension with gulp. The define() function lets you specify the name of the module, any dependencies, and a return function. Because the initial module has no dependencies, the second argument is an empty array []. In the return function, the mountToApp() method initializes the module and returns data. The code for your extension goes in the mountToApp() method.
define(
'Company.SCISExtensionName.MainModule',
[],
function() {
'use strict',
return {
mountToApp: function mountToApp(container) {
}
}
}
);
Modal Dialog Types
Show a modal dialog when you want to show important information to the user or you want the user to confirm an action. Two types of modal dialog are available:
-
Information dialog (or information window) – Shows a modal dialog with one button and space for a text message. The user must click the button to close the dialog and continue with the operation.
-
Confirmation dialog (or option window)– Shows a modal dialog with two buttons and space for a text message. Use this type of dialog when you want the user to choose between one of two actions, usually to confirm or cancel an operation. Separate actions are defined for each button.
Modal dialogs have a predefined look and feel. You cannot modify the look and feel of a dialog, however, you can specify content of the dialog, such as the text in the dialog and whether a toast-style notification strip is shown in the dialog. You can also change the name of the buttons as required.
Define Modal Dialog Options
To create a modal dialog, you get an instance of the SCIS layout component and call the showConfirmationPopup() method with an object as its argument. The object contains a set of properties that let you specify the content of the dialog, such as the title, a message, and the text labels for the two buttons. The following example uses all available properties for the options of a confirmation dialog. The same properties are available to create an information dialog, except the cancelationButtonText property.
var layout = SC.Application('SCIS').getComponent('SCISLayout');
var confirmationPopupOptionsAgeRequirements = {
title: 'Age Verification',
toastType: 'warning',
toastContent: 'Verify customer is +18 years old.',
messageContent: 'Sale of this item prohibited to minors. Tap Age Confirmed only if the customer is +18 years old.',
confirmationButtonText: 'Age Confirmed',
cancelationButtonText: 'Remove Item'
}
Show the Modal Dialog After an Event Occurs
In our example, we want the modal dialog to appear before an item is added to the cart. Get an instance of the cart component to listen for the beforeAddLine event, which occurs just before the item is added. Use the on() method of the cart component to add an event listener for the beforeAddLine event.
The on() method accepts an event name and an event handler as it arguments. Contextual data is passed to the event handler as an object. In the case of the beforeAddLine event, properties of the object include the item’s internal ID. Use dot notation to get the internal ID of the item.
var cart = SC.Application('SCIS').getComponent('Cart');
cart.on('beforeAddLine', function(data) {
if (data.line.internalid == '10101') {
layout.showConfirmationPopup(confirmationPopupOptionsAgeRequirements).then(function(result){
if (result.action === 'cancel') {
throw Error('Item not added to cart.');
}
});
}
});
If the internal ID of the item added to the cart matches a specified number (in this example, 10101), show the confirmation dialog with showConfirmationPopup(). Since this method returns a promise, use then() to attach a done callback. In the callback, check the value returned by showConfirmationPopup(). The value returned will be either ‘cancel’ or ‘OK’, depending on whether the cancelation or confirmation button was clicked. Finally, if the value returned from the modal dialog is ‘cancel’, throw Error() stops execution of the script, which prevents the item being added to the cart.
The following example shows the full sample code for a modal dialog in SCIS.
define(
'Company.SCISExtension.MainModule',
[],
function () {
'use strict';
return {
mountToApp: function mountToApp (container) {
var layout = SC.Application('SCIS').getComponent('SCISLayout');
var cart = SC.Application('SCIS').getComponent('Cart');
confirmationPopupOptionsAgeRequirements = {
title: 'Age Verification',
toastType: 'warning',
toastContent: 'Verify customer is +18 years old.',
messageContent: 'Sale of this item prohibited to minors. Tap Age Confirmed only if the customer is +18 years old.',
confirmationButtonText: 'Age Confirmed' ,
cancelationButtonText: 'Remove Item'
}
cart.on('beforeAddLine', function(data) {
if (data.line.internalid == '10101') {
layout.showConfirmationPopup(confirmationPopupOptionsAgeRequirements).then(function(result){
if (result === 'cancel') {
throw Error('Item not added to cart.');
}
});
}
});
}
}
}
);