GlideForm - addDecoration(String fieldName, String icon, String title, String color)

The GlideForm API provides methods to customize forms.

GlideForm.js is the JavaScript class containing the methods. The global object g_form is used to access GlideForm methods. GlideForm methods are only used on the client. These methods are used to make custom changes to the form view of records. All validation of examples was done using client scripts.

Some of these methods can also be used in other client scripts (such as Catalog Client Scripts or Wizard Client Scripts), but must first be tested to determine whether they will work as expected.

Note: The methods getControl() , getHelpTextControl() , getElement() , and getFormElement() are deprecated for mobile devices. For information on using GlideForm for mobile, see Mobile Client GlideForm (g_form) Scripting and Migration .

There is no constructor for the GlideForm class. Access GlideForm methods using the g_form global object.

Parent Topic: Client API reference GlideForm - addDecoration(String fieldName, String icon, String title)

Adds an icon on a field's label.

Adding the same item twice is prevented; however, you can add the same icon with a different title. Note: This method is not supported by Service Catalog.

Table 1. Parameters Name Type Description fieldName String The field name. icon String The font icon to show next to the field. Supported icons - icon-user, icon-user-group, icon-lightbulb, icon-home, icon-mobile, icon-comment, icon-mail, icon-locked, icon-database, icon-book, icon-drawer, icon-folder, icon-catalog, icon-tab, icon-cards, icon-tree-right, icon-tree, icon-book-open, icon-paperclip, icon-edit, icon-trash, icon-image, icon-search, icon-power, icon-cog, icon-star, icon-star-empty, icon-new-ticket, icon-dashboard, icon-cart-full, icon-view, icon-label, icon-filter, icon-calendar, icon-script, icon-add, icon-delete, icon-help, icon-info, icon-check-circle, icon-alert, icon-sort-ascending, icon-console, icon-list, icon-form, and icon-livefeed. title String The text title for the icon.

Table 2. Returns Type Description void

g_form.addDecoration('caller_id', 'icon-star', 'preferred member');

GlideForm - addDecoration(String fieldName, String icon, String title, String color)

Adds an icon on a field's label.

Adding the same item twice is prevented; however, you can add the same icon with a different title. Note: This method is not supported by Service Catalog.

Table 3. Parameters Name Type Description fieldName String The field name. icon String The font icon to show next to the field. Supported icons - icon-user, icon-user-group, icon-lightbulb, icon-home, icon-mobile, icon-comment, icon-mail, icon-locked, icon-database, icon-book, icon-drawer, icon-folder, icon-catalog, icon-tab, icon-cards, icon-tree-right, icon-tree, icon-book-open, icon-paperclip, icon-edit, icon-trash, icon-image, icon-search, icon-power, icon-cog, icon-star, icon-star-empty, icon-new-ticket, icon-dashboard, icon-cart-full, icon-view, icon-label, icon-filter, icon-calendar, icon-script, icon-add, icon-delete, icon-help, icon-info, icon-check-circle, icon-alert, icon-sort-ascending, icon-console, icon-list, icon-form, and icon-livefeed. title String The text title for the icon. color String A CSS color.

Table 4. Returns Type Description void

g_form.addDecoration('caller_id', 'icon-star', 'Mark as Favorite', 'color-green');

GlideForm - addErrorMessage(String message)

Displays the specified error message at the top of the form.

This message appears for approximately four seconds and then disappears. This timeout is not configurable at this time.

Table 5. Parameters Name Type Description message String Message to display.

Table 6. Returns Type Description void

g_form.addErrorMessage('This is an error');

GlideForm - addFormMessage(String message, String type)

Displays a floating form message at the top of the form detail section. The message does not cover UI actions.

See also: clearAllFormMessages() clearFormMessages()

Table 7. Parameters Name Type Description message String Message to display. type String The type of message. Valid values: error info warning

Table 8. Returns Type Description None

The following example shows how to add form messages of each type.

g_form.addFormMessage('info message','info'); g_form.addFormMessage('warning message','warning'); g_form.addFormMessage('error message','error'); g_form.addFormMessage('info2 message','info'); g_form.addFormMessage('warning2 message','warning'); g_form.addFormMessage('error2 message','error');

GlideForm - addInfoMessage(String message)

Adds the specified informational message to the top of the form.

This message appears for approximately four seconds and then disappears. This timeout is not configurable at this time.

Table 9. Parameters Name Type Description message String Message to display.

Table 10. Returns Type Description void

g_form.addInfoMessage('The top five fields in this form are mandatory');

GlideForm - addOption(String fieldName, String choiceValue, String choiceLabel)

Adds a choice to the end of a choice list field.

Table 11. Parameters Name Type Description fieldName String The name of the field. choiceValue String The value to be stored in the database. choiceLabel String The value displayed.

Table 12. Returns Type Description void

g_form.addOption('priority', '6', '6 - Really Low');

GlideForm - addOption(String fieldName, String choiceValue, String choiceLabel, Number choiceIndex)

Adds a choice to the list field at the position specified.

Note: Duplicate list labels are not supported in Service Portal . For example, items with label text matching another label are ignored and not added to the list.

Table 13. Parameters Name Type Description fieldName String The field name. choiceValue String The value stored in the database. choiceLabel String The value displayed. choiceIndex Number Order of the choice in the list. The index is into a zero based array.

Table 14. Returns Type Description void

g_form.addOption('priority', '2.5', '2.5 - Moderately High', 3);

GlideForm - clearMessages()

Removes all informational and error messages from the top of the form.

Removes informational and error messages added with g_form.addInfoMessage() and g_form.addErrorMessage() .

Table 15. Parameters Name Type Description None

Table 16. Returns Type Description void

g_form.clearMessages();

GlideForm - clearAllFormMessages()

Removes all form messages of any type.

See also: addFormMessage() clearFormMessages()

Table 17. Parameters Name Type Description None

Table 18. Returns Type Description None

The following example shows how to clear all messages from the form.

g_form.clearAllFormMessages();

GlideForm - clearFormMessages(String type)

Removes all form messages of a given type.

See also: addFormMessage() clearAllFormMessages()

Table 19. Parameters Name Type Description type String The type of message. Valid values: error info warning

Table 20. Returns Type Description None

The following example shows how to clear all error messages from the form.

g_form.clearFormMessages('error');

GlideForm - clearOptions(String fieldName)

Removes all options from the choice list.

Table 21. Parameters Name Type Description fieldName String Name of the field.

Table 22. Returns Type Description void

GlideForm - clearValue(String fieldName)

Removes any value(s) from the field.

Table 23. Parameters Name Type Description fieldName String Name of the field.

Table 24. Returns Type Description void

GlideForm - disableAttachments()

Prevents file attachments from being added.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

Table 25. Parameters Name Type Description None

Table 26. Returns Type Description void

GlideForm - enableAttachments()

Allows file attachments to be added. Shows the paper clip icon.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

Table 27. Parameters Name Type Description None

Table 28. Returns Type Description void

GlideForm - flash(String fieldName, String color, Number count)

Used to draw attention to a particular field. Flashes the specified color for a specified duration of time in the specified field.

This method is not supported by Service Catalog.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

Table 29. Parameters Name Type Description fieldName String Specifies the field to highlight in the following format: " . " . color String RGB color or acceptable CSS color. count Number Specifies how long the label will flash. Options include: 2: Flashes for 1 second 0: Flashes for 2 seconds -2: Flashes for 3 seconds -4: Flashes for 4 seconds

Table 30. Returns Type Description void

g_form.flash("incident.number", "#FFFACD", 0);

GlideForm - getActionName()

Returns the most recent action name, or, for a client script, the sys_id of the UI action clicked.

Note: Not available in Wizard client scripts.

Table 31. Parameters Name Type Description None

Table 32. Returns Type Description String The current action name.

function onSubmit() { var action = g_form.getActionName(); alert('You pressed ' + action); }

GlideForm - getBooleanValue(String fieldName)

Returns a Boolean value for the specified field.

Table 33. Parameters Name Type Description fieldName String Name of the field.

Table 34. Returns Type Description Boolean Returns false if the field value is false or undefined; otherwise returns true.

GlideForm - getControl(String fieldName)

Returns the HTML element for the specified field.

Compound fields may contain several HTML elements. This method is generally not necessary as there are built-in methods that use the fields on a form.

If the field is a reference field and the control is a choice list, getControl() may not return a control as expected. In this case, use sys_select. . .

This method is not available in mobile scripts or Service Portal scripts.

Table 35. Parameters Name Type Description fieldName String Name of the field.

Table 36. Returns Type Description HTMLElement The field's HTML element.

GlideForm - getDecimalValue(String fieldName)

Returns the decimal value of the specified field.

Table 37. Parameters Name Type Description fieldName String The name of the field.

Table 38. Returns Type Description String The decimal value of the specified field.

function onChange(control, oldValue, newValue, isLoading) { alert(g_form.getDecimalValue('percent_complete')); }

GlideForm - getDisplayBox(String fieldName)

Gets the display value from a form in the core UI.

Note: To get a display value from a form in Service Portal , use the getDisplayValue() method.

See also: getValue() Get the display value of a reference variable

Table 39. Parameters Name Type Description fieldName String Name of the field from which you want to retrieve a value in the form.

Table 40. Returns Type Description None

var caller = g_form.getDisplayBox('caller_id').value;

var assignee = g_form.getDisplayBox('assigned_to').value;

if (caller == assignee) { alert('in'); }

GlideForm - getDisplayValue(String fieldName)

Gets the display value from a form in Service Portal .

Note: To get a display value from a form in the core UI, use the getDisplayBox() method.

See also: getValue() Get the display value of a reference variable

Note: In the core UI, calling this method as g_form.getDisplayValue() without an argument returns the record display value rather than the display value of an individual field.

Table 41. Parameters Name Type Description fieldName String Name of the field from which you want to retrieve a value in the form.

Table 42. Returns Type Description None

The following example shows how to get the display value of a reference variable in the core UI or Service Portal . The use case for this example is on the community site.

GlideForm - getElement(String id)

Returns the HTML element specified by the parameter.

Compound fields may contain several HTML elements. This method is generally not necessary as there are built-in methods that use the fields on a form.

This method is not available in mobile scripts or Service Portal scripts.

Table 43. Parameters Name Type Description id String The field id.

Table 44. Returns Type Description HTMLElement The field's HTML element.

GlideForm - getFormElement()

Returns the HTML element for the form.

This method is not available in mobile scripts or Service Portal scripts.

Table 45. Parameters Name Type Description None

Table 46. Returns Type Description HTMLFormElement The HTML element for the form.

GlideForm - getHelpTextControl(String fieldName)

Returns the HTML element of the help text for the specified field.

This method is applicable to service catalog variables only.

Table 47. Parameters Name Type Description fieldName String Name of the field.

Table 48. Returns Type Description HTMLElement Help text field's HTML element.

GlideForm - getIntValue(String fieldName)

Returns the integer value of the field.

Table 49. Parameters Name Type Description fieldName String The field name.

Table 50. Returns Type Description Number Integer value of the field.

GlideForm - getLabelOf(String fieldName)

Returns the plain text value of the field label.

Table 51. Parameters Name Type Description fieldName String The field name

Table 52. Returns Type Description String The label text.

if (g_user.hasRole('itil')) { var oldLabel = g_form.getLabelOf('comments'); g_form.setLabelOf('comments', oldLabel + ' (Customer visible)'); }

GlideForm - getOption(String fieldName, String choiceValue)

Returns the option element for a selected box named fieldName where choiceValue matches the option value.

Note: This method does not work on read-only fields.

Table 53. Parameters Name Type Description fieldName String Name of the field. choiceValue String Value of the option.

Table 54. Returns Type Description HTMLElement The HTMLElement for the option. Returns null if the field or option is not found.

The following example shows how to get the label for a choice list value.

// Get the label for a choice list value // fieldName is 'category' function onChange(control, oldValue, newValue, isLoading) { var choiceValue = g_form.getValue('category'); var choiceLabel = g_form.getOption('category', choiceValue).text; }

GlideForm - getReference(String fieldName, Function callBack)

Returns the GlideRecord for a specified field.

If a callback function is present, this routine runs asynchronously. The browser (and script) processing continues normally until the server returns the reference value, at which time, the callback function is invoked. If a callback function is not present, this routine runs synchronously and processing halts (causing the browser to appear to hang) while waiting on a server response.

Important: It is strongly recommended that you use a callback function.

Callback function support for ServiceCatalogForm.getReference is available.

Note: Using this method requires a call to the server which requires additional time and may introduce latency to your page. Use this method with caution. For additional information, see Client script design and processing .

Table 55. Parameters Name Type Description fieldName String Name of the field. callBack Function Name of the call back function.

Table 56. Returns Type Description GlideRecord GlideRecord object for the specified field. If the specified reference cannot be found, it returns an initialized GlideRecord object where currentRow = -1 and rows.length = 0.

function onChange(control, oldValue, newValue, isLoading) { g_form.getReference('caller_id', doAlert); // doAlert is our callback function } function doAlert(caller) { // reference is passed into callback as first arguments if (caller.getValue('vip') == 'true') { alert('Caller is a VIP!'); } }

GlideForm - getRelatedListNames()

Returns an array of related list names from the current form.

Table 57. Parameters Name Type Description None

Table 58. Returns Type Description Array String array of related list names from the current form. The related list names are listed in the order in which they appear on the form.

var listNames = g_form.getRelatedListNames();

for (var i = 0; i

GlideForm - getSectionNames()

Returns all section names, whether visible or not.

Table 59. Parameters Name Type Description None

Table 60. Returns Type Description Array of strings The section names.

GlideForm - getSections()

Returns an array of the form's sections.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

Table 61. Parameters Name Type Description None

Table 62. Returns Type Description Array of HTML elements The form's sections.

GlideForm - getTableName()

Returns the name of the table to which this record belongs.

On the server side, the table for the current record can be retrieved with current.sys_class_name or current.getTableName() .

Table 63. Parameters Name Type Description None

Table 64. Returns Type Description String Name of the table.

function onLoad() { if (g_form.isNewRecord()) { var tableName = g_form.getTableName(); //Get the table name } }

GlideForm - getUniqueValue()

Returns the sys_id of the record displayed in the form.

Table 65. Parameters Name Type Description None

Table 66. Returns Type Description String The record's sys_id.

function onLoad() { var incSysid = g_form.getUniqueValue(); alert(incSysid); }

GlideForm - getValue(String fieldName)

Returns the value of the specified form field.

This method also supports getting values from a multi-row variable set (MRVS). To obtain data from fields within an MRVS, you must first use JSON.parse(getValue(' ') || '[]') to obtain the MRVS array, and then use indexing to access the fields within the row objects. For more details, see the code example below.

Table 67. Parameters Name Type Description fieldName String Name of the field whose value to return.

Table 68. Returns Type Description String Value of the specified field.

The following example shows how to get the short description from the current form.

function onChange(control, oldValue, newValue, isLoading) { alert(g_form.getValue('short_description')); }

The following example shows how to get values from an MRVS. In this example, salaries are being managed through the Service Catalog. The client script searches all rows within the MRVS for the value entered in the Job title and then updates the matching entries within the MRVS with what is entered in the Salary field. The MRVS is named "variable_set_1" and contains the following fields within each row object: Employee name [employee_name], Job title [employee_job_title], and Salary [employee_salary]. In addition, the Catalog Item contains: Job title [job_title] and Salary [salary].

GlideForm - hideAllFieldMsgs()

Hides all field messages.

Table 69. Parameters Name Type Description None

Table 70. Returns Type Description void

GlideForm - hideAllFieldMsgs(String type)

Hides all field messages of the specified type.

Table 71. Parameters Name Type Description type String The type of message. Valid values: error info

Table 72. Returns Type Description void

GlideForm - hideErrorBox(String fieldName)

Hides the error message placed by showErrorBox() .

Whenever possible, use hideFieldMsg() rather than this method whenever possible.

Table 73. Parameters Name Type Description fieldName String The name of the field or control.

Table 74. Returns Type Description void

GlideForm - hideFieldMsg(String fieldName, Boolean clearAll)

Hides the first message that appears in the specified field on the current form.

Use the GlideForm - showFieldMsg(String field, String message, String type) or GlideForm - showFieldMsg(String field, String message, String type, Boolean scrollForm) methods to display messages on a form.

For example, the following code snippet shows how to display two messages on the work_notes field of a form and then hide the first message: g_form.showFieldMsg('work_notes', 'First message', "error"); g_form.showFieldMsg('work_notes', 'Second message', "error"); g_form.hideFieldMsg('work_notes', false); // This call hides the 'First message'

Table 75. Parameters Name Type Description fieldName String Name of the field. clearAll Boolean Optional. Flag that indicates whether to hide all messages for the specified field. Valid values: true: Hide all messages. false: Only hide the first message being displayed. Default: false

Table 76. Returns Type Description void

The following example shows how to clear all messages for a specified form field and then display an encryption error message.

GlideForm - hideRelatedList(String listTableName)

Hides the specified related list on the form.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

Table 77. Parameters Name Type Description listTableName String Name of the related list. Use the sys_id to hide a list through a relationship.

Table 78. Returns Type Description void

GlideForm - hideRelatedLists()

Hides all related lists on the form.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

Table 79. Parameters Name Type Description None

Table 80. Returns Type Description void

GlideForm - isLiveUpdating()

Returns true while a live update is being done on the record the form is showing.

This can be used in an onChange() client script to determine if a change to the record is because of a live update from another session. The client script can then decide what action to take, or not to take. This applies to systems using Core UI with live forms enabled.

Table 81. Parameters Name Type Description None

Table 82. Returns Type Description Boolean Returns true if a live update is happening on the record displayed by the form.

GlideForm - isMandatory(String fieldName)

Returns true if the field is mandatory.

Table 83. Parameters Name Type Description fieldName String Name of the field.

Table 84. Returns Type Description Boolean True if the field is required, false otherwise.

GlideForm - isNewRecord()

Returns true if the record has never been saved.

Table 85. Parameters Name Type Description None

Table 86. Returns Type Description Boolean Returns true if the record has not been saved; otherwise false.

function onLoad() { if(g_form.isNewRecord()){ alert('New Record!'); } }

GlideForm - isSectionVisible(String sectionName)

Returns true if the section is visible.

Important: The isSectionVisible() function is not supported in Workspace.

Table 87. Parameters Name Type Description None

Table 88. Returns Type Description Boolean Returns true when the section is visible; otherwise, false is returned.

GlideForm - onUserChangeValue(Function fn)

Registers a custom event listener that detects when any field in the current form is modified by a user.

When a form field is modified, the event listener calls the function that is passed in when the listener is initially registered. This listener is only triggered when a user makes a change to a field on the form. Changes from client scripts, UI policies, or any other non-user interactions, do not trigger the listener.

Note: This method does not work for journal fields or Service Catalog items in the classic environment.

Table 89. Parameters Name Type Description fn Function Function to call when a user changes the value of a field within the current form. This is actually the function code, not just the function name. This function must accept the following three arguments:

field name original field value updated field value

Table 90. Returns Type Description Function Function to call to unregister the onUserChangeValue event listener.

var handler = function(fieldname, originalValue, newValue) { console.log('The field ('+ fieldname + ') has a new value of: ' + newValue); // function code } var unregister = g_form.onUserChangeValue(handler); // To unregister the event listener unregister();

GlideForm - refreshSlushbucket(String fieldName)

You can update a list collector variable.

Table 91. Parameters Name Type Description fieldName String Name of the slush bucket.

Table 92. Returns Type Description void

g_form.refreshSlushbucket('bucket');

GlideForm - removeDecoration(String fieldname, String icon, String title)

Removes the icon from the specified field that matches the icon and title.

Note: This method is not supported by Service Catalog.

Table 93. Parameters Name Type Description fieldName String Field name. icon String Name of the icon to remove. title String The icon's text title (name).

Table 94. Returns Type Description void

function onChange(control, oldValue, newValue, isLoading) { // if the caller_id field is not present, then we can't add an icon anywhere if (!g_form.hasField('caller_id')) return; if (!newValue) return; g_form.getReference('caller_id', function(ref) { g_form.removeDecoration('caller_id', 'icon-star', 'VIP'); if (ref.getValue('vip') == 'true') g_form.addDecoration('caller_id', 'icon-star', 'VIP'); }); }

GlideForm - removeDecoration(String fieldname, String icon, String title, String color)

Removes the icon from the specified field that matches the icon, title, and color.

Note: This method is not supported by Service Catalog.

Table 95. Parameters Name Type Description fieldName String Field name. icon String Name of the icon to remove. title String The icon's text title (name). color String A CSS color

Table 96. Returns Type Description void

g_form.removeDecoration('caller_id', 'icon-star', 'VIP', 'blue');

GlideForm - removeOption(String fieldName, String choiceValue)

Removes the specified option from the choice list.

Table 97. Parameters Name Type Description fieldName String Name of the field. choiceValue String The value stored in the database. This is not the label.

Table 98. Returns Type Description void

g_form.removeOption('priority', '1');

GlideForm - save()

Saves the record without navigating away (update and stay).

Table 99. Parameters Name Type Description None

Table 100. Returns Type Description void

GlideForm - setMandatory(String fieldName, Boolean mandatory)

Makes the specified field mandatory.

Whenever possible, use a UI policy rather than this method.

Table 101. Parameters Name Type Description fieldName String Name of the field. mandatory Boolean When true makes the field mandatory. When false makes the field optional.

Table 102. Returns Type Description void

GlideForm - setSectionDisplay(String sectionName, Boolean display)

Shows or hides a section.

Table 103. Parameters Name Type Description sectionName String The section name is lower case with an underscore replacing the first space in the name, and with the remaining spaces being removed, for example "Section Four is Here" becomes "section_fourishere". Other non-alphanumeric characters, such as ampersand (&), are removed. Section names can be found by using the getSectionNames() method. display Boolean When true shows the section. When false hides the section.

Table 104. Returns Type Description Boolean Returns true when successful.

GlideForm - setValue(String fieldName, String value, String displayValue)

Sets the value of a specified form field to the value of a specified display value in a reference record.

To improve performance by preventing a round trip when setting the value for a reference field, use this method, not setValue(fieldName, value) . When setting multiple reference values for a list collector field, pass arrays in the value and displayValue parameters.

Note: The method setValue() can cause a stack overflow when used in an OnChange client script. This is because every time the value is set, it will register as a change, which may re-trigger the OnChange client script. To prevent this, perform a check that will validate that the new value will be different from the old value. For example, before performing setValue(shortDesc, newValue.toUpperCase()); , validate that the short description is not already uppercase. This will prevent the client script from applying the toUpperCase() more than once.

Table 105. Parameters Name Type Description fieldName String Name of the form field to update. value String or Array Sys_id of the reference record to use to update the field. If the specified field is a GlideList, this parameter can contain an array of sys_ids. In this case, the method performs a lookup of all records specified in the array and those values are used to update the contents of the specified field (related list).

Note: When defining a value in a choice list, be sure to use number value rather than the label. displayValue String or Array Field within the specified reference record to use to update the specified field. For example, in the User [sys_user] table it might be userName. If the specified field is a GlideList, this parameter can contain an array of display value names.

For additional information on display values, see Display value .

Table 106. Returns Type Description void

This example shows passing the sys_id of the reference record that contains the userName field to use to update the assigned_to form field.

g_form.setValue('assigned_to', userSysID, userName);

This example shows passing an array of reference record sys_ids and an array of corresponding display value names to use to update the form fields in the GlideList glide-list_field_name .

g_form.setValue('glide-list_field_name', sysIDArray, displayNameArray);

GlideForm - showErrorBox(String name, String message, Boolean scrollForm)

Displays an error message under the specified form field (either a control object or the name of the field). If the control or field is currently off the screen and the scrollForm parameter is true, the form scrolls to the control or field.

A global property (glide.ui.scroll_to_message_field) is available that controls automatic message scrolling when the form field is off screen (scrolls the form to the control or field). The showFieldMsg() method is a similar method that requires a type parameter.

Table 107. Parameters Name Type Description name String Name of the field or control. message String Message to display. scrollForm Boolean When true scrolls the form to the field. When false the form does not scroll to the field.

Table 108. Returns Type Description void

GlideForm - showFieldMsg(String field, String message, String type)

Displays either an informational or error message under the specified form field (either a control object or the name of the field). If the control or field is off the screen, the form is scrolled to the field.

A global property (glide.ui.scroll_to_message_field) is available that controls automatic message scrolling when the form field is off screen (scrolls the form to the control or field).

The showErrorBox() method is a shorthand method that does not require the type parameter.

Note: This method does not work with the journal_field type field in Core UI .

Table 109. Parameters Name Type Description field String Name of the field or control. message String Message to display. type String "error","info", or "warning".

Table 110. Returns Type Description void

g_form.showFieldMsg('impact','Low impact response time can be one week','info');

GlideForm - showFieldMsg(String field, String message, String type, Boolean scrollForm)

Displays either an informational or error message under the specified form field (either a control object or the name of the field). If the control or field is currently off the screen and scrollForm is true, the form is scrolled to the field.

A global property (glide.ui.scroll_to_message_field) is available that controls automatic message scrolling when the form field is off screen (scrolls the form to the control or field).

The showErrorBox() method is a shorthand method that does not require the type parameter.

Note: This method does not work with the journal_field type field in Core UI .

Table 111. Parameters Name Type Description field String Name of the field or control. message String Message to display. type String "error","info", or "warning". scrollForm Boolean When true, the form scrolls to the field if it is off screen. When false, the form does not scroll.

Table 112. Returns Type Description void

g_form.showFieldMsg('impact','Low impact not allowed with High priority','error',false);

GlideForm - setDisabled(String fieldName, Boolean disable)

Makes the specified field available or unavailable.

Table 113. Parameters Name Type Description fieldName String Name of the field. disable Boolean When true disables the field. When false enables the field.

Table 114. Returns Type Description void

GlideForm - setDisplay(String fieldName, Boolean display)

Displays or hides a field.

This method cannot hide a mandatory field with no value. If the field is hidden, the space is used to display other items. Whenever possible, use a UI policy instead of this method.

Table 115. Parameters Name Type Description fieldname String Name of the field. display Boolean When true displays the field, when false hides the field.

Table 116. Returns Type Description void

function onChange(control, oldValue, newValue, isLoading, isTemplate) { //If the page isn't loading if (!isLoading) { //If the new value isn't blank if (newValue != '') { g_form.setDisplay('priority', false); } else g_form.setDisplay('priority', true); } }

GlideForm - setLabelOf(String fieldName, String label)

Sets the plain text value of the field label.

Note: This method is not supported by Service Catalog.

Table 117. Parameters Name Type Description fieldName String The field name. label String The field text label.

Table 118. Returns Type Description void

if (g_user.hasRole('itil')) { var oldLabel = g_form.getLabelOf('comments'); g_form.setLabelOf('comments', oldLabel + ' (Customer visible)'); }

GlideForm - setReadOnly(String fieldName, Boolean readOnly)

Makes the specified field read-only or editable.

Whenever possible, use a UI policy instead of this method.

To make a mandatory field read-only, you must first remove the mandatory requirement for that field by using the setMandatory() method.

Once you set a field to read-only, you cannot use the setValue() method to update the value of that field. If you need to set the value in this way, you must set the readOnly value to false.

Table 119. Parameters Name Type Description fieldName String Name of the field. readOnly Boolean Flag that determines whether the associate field is editable or read-only. Possible values: true: Set field to read-only false: Set field to be editable

Table 120. Returns Type Description None

The following example shows how set the Variable Editor to read only. To do this in Service Catalog tables, use setVariablesReadOnly() .

// Create a Client Script on a table (e.g., incident) and paste this script // Uncheck (set to false) the "isolate script" checkbox (not available by default) // To add the isolate script checkbox to the form, configure form layout to add the checkbox function onLoad() { $("variable_map").querySelectorAll("item").forEach(function(item){ var variable = item.getAttribute("qname"); g_form.setReadOnly("variables."+ variable, true); }); }

GlideForm - setValue(String fieldName, String value)

Sets the value of a specified form field to the passed in value.

This method also supports setting values in a multi-row variable set (MRVS). You must first use JSON.parse(getValue(' ')) to obtain the MRVS array and then use indexing to update the fields within the row objects. Once all values are updated in the MRVS, use the setValue() method to save the updated MRVS array. For more details, see the code example below.

Note: The method setValue() can cause a stack overflow when used in an OnChange client script. This is because every time the value is set, it will register as a change, which may re-trigger the OnChange client script. To prevent this, perform a check that will validate that the new value will be different from the old value. For example, before performing setValue(shortDesc, newValue.toUpperCase()); , validate that the short description is not already uppercase. This will prevent the client script from applying the toUpperCase() more than once.

Note: When defining a value in a choice list, be sure to use the number value rather than the label.

Table 121. Parameters Name Type Description fieldName String Name of the form field to update. value String String value to set in the specified field.

Table 122. Returns Type Description void

The following example shows how to set the short description in the current form.

g_form.setValue('short_description', 'replace this with appropriate text');

The following example shows how to set values in an MRVS. In this example, salaries are being managed through the Service Catalog. The client script searches all rows within the MRVS for the value entered in the Job title and then updates the matching entries within the MRVS with what is entered in the Salary field. The MRVS is named "variable_set_1" and contains the following fields within each row object: Employee name [employee_name], Job title [employee_job_title], and Salary [employee_salary]. In addition, the Catalog Item contains: Job title [job_title] and Salary [salary].

function onChange(control, oldValue, newValue, isLoading) { if (isLoading || newValue == '') { return; }

// Get the MRVS var multiRowVariableSet = JSON.parse(g_form.getValue('variable_set_1'));

for (var i = 0; i < multiRowVariableSet.length; i++) { // Check if the entered job title matches the title in the current MRVS row if (multiRowVariableSet[i].employee_job_title == g_form.getValue("job_title")){ // Update the value of a matching field with the new salary multiRowVariableSet[i].employee_salary = newValue; } }

// Update the MRVS g_form.setValue('variable_set_1', JSON.stringify(multiRowVariableSet)); }

GlideForm - setVariablesReadOnly(Boolean isReadOnly)

Makes a Service Catalog variable editor read only.

Note: This method is only applicable to Service Catalog variable editors in the core UI. This method is not supported in the Service Catalog form.

The method must be placed in the client script of the table in which the variable editor is added, such as Requested Item [sc_req_item], Incident [incident], and so on. To set variables to read only in other tables, use the setReadOnly() method.

See also: Service Catalog variable editors

Table 123. Parameters Name Type Description isReadOnly Boolean Flag that determines whether the variable editor is read only. Possible values: true: Sets the variable editor as read-only. false: Sets the variable editor as editable.

Default: false

Table 124. Returns Type Description None

Adding the following line to a client script sets the variable editor to read only.

g_form.setVariablesReadOnly(true);

GlideForm - setVisible(String fieldName, Boolean display)

Displays or hides the field.

On desktop UI, the space is left blank when hidden. On Mobile or Service Portal UI, the space is filled in my other fields when hidden. This method cannot hide mandatory fields with no value.

Use UI Policy rather than this method whenever possible.

Table 125. Parameters Name Type Description fieldName String The field name. display Boolean When true displays the field. When false hides the field.

Table 126. Returns Type Description void

function onChange(control, oldValue, newValue, isLoading, isTemplate) { //If the page isn't loading if (!isLoading) { //If the new value isn't blank if(newValue != '') { g_form.setVisible('priority', false); } else g_form.setVisible('priority', true); } }

GlideForm - showErrorBox(String name, String message)

Displays an error message under the specified form field (either a control object or the name of the field). If the control or field is currently off the screen, the form scrolls to the control or field.

A global property (glide.ui.scroll_to_message_field) is available that controls automatic message scrolling when the form field is off screen (scrolls the form to the control or field). The showFieldMsg() method is a similar method that requires a type parameter.

Table 127. Parameters Name Type Description name String The name of the control or field. message String The message to be displayed.

Table 128. Returns Type Description void

GlideForm - showRelatedList(String listTableName)

Displays the specified related list on the form.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

Table 129. Parameters Name Type Description listTableName String Name of the related list.

Table 130. Returns Type Description void

GlideForm - showRelatedLists()

Displays all the form's related lists.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

Table 131. Parameters Name Type Description None

Table 132. Returns Type Description void

GlideForm - submit()

Saves the record.

The user is taken away from the form, returning them to where they were.

Table 133. Parameters Name Type Description None

Table 134. Returns Type Description void

GlideForm - submit(String verb)

Performs the UI action specified by the parameter.

Table 135. Parameters Name Type Description verb String An action_name from a sys_ui_action record. The action name must be for a visible form button.

Table 136. Returns Type Description void