Displaying a custom dialog

Using GlideDialogWindow(), you can write a script to open a custom dialog.

A GlideDialogWindow can be displayed anywhere you use client scripts, UI macros, or UI actions. These are most commonly called from a UI action with the Client check box selected.

For reference information on the available GlideDialogWindow() methods, see GlideDialogWindow() API reference.

GlideDialogWindow basics

Your script should accomplish the following tasks to display a dialog window:
  • Initialize the window by calling GlideDialogWindow(id).
  • Specify the table to display in the dialog with setPreference(name, value).
  • Display the dialog using render().
You can call setTitle(title) and setSize(w,h) to specify the window title and size. If you do not call setTitle(title), the dialog is created without a title displayed in the title bar. You can also define a UI page to display in the dialog window and pass the result back to the calling window.

Displaying a list of records

This example opens a list of incidents in a dialog window. When the user selects an item in the dialog window, that item is opened in the calling window or, if the user clicks the close box, the window closes.

To trigger the dialog window, define a UI action or UI macro with a script that initializes the dialog, references the UI page, and renders the dialog window. In this example, a UI action to define and trigger the dialog window was created with the following attributes and script:
  • Name: Popup Display List
  • Table: Incident
  • Action name: popup_display_list
  • Form button: True
  • Client: True
  • Onclick: popupDispList()
  • Client Script:
function popupDispList() {
    //Initialize the GlideDialogWindow
    var gdw = new GlideDialogWindow('display_incident_list');
    gdw.setTitle('Incidents');
    gdw.setPreference('table', 'incident_list');
    gdw.setPreference('sysparm_view', 'default');
 
    //Set the table to display
    var num = g_form.getValue('number');
    var query = 'active=true^priority=1^number!=' + num;
    gdw.setPreference('sysparm_query', query);
 
    //Open the dialog window
    gdw.render();
}

Opening a custom UI page in a dialog window

This is an example of how to use GlideDialogWindow() to open a custom UI page in a dialog window and pass the results back to the calling window.

To accomplish this, you will need to create the following:
  • A trigger to open the dialog window and reference the UI page.
  • A UI page with HTML and client script definitions.
  • A script include to escape reserved characters in XML.

Defining the trigger

To trigger the dialog window, define a UI action or UI macro with a script that initializes the dialog, references the UI page, and renders the dialog window.

In this example, the following UI action triggers the dialog window:
  • Name: Comments Dialog
  • Table: Incident
  • Action name: comments_dialog
  • Form button: True
  • Client: True
  • Onclick: commentsDialog()
  • Client Script:
function commentsDialog() {
   //Get the values to pass into the dialog
   var comments_text = g_form.getValue("comments");
   var short_text = g_form.getValue("short_description");
 
   //Initialize and open the dialog
   var dialog = new GlideDialogWindow("add_comments_dialog"); //Instantiate the dialog containing the UI page 'add_comments_dialog'
   dialog.setTitle("Add Task Comments"); //Set the dialog title
   dialog.setPreference("comments_text", comments_text); //Pass the comments into the dialog
   dialog.setPreference("short_text", short_text); //Pass in a short description for use in the dialog
   dialog.render(); //Open the dialog
}
The script obtains the values to pass to the dialog, calls the JSUtil script include to escape any content, initializes the dialog attributes, and displays the dialog.

Defining the UI page

In addition to the trigger that opens the dialog window, you will need to define the UI page to display in the dialog window. The UI page name must match the GlideDialogWindow that is instantiated in the trigger script. The example triggering script in the previous section creates a dialog window "add_comments_dialog" so the UI page is named "add_comments_dialog".

The following example UI page is displayed in the dialog window to to add comments to an incident. See Extensions to Jelly Syntax for information on the ServiceNow extensions to Jelly. To obtain the window properties from the triggering script defined by the setPreference() method into the UI page, use RP.getWindowProperties() in the HTML script.

Note: For scoped applications, the RP.getWindowProperties.get() method is not avaliable. Instead use the syntax RP.getWindowProperties.<property>, where <property> is the dialog box property that you want to obtain. For example, RP.getWindowProperties().get('title') would be RP.getWindowProperties().title.

HTML script

<g:ui_form>
  <!-- Get the values from dialog preferences -->
  <g:evaluate var="jvar_short_text"
    expression="RP.getWindowProperties().get('short_text')" />
  <g:evaluate var="jvar_comments_text"
    expression="RP.getWindowProperties().get('comments_text')" />
   <!-- Set up form fields and labels -->
   <table width="100%">
     <tr id="description_row" valign="top">
        <td colspan="2">
           <!-- Short description value used as a label -->
           ${jvar_short_text}
        </td>
     </tr>
     <tr>
       <td>
         <!-- Comments text field (Contains comments from originating record as a default) -->
         <g:ui_multiline_input_field name="dialog_comments" id="dialog_comments" label="Additional comments" 
            value="${jvar_comments_text}" mandatory="true" />
       </td>
     </tr>
     <tr>
       <td colspan="2">
       </td>
     </tr>
     <tr id="dialog_buttons">
        <td colspan="2" align="right">
           <!-- Add OK/Cancel buttons. Clicking OK calls the validateComments script -->
           <g:dialog_buttons_ok_cancel ok="return validateComments()" ok_type="button" cancel_type="button" />
        </td>
     </tr>
  </table>
</g:ui_form>

Client script

The following is an example of a client script that is called when the OK button is clicked in the dialog window. The script checks if there is data in the dialog and, if so, closes the dialog window and pass the comments entered in the dialog window into the Comments field of the original form.

function validateComments() {
	//This script is called when the user clicks "OK" in the dialog window
	
	//Make sure there are comments to submit
	var comments = gel("dialog_comments").value;
	var ga = new GlideAjax('validateComments'); //Call script include to escape text
	ga.addParam('sysparm_name', 'validateComments');
	ga.addParam('sysparm_comments', comments);
	ga.getXMLWait();
	comments = ga.getAnswer(); //Set comments to escaped text
	comments = trim(comments);
	if (comments == "") {
		//If comments are empty, alert the user and stop submission
		alert("Please enter your comments before submitting.");
		return false;
	}
	
	//If there are comments, close the dialog window and submit them
	GlideDialogWindow.get().destroy(); //Close the dialog window
	g_form.setValue("comments", comments); //Set the "Comments" field with comments in the dialog
}

Script Include

To escape out XML-reserved characters from the content users enter into the custom dialog, create this script include.
  • Name: validateComments
  • Client callable: True
  • Script:
var validateComments = Class.create();
validateComments.prototype = Object.extendsObject(AbstractAjaxProcessor, {
	
		validateComments: function() {
			
			var comments = this.getParameter('sysparm_comments');
			var ampRegex = new SNC.Regex('/&/');
			var ltRegex = new SNC.Regex('/</');
			var gtRegex = new SNC.Regex('/>/');
			
			var result = ampRegex.replaceAll('' + comments, '&' + 'amp;');
			result = ltRegex.replaceAll(result, '&' + 'lt;');
			return gtRegex.replaceAll(result, '&' + 'gt;');
			
		},
		
		type: 'validateComments'
	});