SimpleForm

Данный класс включает в себя методы необходимые для настройки форм. Они могут использоваться исключительно на стороне клиента.

Помимо этого, нижеперечисленные методы можно использовать для настройки зависимостей между полями и значениями. Например, для изменения или удаления значений полей .

SimpleForm(table, sys_id)

Используйте этот метод для создания экземпляра объекта SimpleForm.

Параметры:

Возврат:

Пример:

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

Использование глобальных переменных

Внутри каждой формы записи можно использовать преднастроенные глобальные переменные.

window.currentFieldLabel.getColumnId()

s_form.addErrorMessage(message)

Используйте этот метод для отображения всплывающего окна с сообщением об ошибке в нижнем правом углу окна.

Параметр:

Возврат:

Пример:

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

s_form.addInfoMessage(message, durationMilliseconds)

Используйте данный метод для отображения информационного сообщения, которое всплывает в нижнем правом углу окна. Сообщение исчезнет через некоторое количество времени. Укажите это время  в милисекундах во втором параметре.

Параметры:

Возврат:

Пример:

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

s_form.addSuccessMessage(message, durationMilliseconds)

Этот метод отображает сообщение об успешном действии, которое всплывает в нижнем правом углу окна. Сообщение исчезнет через некоторое количество времени. Укажите это время  в милисекундах во втором параметре.

Параметры:

Возврат:

Приемр:

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

s_form.addWarningMessage(message, durationMilliseconds)

Данный метод отображает сообщение с предупреждением в правом нижнем углу окна. Сообщение исчезнет через некоторое количество времени. Укажите это время  в милисекундах во втором параметре.

Параметры:

Возврат:

Пример:

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

s_form.addOption(fieldName, choiceValue)

Используйте данный метод для добавления опции выбора в конец поля со списком выбора, если опция с переданной choiceValue определена для fieldName в текущем наборе опций таблицы.

Параметры:

Возврат:

Пример:

const states = ['-1', '0', '2', '5'];

s_form.clearOptions('state');
states.forEach(async (stateValue) => {
  await s_form.addOption('state', stateValue);
})

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

Используйте данный метод для удаления всех опций из списка с выбором.

Параметр:

Возврат:

Пример:

const choices = [
  "Phone",
  "Email",
  "Self-service"
];

s_form.clearOptions('contact_type');
choices.forEach(async (choiceValue) => {
  await s_form.addOption('contact_type', choiceValue);
});

s_form.clearValue(fieldName) 

Используйте данный метод для удаления значения любого поля.

Параметр:

Возврат:

Пример:

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

s_form.isFieldChanged(fieldName)

Используйте этот метод, чтобы проверить, изменилось ли указанное поле.

Параметр:

Возврат:

Пример:

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

s_form.formId

Этот класс свойств возвращает текущий ID текущего пользователя. Форма представления ID – это ID записи в словаре UI Forms (sys_ui_form).

Возврат:

Пример:

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

Используйте данный метод для получения информации об измененных полях: название поля, предыдущее значение, текущее значение.

Возврат:

Пример:

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)

The method returns 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)

This method gets a displayable REM attribute value.

Parameter(s):

Return:

Example:

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

s_form.getREMLabelOf(fieldName)

This method gets 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)

This method gets a REM attribute value.

Parameter(s):

Return:

Example:

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

s_form.getSections()

Use this method to get an array of sections.

Return:

s_form.getSectionNames()

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

Return:

s_form.getTableName()

This method returns a table name that the specified record relates to.

Return:

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

s_form.getUniqueValue()

This method returns a unique record ID (sys_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)

This method returns the database value of the specified field.

Parameter(s):

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)

This method returns the displayed value of the field.

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)

This method, unlike the s_form.showFieldMsg() method, hides 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(s):

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

Return:

Example:

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

s_form.isNewRecord()

If the record has never been saved, this method returns true; otherwise, it returns false.

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 check if the specified field is editable or read-only.

Parameter(s):

Return:

Example:

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

s_form.isSectionVisible(sectionName)

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

Parameter(s):

Return:

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

Return:

Example:

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

s_form.refreshUiActions()

This method reloads all UI actions on the form and recalculates the server condition defined for these UI actions without refreshing the page.

Return:

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 list.

Parameter(s):

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

This method saves 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)

This method sets 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, i.e., 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)

This message sets 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.

Parameter(s):

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)

With this method you can set a value of the REM attribute label.

Parameter(s):

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.

Parameter(s):

Return:

Example:

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

s_form.setSectionDisplay(sectionName, display)

Use this method to specify the section you want to hide.

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)

This method sets a field value. 

Parameter(s):

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 displaying 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.

Parameter(s):

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 a message containing 'info', 'error', or 'warning' value under the specified form field. 

Parameter(s):

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:

s_form.showRelatedList(listTitle)

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

Parameter(s):

Return:

Example:

s_form.showRelatedList('UI Action');

s_form.submit()

With this method you can submitting a record form.

Return:

Deprecated methods

s_form.fieldHasChanges(fieldName)

Use this method to check if the specified field has been changed or not.

Parameter(s):

Return:

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

s_form.hasChanges()

Use this method to get 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();
}