Modal box

Guide
Beginner

The purpose of the modal box is to display data in a dialog box.

The modal box behaves as follows:

  • The page from which the modal box was called remains open.
  • Creatio does not go to a new page.
  • The browser history does not record the page the modal box displays.

The modal box lets you:

  • Display any information. For example, text, buttons, etc.

  • Select data from a lookup. For example, the modal box displays the contact lookup to select the activity owner.

The modal box includes the following components:

  • The ModalBox and ModalBoxSchemaModule schemas of the NUI package that implement the functionality of the modal box.
  • The LookupUtilitiesV2 schema of the NUI package that implements calls to the modal box for selecting lookup data.
See also
Manage lookup values
Implement a modal box
Advanced

Example. Implement a process task that displays a modal box as part of a business process. The box must contain text and Yes, No, Cancel buttons.

Set up the following button logic:

  • If you click Yes or No, the corresponding auto-generated pages open.
  • If you click Cancel, the modal box closes.

Set up logging for the process task.

1. Create a process task 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → User task on the section list toolbar.

  3. Specify the process task properties.

    • Set Code to "UsrShowModalPageUserTask."
    • Set Title to "Show modal page (process user task)."

Click Apply to apply the properties.

2. Add process task parameters 

  1. Add a parameter that displays the message to the user.

    1. Click the scr_add_button.png button in the Parameters node.

    2. Fill out the parameter properties.

      • Set Code to "UsrDialogText."
      • Set Title to "Dialog message text."
      • Set Type to "Text."
      • Select the Required checkbox.

  2. Add a parameter that passes the names of the displayed buttons from the process to the element. The parameter must accept comma-separated button codes in a string.

    1. Click the scr_add_button.png button in the Parameters node.

    2. Fill out the parameter properties.

      • Set Code to "UsrCommaSeparatedReturnCodes."
      • Set Title to "Button return codes separated with comma.”
      • Set Type to "Text."
      • Select the Required checkbox.

  3. Add a parameter that contains the code of the clicked button.

    1. Click the scr_add_button.png button in the Parameters node.

    2. Fill out the parameter properties.

      • Set Code to "UsrReturnCode."
      • Set Title to "Selected button code."
      • Set Type to "Text."
      • Select the Resulting checkbox.

3. Implement the process task in the back-end 

  1. Set up process logging.

    1. Use the using directive to add the needed namespaces.

      using global::Common.Logging;
using Terrasoft.Configuration;

    2. Implement the logic of the process task and process logging

      UsrShowModalPageUserTask
      namespace Terrasoft.Core.Process.Configuration
{

    using Newtonsoft.Json;
    using Newtonsoft.Json.Linq;
    using System;
    using System.Collections.Generic;
    using System.Collections.ObjectModel;
    using System.Globalization;
    using Terrasoft.Common;
    using Terrasoft.Core;
    using Terrasoft.Core.Configuration;
    using Terrasoft.Core.DB;
    using Terrasoft.Core.Entities;
    using Terrasoft.Core.Process;
    using Terrasoft.UI.WebControls.Controls;

    /* Required for logging to operate correctly. */
    using global::Common.Logging;

    /* Required for message sending tools to operate correctly. */
    using Terrasoft.Configuration;

    #region Class: UsrShowModalPageUserTask

    /// <exclude/>
    public partial class UsrShowModalPageUserTask
    {
        /* Set up logging.
        Create an individual logger. Record the logging results to the Common.log file. */
        private static readonly ILog _log = LogManager.GetLogger("UsrShowModalPageUserTask");

        /* Define the sender in the back-end. */
        private const string MessageSender = "UsrShowModalPageUserTask";

        #region Methods: Protected

        /* The business logic of the process task. */
        protected override bool InternalExecute(ProcessExecutingContext context) {

            /* Log the information level message. */
            _log.InfoFormat("UserTask works well. UsrDialogText = {0}, UsrCommaSeparatedReturnCodes = {1}", UsrDialogText, UsrCommaSeparatedReturnCodes);
            /* Create a message. */
            var messageData = new
            {
                /* The text in the dialog box. */
                UsrDialogText = UsrDialogText,
                /* The comma-separated button return codes. */
                UsrCommaSeparatedReturnCodes = UsrCommaSeparatedReturnCodes,
                /* The service parameter. The unique ID of the element instance within the process instance. */
                procElUId = UId
            };
            /* Serialize the message body object. */
            string messageBody = JsonConvert.SerializeObject(messageData);
            /* The message body sent from the back-end to front-end. */
            MsgChannelUtilities.PostMessage(UserConnection, MessageSender, messageBody);
            return false;
        }

        #endregion

        #region Methods: Public

        public override bool CompleteExecuting(params object[] parameters) {
            return base.CompleteExecuting(parameters);
        }

        public override void CancelExecuting(params object[] parameters) {
            base.CancelExecuting(parameters);
        }

        public override string GetExecutionData() {
            return string.Empty;
        }

        public override ProcessElementNotification GetNotificationData() {
            return base.GetNotificationData();
        }

        #endregion

    }

    #endregion

}
  2. Click Publish on the Designer’s toolbar.

4. Implement the task processing in the front-end 

  1. Go to the Configuration section and select a custom package to add the schema.
  2. Click Add → Module on the section list toolbar.

  3. Fill out the module properties.

    • Set Code to "UsrShowModalPageUserTaskMixin."
    • Set Title to "ShowModalPageUserTaskMixin."

  4. Add the source code in the Module Designer.

    UsrShowModalPageUserTaskMixin
    define("UsrShowModalPageUserTaskMixin", [],
    function() {
        Ext.define("Terrasoft.configuration.mixins.ShowModalPageUserTaskMixin", {
            alternateClassName: "Terrasoft.ShowModalPageUserTaskMixin",
            
            /* Subscribe to the WebSocket channel messages. */
            UsrSubscribeForShowModalWindowServerChannelMessages: function() {
                this.Terrasoft.ServerChannel.on(this.Terrasoft.EventName.ON_MESSAGE, this.UsrServerChannelMessageHandler, this);
            },
            /* Unsubscribe from the WebSocket channel messages. */
            UsrUnsubscribeForShowModalWindowServerChannelMessages: function() {
                this.Terrasoft.ServerChannel.un(this.Terrasoft.EventName.ON_MESSAGE, this.UsrServerChannelMessageHandler, this);
            },
            
            UsrShowModalPageUserTask_procElUId: "",
            
            /* The function that processes WebSocket messages. */
            UsrServerChannelMessageHandler: function(scope, message) {
                if (!message) {
                    return;
                }
                /* Define the message from the UsrShowModalPageUserTask sender. */
                if (message.Header && message.Header.Sender !== "UsrShowModalPageUserTask") {
                    return;
                }
                if (message.Body) {
                    var bodyData = this.Ext.decode(message.Body);
                    var UsrDialogText = bodyData.UsrDialogText;
                    var UsrCommaSeparatedReturnCodes = bodyData.UsrCommaSeparatedReturnCodes;
                    
                    /* Retrieve and save the button codes as an array. */
                    var returnCodesArray = UsrCommaSeparatedReturnCodes.split(",");
                    var procElUId = bodyData.procElUId;
                    UsrShowModalPageUserTask_procElUId = procElUId;
                    
                    /* Display the dialog box. */
                    this.showConfirmationDialog(UsrDialogText, this.UsrGetConfirmationResult, returnCodesArray);
                }
            },
            /* Process the button code selection results. */
            UsrGetConfirmationResult: function(returnCode) {
                this.console.log("UsrGetConfirmationResult: returnCode = " + returnCode + " UsrShowModalPageUserTask_procElUId = " + UsrShowModalPageUserTask_procElUId);
                
                var procElUId = UsrShowModalPageUserTask_procElUId;
                
                /* Create a POST request. */
                this.Terrasoft.AjaxProvider.request({
                    url: "../ServiceModel/ProcessEngineService.svc/" + procElUId + "/CompleteExecution" + "?UsrReturnCode=" + returnCode,
                    method: "POST",
                    scope: this,
                    callback: function(request, success, response) {	
                    }
                });
            }
        });
    });
  5. Click Save on the Designer’s toolbar.

5. Create a replacing view model of the container 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the module properties.

    • Set Code to "MainHeaderSchema."
    • Set Title to "MainHeaderSchema."
    • Set Parent object to "MainHeaderSchema."

  4. Add the source code in the Module Designer.

    MainHeaderSchema
    define("MainHeaderSchema", ["UsrShowModalPageUserTaskMixin"], function(){
    return {
        mixins: {
            ShowModalPageUserTaskMixin: "Terrasoft.ShowModalPageUserTaskMixin"
        },
        methods: {
            init: function() {
                this.callParent(arguments);
                this.UsrSubscribeForShowModalWindowServerChannelMessages();
            },
            destroy: function() {
                this.callParent(arguments);
                this.UsrUnsubscribeForShowModalWindowServerChannelMessages();
            }	
        }
    };
});
  5. Click Save on the Designer’s toolbar.

6. Create a business process that displays the modal box 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Business process on the section list toolbar.

  3. Fill out the process properties.

    • Set the Title property in the element setup area to "Show Modal Page Example Process."
    • Set the Code property on the Settings tab of the element setup area to "UsrShowModalPageExampleProcess."

  4. Implement the business process.

    1. Add the process task.

      1. Click System actions in the Designer’s element area and place a User task element between the Simple start event and Terminate end event on the Process Designer’s working area.

      2. Specify the process task properties.

        • Set Which user task to perform? to "Show modal page (process user task)."

        • Fill out the process task parameters.

          • Set Dialog message text to "Do you like new window?."
          • Set Button return codes separated with comma to "yes,no,cancel."

    2. Add the auto-generated page.

      1. Click User actions in the Designer's element area and place an Auto-generated page element in the Process Designer’s working area.

      2. Fill out the auto-generated page properties.

        • Set Title to "YES."
        • Set Page title to "Pressed YES."

      3. Add a button.

        1. Click the button in the Buttons block.

        2. Fill out the button properties.

          • Set Caption to "OK."
        3. Save the changes.

      View the auto-generated page settings on the figure below.

    3. Set up the conditional flow.

      1. Select Add flow in the process task menu and connect the process task to the auto-generated page.

      2. Convert the sequence flow into a conditional flow. To do this, click the button and select Conditional flow in the flow menu.

      3. Fill out the conditional flow properties.

        • Set Title to "yes."

      4. Specify the move conditions.

        1. Click the button of the Condition to move down the flow property in the element setup area.
        2. Select the "Show modal page (process user task)" process element.
        3. Double-click the "Selected button code" process parameter.

        4. Set the parameter formula.

          [#Show modal page (process user task).Selected button code#] == "yes"
        5. Save the changes.
    4. Add a NO auto-generated page connected to the corresponding no conditional flow in a similar way.

    5. Set up the default flow.

      1. Select Add flow in the process task menu and connect the process task to the Terminate end event.

      2. Convert the conditional flow into a default flow. To do this, click the button and select Default flow in the flow menu.

      3. Fill out the default flow properties.

        • Set Title to "cancel."

    View the business process in the figure below

  5. Click Save on the Process Designer’s toolbar.

Outcome of the example 

You can run the Show Modal Page Example Process business process from any Creatio section. For example, run the business process from the Contacts section.

To run the Show Modal Page Example Process business process from the Contacts section:

  1. Open the Contacts section.
  2. Click the button in the section panel.
  3. Select the Show Modal Page Example Process business process and click Run.

As a result, the Show Modal Page Example Process business process will display the modal box in the Contacts section.

  • If you click the Yes button, the Pressed YES page that contains the OK button will open.

  • If you click the No button, the Pressed NO page that contains the OK button will open.

  • If you click the Cancel button, the modal box will close.

View the request logging results in the Common.log file in the Creatio root directory. Use the browser developer tools to track the WebSocket messages passed from the back-end to the front-end.

Resources
Package with example implementation