SimpleForm

This class provides methods for forms configurations. These methods can only be used on the client side.

You can also use these methods to configure the dependencies between the fields and the values, for example, changing the values of the fields or clearing the fields. 

SimpleForm(table, sys_id)

Use this constructor to instantiate a new SimpleForm object.

Parameters:

Return:

Example:

window.s_widget_custom.submit = async function () {
  await s_widget.serverUpdate();
  const tableName = s_widget.getFieldValue('table_name');
  const recordId = s_widget.getFieldValue('record_id');

  const builtInForm = new SimpleForm(tableName, recordId);
  
  await builtInForm.save().then(s_form.save());
  s_modal.setShow(false);
  s_go.reloadWindow();
}

modalForm()

Use this object of the SimpleForm class to interact with the modal window of the opened record from the client script of the form. The form is available by using the <Form> tag in the modal window widget.

Access the object using s_form.modalForm.

Returns:

Example:

s_form.modalForm.setValue('state', '2')

Global variable usage

Within any record form, you can use predefined global variables.

window.currentFieldLabel.getColumnId()

s_form.addErrorMessage(message)

Use this method to display an error toast message in the lower right corner.

Parameter:

Return:

Example:

s_form.addErrorMessage('Please enter a valid email address using the following format: joe@example.com');

s_form.addInfoMessage(message, durationMilliseconds)

Use this method to display an informational toast message in the lower right corner. The message disappears after a certain period of time. In the durationMilliseconds parameter, specify this period in milliseconds.

Parameters:

Return:

Example:

s_form.addInfoMessage('Link copied to clipboard', 2000);

s_form.addSuccessMessage(message, durationMilliseconds)

Use this method to display a message about a successul action in the lower right corner. The message disappears after a certain period of time. Specify this period in milliseconds in the durationMilliseconds parameter.

Parameter(s):

Return:

Example:

s_form.addSuccessMessage('Record was successfully added!', 3000);

s_form.addWarningMessage(message, durationMilliseconds)

Use this method to display a warning message in the lower right corner. The message disappears after a certain period of time. Specify this period in milliseconds in the durationMilliseconds parameter.

Parameters:

Return:

Example:

s_form.addWarningMessage('This record has been modified by another user', 3000);

s_form.addOption(fieldName, choiceValue)

Use this method to add a choice option to the end of the choice field. A user can add a choiceValue values defined for fieldName into the current set of the table options.

Parameters:

Return:

Example:

const choices = ['10', '20', '30'];
s_form.clearOptions('contact_type');
for (const optionValue of choices) {
    await s_form.addOption('contact_type', optionValue);
}

s_form.clearMessages()

Use this method to close all kinds of messages (both informational and error) in the form.

Return:

Example:

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

s_form.clearOptions(fieldName)

Use this method to remove all options from the choice list.

Parameter:

Return:

Example:

const choices = ['10', '20', '30'];
s_form.clearOptions('contact_type');
for (const optionValue of choices) {
    await s_form.addOption('contact_type', optionValue);
}

s_form.clearValue(fieldName) 

Use this method to clear out any field, that is delete its value.

Parameter(s):

Return:

Example:

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

s_form.isFieldChanged(fieldName)

Use this method to verify whether the specified field has been changed.

Parameter(s):

Return:

Example:

if (s_form.isFieldChanged('state') && s_form.getValue('state') != 'new') {
  return false; // abort form submit
}

s_form.formId

Use this class property to return the current form ID. The form view ID is an ID of the record in the UI Forms (sys_ui_form) table.

Return:

Example:

const url = new URL(`${API_BASE_URL}/export/excel`);
if (typeof s_form !== "undefined") {
  url.searchParams.set('form_id', s_form.formId);
}
window.open(url, "_blank");

s_form.getAllFields()

Use this method to get a list of fields with their values placed on the form.

The return value contains two keys:

• the data key is an object, where the keys are the system field names, and the values are the values of those fields.
• the error key is an array with error messages if the form is saved in the current state.

Parameter:

Return:

Example:

if (!s_form.getAllFields(true).data.hasOwnProperty('state')) return;

s_form.getChanges()

Use this method to retrieve information about the changed fields: field name, previous value, current value.

Return:

if (s_form.isChanged()) {
  const changedFields = s_form.getChanges();
  let payload = {};
  changedFields.forEach((field) => {
    payload[field.fieldName] = field.currentValue;
  });
  SimpleStorage.setItem('payload', payload);
}

s_form.getLabelOf(fieldName)

Use this method to return a label text value.

Parameter(s):

Return:

Example:

const FIELD_LABEL = s_form.getLabelOf('username');
s_form.addErrorMessage(`Field "${FIELD_LABEL}" contains invalid characters.`);

s_form.getREMDisplayValue(fieldName)

Use this method to get a displayable REM attribute value.

Find the values represented in the client scripts according to the field types in the table.

Parameter:

Return:

Example:

s_form.addErrorMessage(`Service "${s_form.getREMDisplayValue('service')}" is not available`);

s_form.getREMLabelOf(fieldName)

Use this method to get a label text value of a REM attribute.

Parameter(s):

Return:

Example:

const FIELD_LABEL = s_form.getREMLabelOf('phone');
s_form.addErrorMessage(`Field "${FIELD_LABEL}" contains invalid characters.`);

s_form.getREMValue(fieldName)

Use this method to get a REM attribute value.

Find the values represented in the client scripts according to the field types in the table.

Parameter:

Return:

Example:

if (s_form.getREMValue('model')) {
  s_form.hideFieldMsg('model');
}

s_form.getSections()

Use this method to get an array of sections.

Return:

Example:

const sectionNames = s_form.getSections().map(section => section.name);
if (sectionNames.length) {
    s_form.addInfoMessage(`You can move between ${sectionNames.join(', ')}` sections);
}

s_form.getSectionNames()

Use this method return an array that contains the names of all sections, visible and hidden.

Return:

Example:

const sectionNames = s_form.getSectionNames()
if (sectionNames.length) {
    s_form.addInfoMessage(`You can move between ${sectionNames.join(', ')}` sections);
}

s_form.getTableName()

Use this method to return a table name that the specified record relates to.

Return:

Example:

const TABLE_NAME = s_form.getTableName();
console.log(TABLE_NAME);

s_form.getUniqueValue()

Use this method to return a unique record ID.

Return:

Example:

const TABLE_NAME = s_form.getTableName();
const RECORD_ID = s_form.getUniqueValue();
const currentRecord = new SimpleRecord(TABLE_NAME);
currentRecord.get(RECORD_ID, ()=> {
  if (currentRecord.sys_id === RECORD_ID) {
    s_form.addInfoMessage(currentRecord.sys_created_at);
  }
});

s_form.getValue(fieldName)

Use this method to return the database value of the specified field .

Find the values represented in the client scripts according to the field types in the table.

Parameter:

Return:

Example:

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)

Use this method to return the displayed value of the field.

Find the values represented in the client scripts according to the field types in the table.

Parameter(s):

Return:

Example:

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

s_form.goBack()

Use this method to perform a redirection to the previous page. If it is not possible, the redirection leads to the list view of the current instance, for example, to a list of incidents from an incident record.

Return:

Example:

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

s_form.isChanged()

Use this method to get information whether a record form has been changed.

Return:

Example:

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

s_form.hideFieldMsg(fieldName)

Use this method to hide informational or error messages in the specified form field.

Parameter(s):

Return:

Example:

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

s_form.hideRelatedLists()

Use this method to hide all related lists on the form.

Return:

Example:

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

s_form.isMandatory(fieldName)

Use this method to check if the specified field is mandatory.

Parameter:

Return:

Example:

if (s_form.isMandatory('state') && !s_form.getValue('state')) {
  s_form.addInfoMessage('State cannot be None');
}

s_form.hideRelatedList(relListTitle)

Use this method to specify a related list you need to hide.

Parameter:

Return:

Example:

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

s_form.isNewRecord()

Use this method to find out if the record is new.

Return:

Example:

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

s_form.isReadonly(fieldName)

Use this method to verify whether a user can edit the specified field via the interface or the field is read-only.

Parameter:

Return:

Example:

if (!s_form.isReadonly('state')) {
  await s_form.setValue('state', 'new');
}

s_form.isSectionVisible(sectionName)

Use this method to define if a specified section is visible or not.

Parameter:

Return:

Example:

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

s_form.isValid()

Use this method to check if the specified form is valid or not.

Return:

Example:

if (!s_form.isValid()) {
  s_form.addErrorMessage('This form is invalid');
}

s_form.isVisible(fieldName)

Use this method to check if the specified field is visible or not.

Parameter:

Return:

Example:

if (s_form.isVisible('state')) {
  s_form.setSectionDisplay('Controls', true);
}

s_form.refreshUiActions()

Use this method to reload all UI actions on the form and reverifies conditions to display a button that are defined for these UI actions without refreshing the page.

Return:

Example:

const stateValue = s_form.getValue('state');
if (stateValue == 'in-progress') {
    s_form.refreshUiActions();
}

s_form.removeOption(fieldName, choiceValue)

Use this method to specify and delete an option from the choice list.

Parameters:

Return:

Example:

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

Use this method to save a record without leaving its form.

Return:

Example:

const sysId = await s_form.save().finally(__resolveServerResponse);
await s_user.setPreference(preferenceApplicationName, packApplicationId);
await s_user.setPreference(preferenceLocalPackName, sysId);
await s_pref.refresh();

s_form.setLabelOf(fieldName, value)

Use this method to set a text value of the field label.

Parameter(s):

Return:

Example:

if (s_form.getTableName() == "employee") {  
  s_form.setLabelOf("email", "Personal Email");
  s_form.setLabelOf("manager.email", "Manager's Email");
} else {
  s_form.setLabelOf("email", "Email");
}

s_form.setMandatory(fieldName, mandatory)

Use this method to change a specified field to a mandatory field, that is it cannot be null.

Parameter(s):

Return:

Example:

const scriptType = s_form.getValue('type');
const mandatoryColumn = ['onChange', 'onCellEdit'].includes(scriptType);
s_form.setVisible('column_id', mandatoryColumn);
s_form.setMandatory('column_id', mandatoryColumn);

s_form.setReadOnly(fieldName, readOnly)

Use this method to change a specified field to read-only or editable.

Parameter(s):

Return:

Example:

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

s_form.setREMLabelOf(fieldName, value)

Use this method to set a plain text value of a REM attribute label.

Parameter(s):

Return:

Example:

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

s_form.setREMMandatory(fieldName, mandatory)

Use this method to make a field specified by a REM attribute mandatory.

Parameters:

Return:

Example:

const isDeliveryFilled = !!s_form.getValue('delivery');
s_form.setREMMandatory('phone', isDeliveryFilled);

s_form.setREMReadOnly(fieldName, readOnly)

Use this method to make a field specified by a REM attribute read-only.

Parameter(s):

Return:

Example:

if (s_form.isNewRecord()) {
  s_form.setREMValue('state', 'new');
  s_form.setREMReadOnly('state', true);
}

s_form.setREMValue(fieldName, databaseValue)

Use this method to set a value of the REM attribute label.

Parameters:

Return:

Example:

await s_form.setREMValue('state', 'new');
s_form.save();

s_form.setREMVisible(fieldName, display)

Use this method to define visibility of the field specified by a REM attribute.

Parameters:

Return:

Example:

s_form.setREMVisible('additional_info', !s_form.isNewRecord());

s_form.setSectionDisplay(sectionName, display)

Use this method to specify the section you need to display.

Parameter(s):

Return:

Example:

if (s_form.getValue('state') == '7') { // Completed
  s_form.setSectionDisplay('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.setValue(fieldName, databaseValue)

Use this method to set a field value. 

Parameters:

Return:

Example:

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)

Use this method to manage the display of the fields that have been added to the form through the Form Layout. You can hide or show the fields. The hidden field state is similar to being removed from the form view.

Parameters:

Return:

Example:

if (!s_form.isNewRecord()) {
  s_form.setVisible('subject', true);
  s_form.setVisible('reason', false);
}

s_form.showFieldMsg(fieldName, message, type) 

Use this method to display informantional and warning messages, and messages containing error description under the specified form field. 

Parameters:

Return:

Example:

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

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

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

s_form.showRelatedLists()

Use this method to display all the lists related to the form.

Return:

Example:

s_form.showRelatedLists();

s_form.showRelatedList(listTitle)

Use this method to display a specified list related to the form.

Parameter:

Return:

Example:

s_form.showRelatedList('UI Action');

s_form.submit()

Use this method to submit a record form.

Return:

Example:

s_form.submit();

Deprecated methods

s_form.fieldHasChanges(fieldName)

This method checks whether the specified field has been changed.

Parameter:

Return:

Example:

console.log(s_form.fieldHasChanges('state'));

s_form.hasChanges()

This method gets t information whether a record form has been changed or not.

Return:

Example:

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