Page History

This class provides methods to configure forms. These methods can be used on the client side only.

You can also use these methods to configure the dependencies between fields and values. For example, changing values in the fields or clear the fields.

SimpleForm(table, sys_id)

Instantiates a new SimpleForm object.

Name	Type	Mandatory	Default Value
table	String	Y	N
sys_id	String	Y	N

Code Block

language	js
theme	Eclipse
title	SimpleForm
linenumbers	true

const formObject = new SimpleForm(s_form.table, s_form.sysId);

Return:

Type	Description
Object	This method returns a form object.

s_form.addErrorMessage(message)

This method displays the error toast message in the bottom right corner.

Parameter(s):

Name	Type	Mandatory	Default Value
message	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	addErrorMessage
linenumbers	true

s_form.addErrorMessage('Need more information');

s_form.addInfoMessage(message, durationMilliseconds)

This method displays an informational toast message in the bottom right corner. The message is expirable, its expire period (in milliseconds) should be specified by second parameter.

Parameter(s):

Name	Type	Mandatory	Default Value
message	String	Y	N
durationMilliseconds	Number	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	addInfoMessage
linenumbers	true

s_form.addInfoMessage('Record successfully created', 1000);

s_form.addOption(fieldName, choiceValue)

This method adds a choice option to the end of the choice list field (if option with passed choiceValue defined for fieldName for current table options set).

Note
Please note that this method is asynchronous; for better performing, use the await keyword like shown in the code example below.

Parameter(s):

Name	Type	Mandatory	Default Value
fieldName	String	Y	N
choiceValue	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	addOption
linenumbers	true

const states = ['-1', '0', '2', '5'];
s_form.clearOptions('state');
states.forEach(stateValue => {
    await s_form.addOption('state', stateValue);
}

s_form.clearMessages()

This method is used to close all kinds of messages (both informational and error) in the form.

Return:

Type	Description
Void	This method does not return a value.

Code Block

language	js
theme	Eclipse
title	clearMessages()
linenumbers	true

s_i18n.getMessage('End date time cannot be less than start date time', (response) => {
  s_form.clearMessages();
  s_form.addErrorMessage(response);
  return false; // abort form submit
});

s_form.clearOptions(fieldName)

Using this method, you can remove all options from the choice list.

Parameter(s):

Name	Type	Mandatory	Default Value
fieldName	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	clearOptions
linenumbers	true

const choices =
  {
    "Phone": "10",
    "Email": "20",
    "Self-service": "30"
  };
const choicesArray = Object.keys(choices);
s_form.clearOptions('contact_type');
choicesArray.forEach((choiceValue) => {
  s_form.addOption('contact_type', choices[choiceValue]);
});

s_form.clearValue(fieldName)

This method is used to clear out any field, i.e., delete its value.

Using this method you can select a value and remove it from the field.

It returns TRUE if it is able to clear the value from the field.

It returns FALSE in the following cases:

if the column_type is either Boolean or Record Class;
if the column_name is equal to 'sys_id';
if the column_type is Choice and it does not have a default value.

If the method returns FALSE, then the field. will not be cleared.

Parameter(s):

Name	Type	Mandatory	Default Value
fieldName	String	Y	N

Return:

Type	Description
Boolean	This method returns the boolean value (TRUE or FALSE) in the cases described above.

Example:

Code Block

language	js
theme	Eclipse
title	clearValue
linenumbers	true

if (!s_form.getValue('sprint')) {
  s_form.clearValue('points');
}

s_form.getLabelOf(fieldName)

The method returns the label text value.

Parameter(s):

Name	Type	Mandatory	Default Value
fieldName	String	Y	N

Return:

Type	Description
String	The label text.

Example:

Code Block

language	js
theme	Eclipse
title	getLabelOf
linenumbers	true

if (s_form.getValue('name').match(/[\/|_*]/g)) {
  s_form.addErrorMessage(`Field "s_form.getLabelOf('name')" contains invalid characters.`);
}

s_form.getSections()

Using this method, you can get an array of sections.

Return:

Type	Description
Array of HTML elements	The form sections.

s_form.getSectionNames()

This method allows returning an array, which will contain the names of all sections, visible or not.

Return:

Type	Description
Array of strings	This method returns array containing section names.

s_form.getUniqueValue()

This method returns the unique record ID (sys_id).

Return:

Type	Description
String	Returns the record ID; otherwise, returns NULL.

Example:

Code Block

language	js
theme	Eclipse
title	getUniqueValue
linenumbers	true

const sysId = s_form.getUniqueValue();
const currentRecord = new SimpleRecord(s_form.table);
currentRecord.get(sysId, ()=> {
  if (currentRecord.type == 'unavailable') {
    return false; // abort form submit
  }
});

s_form.getValue(fieldName)

This method returns the internal (written down to the database) value of the specified field.

Warning
IsDisplayValue parameter was maintained in earlier versions but has been deprecated from version 1.1 and no longer valid. Avoid using it in your scripts. To get a displayed value of a field, use the s_form.getDisplayValue method.

Parameter(s):

Name	Type	Mandatory	Default Value
fieldName	String	Y	N

Return:

Type	Description
String	This method returns the internal (written down to the database) value of the specified field.

Example:

Code Block

language	js
theme	Eclipse
title	getValue
linenumbers	true

const callerId = s_form.getValue('caller_id');
if (!callerId) {
  const callerRecord = new SimpleRecord('employee');
  callerRecord.get(callerId, ()=> {
    if (!!callerRecord.sys_id &&
      callerRecord.personal_schedule) {
      await s_form.setValue('schedule', callerRecord.personal_schedule);
    } else {
      s_form.addInfoMessage('Users schedule is not defined');
    }
  });
}

s_form.getDisplayValue(fieldName)

This method returns the displayed value of the field.

Parameter(s):

Name	Type	Mandatory	Default value
fieldName	String	Y	N

Return:

Type	Description
String	The displayed value of the specified field.

Example:

Code Block

language	js
theme	Eclipse
title	getDisplayValue
linenumbers	true

s_form.addInfoMessage(`Service "${s_form.getDisplayValue('service')}" is no available`);

s_form.hideFieldMsg(input)

This method, as opposed to the s_form.showFieldMsg() method, allows to hide informational or error messages on the specified form field.

Parameter(s):

Name	Type	Mandatory	Default Value
input	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	hideFieldMsg
linenumbers	true

if (!!s_form.getValue('state')) {
  s_form.hideFieldMsg('state');
}

s_form.hideRelatedLists()

Using this method, you can hide all related lists on the form.

Return:

Type	Description
Void	This method does not return a value.

Code Block

language	js
theme	Eclipse
title	hideRelatedList
linenumbers	true

if (s_form.getValue('type') == 'internal') {
  s_form.hideRelatedLists();
}

s_form.hideRelatedList(relListTitle)

Using this method, you can specify a related list you want to hide.

Parameter(s):

Name	Type	Mandatory	Default Value
relListTitle	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	hideRelatedList
linenumbers	true

if (s_form.getValue('type') == 'external') {
  s_form.hideRelatedList('Customer');
}

s_form.isNewRecord()

If the record was never saved, this method returns TRUE; otherwise, it returns FALSE.

Return:

Type	Description
Boolean	If the record was never saved then this method returns TRUE; otherwise, it returns FALSE.

Example:

Code Block

language	js
theme	Eclipse
title	isNewRecord
linenumbers	true

if (!!s_form.isNewRecord()) {
  await s_form.setValue('state', 'new');
  s_form.setReadOnly('state', true);
}

s_form.isSectionVisible(sectionName)

This method defines if a specified section is visible or not.

Parameter(s):

Name	Type	Mandatory	Default Value
sectionName	string	Y	N

Return:

Type	Description
Boolean	This method returns TRUE if the section is visible; otherwise, it returns FALSE.

Code Block

language	js
theme	Eclipse
title	getSectionNames
linenumbers	true

if (s_form.isSectionVisible('Instructions')) {
  s_form.addInfoMessage('Check out the "Instructions" section', 5000);
}

s_form.removeOption(fieldName, choiceValue)

Using this method, you can specify and delete an option from the list.

Parameter(s):

Name	Type	Mandatory	Default Value
fieldName	String	Y	N
choiceValue	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	removeOption
linenumbers	true

const serviceId = s_form.getValue('service');
if (!!serviceId) {
  const service = new SimpleRecord('sys_cmdb_ci_service');
  service.get(serviceId, ()=> {
    if (service.business_criticality > '1') {
      s_form.removeOption('impact', 'low');
      s_form.removeOption('urgency', 'low');
    }
  });
}

s_form.save()

This method saves the record without leaving its form (just updating).

Return:

Type	Description
Object	This method returns a promise containing specific data.

Code Block

language	js
theme	Eclipse
title	save()
linenumbers	true

s_form.save().finally(__resolveServerResponse);

s_form.setLabelOf(fieldName, value)

This method sets the text value of the field label.

Parameter(s):

Name	Type	Mandatory	Default Value
fieldName	String	Y	N
value	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	setLabelOf
linenumbers	true

if (s_form.table == 'user') {  
  s_form.setLabelOf('email', 'Email'); 
} else {
  s_form.setLabelOf('email', 'Personal Email'); 
}

s_form.setSectionMandatory(sectionName, mandatory)

This method allows making the specified section mandatory.

Parameter(s):

Name	Type	Mandatory	Default Value
sectionName	String	Y	N
mandatory	Boolean	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	setSectionMandatory
linenumbers	true

if (s_form.getValue('state') == '7') { // Completed
  s_form.setSectionDisplay('Closure Information', true);
  s_form.setSectionMandatory('Closure Information', true);
  s_form.setMandatory('closure_code', true);
  s_form.setMandatory('closure_notes', true);
}

s_form.setMandatory(fieldName, mandatory)

This method is used to change a specified field to mandatory field, i.e., it cannot be null.

Parameter(s):

Name	Type	Mandatory	Default Value
fieldName	String	Y	N
mandatory	Boolean	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	setMandatory
linenumbers	true

const mandatoryColumn =
  (scriptType == 'onChange' || scriptType == 'onCellEdit');
s_form.setMandatory('column_id', mandatoryColumn);

s_form.setReadOnly(fieldName, readOnly)

This method is used to change a specified field to read-only or editable.

If the field is mandatory, it cannot be set to read-only. First, use the s_form.setMandatory() method and then make it read-only.

Parameter(s):

Name	Type	Mandatory	Default Value
fieldName	String	Y	N
readOnly	Boolean	Y	N

Return:

Type	Description
Void	This method does not return a value

Example:

Code Block

language	js
theme	Eclipse
title	setReadOnly
linenumbers	true

if (!!s_form.getValue('any_tables')){
  s_form.setReadOnly('table_id', true);
  s_form.setMandatory('table_id', false);
  s_form.setVisible('table_id', false);
}

s_form.setSectionDisplay(sectionName, display)

Using this method, you can specify a section you want to hide.

Parameter(s):

Name	Type	Mandatory	Default Value
sectionName	String	Y	N
display	Boolean	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	setSectionDisplay
linenumbers	true

if (s_form.getValue('state') == '7') { // Completed
  s_form.setSectionDisplay('Closure Information', true);
  s_form.setSectionMandatory('Closure Information', true);
  s_form.setMandatory('closure_code', true);
  s_form.setMandatory('closure_notes', true);
} else {
  s_form.setMandatory('closure_code', false);
  s_form.setMandatory('closure_notes', false);
  s_form.setSectionDisplay('Closure Information', false);
  s_form.setSectionMandatory('Closure Information', false);
}

s_form.setValue(fieldName, databaseValue)

This method sets the field value.

Warning
IsDisplayValue parameter has been maintained in earlier versions but will be deprecated after version 1.1. Avoid using it in your scripts.

Note

Use s_form.clearValue() method for field clearing instead of setting an empty string value.

Also please note that this method is asynchronous; for better performing, use the await keyword like shown in the code example below.

Parameter(s):

Name	Type	Mandatory	Default Value
fieldName	String	Y	N
databaseValue	String	Y	N

Return:

Type	Description
Void	This method returns a Promise object.

Example:

Code Block

language	js
theme	Eclipse
title	setValue
linenumbers	true

await s_form.setValue('state', '7'); // Completed
await s_form.setValue('closure_notes', articleBodies.join('\n'));
await s_form.setValue('closure_code', '1'); // Solved 1st Level
s_form.save()
  .then(() => {
    s_i18n.getMessage(`The typical solution is applied`, (e) => {
      s_form.addInfoMessage(e);
    })
  });

s_form.setVisible(fieldName, display)

This method allows making a field visible or hidden.

If the field is hidden, then the space is left blank. An empty mandatory field cannot be hidden.

Parameter(s):

Name	Type	Mandatory	Default Value
fieldName	String	Y	N
display	Boolean	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	setVisible
linenumbers	true

s_form.setVisible('chronology', !s_form.isNewRecord());

s_form.showFieldMsg(fieldName, message, type)

This method is used to display a message containing 'info', 'error', or 'warning' value under the specified form field.

Parameter(s):

Name	Type	Mandatory	Default Value
fieldName	String	Y	N
message	String	Y	N
type	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	showFieldMsg
linenumbers	true

s_form.showFieldMsg('subject', 'Cannot be empty', 'info');

Code Block

language	js
theme	Eclipse
title	showFieldMsg
linenumbers	true

s_form.showFieldMsg('subject', 'Cannot be empty', 'warning');

Code Block

language	js
theme	Eclipse
title	showFieldMsg
linenumbers	true

s_form.showFieldMsg('subject', 'Cannot be empty', 'error');

s_form.showRelatedLists()

This method allows displaying all lists related to the form.

Return:

Type	Description
Void	This method does not return a value.

s_form.showRelatedList(listTitle)

This method allows displaying the specified lists related to the form.

Parameter(s):

Name	Type	Mandatory	Default Value
listTitle	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

Code Block

language	js
theme	Eclipse
title	showRelatedList
linenumbers	true

s_form.showRelatedList('UI Action');

s_form.submit()

This method allows to submit the record form.

Return:

Type	Description
Void	This method does not return a value.

Table of Contents

absoluteUrl	true

Page tree

Versions Compared

Old Version 94

New Version 95

Key

SimpleForm(table, sys_id)

s_form.addErrorMessage(message)

s_form.addInfoMessage(message, durationMilliseconds)

s_form.addOption(fieldName, choiceValue)

s_form.clearMessages()

s_form.clearOptions(fieldName)

s_form.clearValue(fieldName)

s_form.getLabelOf(fieldName)

s_form.getSections()

s_form.getSectionNames()

s_form.getUniqueValue()

s_form.getValue(fieldName)

s_form.getDisplayValue(fieldName)

s_form.hideFieldMsg(input)

s_form.hideRelatedLists()

s_form.hideRelatedList(relListTitle)

s_form.isNewRecord()

s_form.isSectionVisible(sectionName)

s_form.removeOption(fieldName, choiceValue)

s_form.save()

s_form.setLabelOf(fieldName, value)

s_form.setSectionMandatory(sectionName, mandatory)

s_form.setMandatory(fieldName, mandatory)

s_form.setReadOnly(fieldName, readOnly)

s_form.setSectionDisplay(sectionName, display)

s_form.setValue(fieldName, databaseValue)

s_form.setVisible(fieldName, display)

s_form.showFieldMsg(fieldName, message, type)

s_form.showRelatedLists()

s_form.showRelatedList(listTitle)

s_form.submit()