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.

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

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

      UsrShowModalPageUserTask
      Code copied
      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
    Code copied
    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
    Code copied
    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.

          Code copied
          [#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