You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 83 Next »

The SimpleForm API provides methods for customizing 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.

NameTypeMandatoryDefault Value
tableStringYN
sys_idStringYN
SimpleForm
const formObject = new SimpleForm(s_form.table, s_form.sysId);


Return:

TypeDescription
ObjectThis method returns a form object.

s_form.addErrorMessage(message)


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


Parameter(s):

NameTypeMandatoryDefault Value
messageStringYN


Return:

TypeDescription
VoidThis method does not return a value.


Example:

addErrorMessage
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):

NameTypeMandatoryDefault Value
messageStringYN
durationMillisecondsNumberYN


Return:

TypeDescription
VoidThis method does not return a value.


Example:

addInfoMessage
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).

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


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN
choiceValueStringYN


Return:

TypeDescription
VoidThis method does not return a value.


Example:

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

s_form.clearMessages()


This method removes informational messages or error messages in the top of the form.


Return:

TypeDescription
VoidThis method does not return a value.
clearMessages()
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)


This method allows removing all options from the choice list.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN


Return:

TypeDescription
VoidThis method does not return a value.


Example:

clearOptions
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 allows removing any value from any 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):

NameTypeMandatoryDefault Value
fieldNameStringYN


Return:

TypeDescription
BooleanThis method returns the boolean value (TRUE or FALSE) in the cases described above.


Example:

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

s_form.formId()


This class option returns the current form ID for authorized user.


Return:

TypeDescription
StringReturns the record form ID.


Example:


formId


s_form.getLabelOf(fieldName)


This method returns the text value of the field label.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN


Return:

TypeDescription
StringThe label text.


Example:

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

s_form.getSections()


This method allows returning the array of the sections.


Return:

TypeDescription
Array of HTML elementsThe form sections.

s_form.getSectionNames()


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


Return:

TypeDescription
Array of stringsThis method returns array containing section names.

s_form.getUniqueValue()


Returns the unique ID (sys_id) of the record displayed on the form.

Return:

TypeDescription
StringReturns the record ID; otherwise, returns NULL.


Example:

getUniqueValue
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)


Returns the internal (written down to the database) value of the specified field.

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):

NameTypeMandatoryDefault Value
fieldNameStringYN


Return:

TypeDescription
String

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


Example:

getValue
const callerId = s_form.getValue('caller_id');
if (!callerId) {
  const callerRecord = new SimpleRecord('employee');
  callerRecord.get(callerId, ()=> {
    if (!!callerRecord.sys_id &&
      callerRecord.personal_schedule) {
      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):

NameTypeMandatoryDefault value
fieldNameStringYN

Return:

TypeDescription
StringThe displayed value of the specified field.

Example:

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

s_form.getREMDisplayValue(fieldName)


This method gets the displayable REM attribute value.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN

Return:

TypeDescription
StringMethod returns attribute displayable value.

Example:

getREMDisplayValue

s_form.getREMLabelOf(fieldName)


This message gets the plain text value of the REM attribute label.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN

Return:

TypeDescription
StringThis method returns string containing attribute label value.

Example:

getREMLabelOf

s_form.getREMValue(fieldName)


This method gets the attribute value.

Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN

Return:

TypeDescription
ObjectThis method returns the current attribute object.

Example:

getREMValue

s_form.hasChanges()


This method allows to get information whether a record form has been changed or not.


Return:

TypeDescription
BooleanThe method returns 'true' if any changes were made on the record form; otherwise, it returns 'false'.

Example:

hasChanges
if (s_form.hasChanges()) {
    s_form.save().then(() => s_form.goBack());
} else {
    s_form.goBack();
}

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):

NameTypeMandatoryDefault Value
inputStringYN

Return:

TypeDescription
VoidThis method does not return a value.

Example:

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

s_form.hideRelatedLists()


This method allows hiding all related lists on the form.


Return:

TypeDescription
VoidThis method does not return a value.
hideRelatedList
if (s_form.getValue('type') == 'internal') {
  s_form.hideRelatedLists();
}

s_form.hideRelatedList(relListTitle)


This method allows hiding the specified related list on the form.


Parameter(s):

NameTypeMandatoryDefault Value
relListTitleStringYN


Return:

TypeDescription
VoidThis method does not return a value.


Example:

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

s_form.goBack()


This method allows to perform redirect to the previous page; if not possible then redirect direction is a list view of the current essence (for example, to a list of incidents out of a incident record).


Return:

TypeDescription
VoidThis method does not return a value.

Example:

goBack
if (s_form.hasChanges()) {
    s_form.save().then(() => s_form.goBack());
} else {
    s_form.goBack();
}

s_form.isNewRecord()


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


Return:

TypeDescription
BooleanIf the record was never saved then this method returns TRUE; otherwise, it returns FALSE.


Example:

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

s_form.isSectionVisible(sectionName)


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


Parameter(s):

NameTypeMandatoryDefault Value
sectionNamestringYN


Return:

TypeDescription
BooleanThis method returns TRUE if the section is visible; otherwise, it returns FALSE.
getSectionNames
if (s_form.isSectionVisible('Instructions')) {
  s_form.addInfoMessage('Check out the "Instructions" section', 5000);
}

s_form.removeOption(fieldName, choiceValue)


This method removes the selected option from the list.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN
choiceValueStringYN


Return:

TypeDescription
VoidThis method does not return a value.


Example:

removeOption
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 going away (just updating).


Return:

TypeDescription
ObjectThis method returns a promise containing specific data.
save()
s_form.save().finally(__resolveServerResponse);


s_form.setLabelOf(fieldName, value)


This method sets the text value of the field label.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN
valueStringYN


Return:

TypeDescription
VoidThis method does not return a value.


Example:

setLabelOf
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. Use UI policy instead of this method if possible.


Parameter(s):

NameTypeMandatoryDefault Value
sectionNameStringYN
mandatoryBooleanYN


Return:

TypeDescription
VoidThis method does not return a value.


Example:

setSectionMandatory
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 allows making the specified field mandatory. Use UI policy instead of this method if possible.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN
mandatoryBooleanYN


Return:

TypeDescription
VoidThis method does not return a value


Example:

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

s_form.setReadOnly(fieldName, readOnly)


This method allows making the specified field read-only or editable.

Use UI policy instead of this method if possible.

To make a mandatory field read-only, formerly make it non-mandatory using the setMandatory() method.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN
readOnlyBooleanYN


Return:

TypeDescription
VoidThis method does not return a value


Example:

setReadOnly
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)


This method allows to show or hide a section.


Parameter(s):

NameTypeMandatoryDefault Value
sectionNameStringYN
displayBooleanYN


Return:

TypeDescription
VoidThis method does not return a value.


Example:

setSectionDisplay
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, value)


This method sets the field value. 

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

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):

NameTypeMandatoryDefault Value
fieldNameStringYN
valueStringYN


Return:

TypeDescription
VoidThis method does not return a value.


Example:

setValue
if (!!s_form.isNewRecord()) {
  s_form.setValue('name', 'Name created by system');
}

s_form.setREMLabelOf(fieldName, value)


This method allows changing the displayable attribute label.

Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN
valueStringYN

Return:

TypeDescription
StringThis method returns new value of the attribute label.

Example:

setREMLabelOf

s_form.setREMMandatory(fieldName, mandatory)


This method allows to make a field specified by REM attribute mandatory.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN
mandatoryBooleanY'true'

Return:

TypeDescription
BooleanThis method returns "true" if its execution has been successful; otherwise, it returns "false".

Example:

setREMMandatory

s_form.setREMReadOnly(fieldName, readonly)


This method allows to make a field specified by REM attribute read-only.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN
readonlyBooleanY'true'


Return:

TypeDescription
BooleanThis method returns "true" if its execution has been successful; otherwise, it returns "false".

Example:

setREMReadOnly

s_form.setREMValue(fieldName, databaseValue)


This method allows to set a value of the REM attribute label.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN
databaseValueObjectYN


Return:

TypeDescription
VoidThis method does not return a value.

Example:

setREMValue

s_form.setREMVisiblle(fieldName, display)


This method allows to define visibility of the field specified by REM attribute.

Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN
displayBooleanYN

Return:

TypeDescription
VoidThis method does not return a value.

Example:

setREMvisible

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. This method cannot hide mandatory field without any value.

Use UI policy instead of this method if possible.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN
displayBooleanYN


Return:

TypeDescription
VoidThis method does not return a value.


Example:

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

s_form.showFieldMsg(fieldName, message, type)


This method displays a message under the specified form field. Possible type values - 'info', 'error', or 'warning'.


Parameter(s):

NameTypeMandatoryDefault Value
fieldNameStringYN
messageStringYN
typeStringYN


Return:

TypeDescription
VoidThis method does not return a value.


Example:

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

s_form.showRelatedLists()


This method allows displaying all lists related to the form.


Return:

TypeDescription
VoidThis method does not return a value.

s_form.showRelatedList(listTitle)


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


Parameter(s):

NameTypeMandatoryDefault Value

listTitle

StringYN


Return:

TypeDescription
VoidThis method does not return a value.

Example:

showRelatedList
s_form.showRelatedList('UI Action');

s_form.submit()


This method allows to submit the record form.


Return:

TypeDescription
VoidThis method does not return a value.

  • No labels