Modal Dialogs for Event Handling in SuiteCommerce

The SCIS extensibility API allows developers to create custom extensions for SuiteCommerce InStore (SCIS), enabling modal dialogs to appear in response to various cart events. This capability enhances user interactions by prompting confirmations for significant actions like adding items to the cart or applying discounts.

Steps to Create an SCIS Extension

Creating an SCIS extension involves several key steps:

1. Download and install the extension developer tools.
   This step sets up your environment for building extensions.
2. Create a baseline extension.
   When prompted, select SuiteCommerce InStore as the supported extension. Consult the official documentation for detailed guidance on creating a baseline extension.
3. Add your extension code.
   Implement the necessary functionality for your dialog.
4. Test the extension locally and deploy.
   Ensure everything works as intended before going live.

Initial Module Structure

When a baseline extension is created using the developer tools, it generates the directory structure along with a JavaScript file for your initial module. This file typically resides in the directory: [workspace folder]/[extension name]/Modules/JavaScript. An essential part of this module is the define() function, which allows you to specify dependencies and the return function, which initializes the module.

Here’s a simple example of the initial module setup:

1"text-purple-400">define(
2    'Company.SCISExtensionName.MainModule',
3    [],
4    "text-purple-400">function() {
5        'use strict';
6        "text-purple-400">return {
7            mountToApp: "text-purple-400">function mountToApp(container) {
8            }
9        };
10    }
11);

Types of Modal Dialogs

In SCIS, you have two options for modal dialogs:

• Information Dialog:
  This dialog includes one button and communicates essential information. Users must acknowledge it to proceed.
• Confirmation Dialog:
  This dialog features two buttons, allowing users to confirm or cancel their actions. Each button can execute different operations.

While the external appearance of these dialogs cannot be modified, you have control over the dialog's content, including button labels and accompanying messages.

Defining Modal Dialog Options

To implement a modal dialog, you need to get an instance of the SCIS layout component and utilize the showConfirmationPopup() method. You can provide an object as an argument to define various properties of the dialog such as the title and button texts. The example below demonstrates a set of options for a confirmation dialog:

1"text-purple-400">var layout = SC.Application('SCIS').getComponent('SCISLayout');
2 
3"text-purple-400">var confirmationPopupOptions = {
4    title: 'Age Verification',
5    toastType: 'warning',
6    toastContent: 'Verify customer is +18 years old.',
7    messageContent: 'Sale of ">this item prohibited to minors. Tap Age Confirmed only ">if the customer is +18 years old.',
8    confirmationButtonText: 'Age Confirmed',
9    cancelationButtonText: 'Remove Item'
10};

Implementing Event-Triggered Modal Dialogs

You can trigger modal dialogs based on specific events. For instance, displaying a dialog before adding an item to the cart can improve user decision-making. To achieve this, you would listen for the beforeAddLine event using the cart component's on() method.

Here’s how to set up the event listener:

1"text-purple-400">var cart = SC.Application('SCIS').getComponent('Cart');
2 
3cart.on('beforeAddLine', "text-purple-400">function(data) {
4    "text-purple-400">if (data.line.internalid == '10101') {
5        layout.showConfirmationPopup(confirmationPopupOptions).then("text-purple-400">function(result){
6            "text-purple-400">if (result.action === 'cancel') {
7                "text-purple-400">throw Error('Item not added to cart.');
8            }
9        });
10    }
11});

In this code, if the item's internal ID matches a specified value (in this case, 10101), the confirmation dialog is shown. The showConfirmationPopup() method returns a promise that resolves based on user interaction with the dialog buttons. If the user opts to cancel, an error is thrown, preventing the item from being added to the cart.

Example of Complete Modal Dialog in SCIS

Here’s the complete code snippet that sets up a modal dialog in SCIS:

1"text-purple-400">define(
2    'Company.SCISExtension.MainModule', 
3    [],
4    "text-purple-400">function () {
5        'use strict';
6        "text-purple-400">return {
7            mountToApp: "text-purple-400">function mountToApp (container) {
8                "text-purple-400">var layout = SC.Application('SCIS').getComponent('SCISLayout');
9                "text-purple-400">var cart = SC.Application('SCIS').getComponent('Cart');
10                "text-purple-400">var confirmationPopupOptions = {
11                    title: 'Age Verification',
12                    toastType: 'warning',
13                    toastContent: 'Verify customer is +18 years old.',
14                    messageContent: 'Sale of ">this item prohibited to minors. Tap Age Confirmed only ">if the customer is +18 years old.',
15                    confirmationButtonText: 'Age Confirmed',
16                    cancelationButtonText: 'Remove Item'
17                };
18                cart.on('beforeAddLine', "text-purple-400">function(data) {
19                    "text-purple-400">if (data.line.internalid == '10101') {
20                        layout.showConfirmationPopup(confirmationPopupOptions).then("text-purple-400">function(result){
21                            "text-purple-400">if (result === 'cancel') {
22                                "text-purple-400">throw Error('Item not added to cart.');
23                            }
24                        });
25                    }
26                });
27            }
28        };
29    }
30);

This example demonstrates how to implement a notification flow that can significantly improve user interaction with your SCIS extension as they manage their cart items.

Key Takeaways

• You can create modal dialogs in SCIS to enhance user interactions.
• Different types of dialogs (information and confirmation) serve distinct purposes.
• Setting up event-triggered dialogs helps manage critical user decisions effectively.

Source: This article is based on Oracle's official NetSuite documentation.