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

modalForm()

Используйте этот объект класса SimpleForm, чтобы взаимодействовать с формой модального окна из клиентских скриптов формы открытой записи. Форма доступна при использовании тэга <form> в виджете модального окна.

Чтобы обратиться к объекту, используйте s_form.modalForm.

Возвращаемое значение:

Пример:

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

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

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

window.currentFieldLabel.getColumnId()

s_form.addErrorMessage(message)

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

Параметр:

Возвращаемое значение:

Пример:

s_form.addErrorMessage('Пожалуйста, введите email в следующем формате: joe@example.com');

s_form.addInfoMessage(message, durationMilliseconds)

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

Параметры:

Возвращаемое значение:

Пример:

s_form.addInfoMessage('Ссылка скопирована', 2000);

s_form.addSuccessMessage(message, durationMilliseconds)

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

Параметры:

Возвращаемое значение:

Пример:

s_form.addSuccessMessage('Запись успешно добавлена!', 3000);

s_form.addWarningMessage(message, durationMilliseconds)

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

Параметры:

Возвращаемое значение:

Пример:

s_form.addWarningMessage('Эта запись изменена другим пользователем', 3000);

s_form.addOption(fieldName, choiceValue)

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

Параметры:

Возвращаемое значение:

Пример:

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

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

Возвращаемое значение:

Пример:

s_i18n.getMessage('Дата и время завершения не могут быть раньше даты и времени начала', (response) => {
  s_form.clearMessages();
  s_form.addErrorMessage(response);
});

s_form.clearOptions(fieldName)

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

Параметр:

Возвращаемое значение:

Пример:

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) 

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

Параметр:

Возвращаемое значение:

Пример:

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; // отмена отправки формы
}

s_form.formId

Используйте это свойство класс, чтобы вернуть ID текущей формы. ID формы – это ID записи в таблице Формы (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.getAllFields()

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

Возвращаемое значение содержит два ключа:

• data – объектом, ключами которого являются системные названия полей, а значения – значения этих полей.
• error – массив с сообщениями об ошибках в случае сохранения формы в текущем состоянии.

Параметр:

Возвращаемое значение:

Пример:

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

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)

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

Параметр:

Возвращаемое значение:

Пример:

const FIELD_LABEL = s_form.getLabelOf('username');
s_form.addErrorMessage(`Поле "${FIELD_LABEL}" содержит недопустимые символы.`);

s_form.getREMDisplayValue(fieldName)

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

Параметр:

Возвращаемое значение:

Пример:

s_form.addErrorMessage(`Сервис "${s_form.getREMDisplayValue('service')}" недоступен.`);

s_form.getREMLabelOf(fieldName)

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

Параметр:

Возвращаемое значение:

Пример:

const FIELD_LABEL = s_form.getREMLabelOf('phone');
s_form.addErrorMessage(`Поле "${FIELD_LABEL}" содержит недопустимые символы.`);

s_form.getREMValue(fieldName)

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

Параметр:

Возвращаемое значение:

Пример:

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

s_form.getSections()

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

Возвращаемое значение:

Пример:

const sectionNames = s_form.getSections().map(section => section.name);
if (sectionNames.length) {
    s_form.addInfoMessage(`Вы можете перемещаться между секциями ${sectionNames.join(', ')}`);
}

s_form.getSectionNames()

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

Возвращаемое значение:

Пример:

const sectionNames = s_form.getSectionNames();
if (sectionNames.length) {
    s_form.addInfoMessage(`Вы можете перемещаться между секциями ${sectionNames.join(', ')}`);
}

s_form.getTableName()

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

Возвращаемое значение:

Пример:

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

s_form.getUniqueValue()

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

Возвращаемое значение:

Пример:

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)

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

Параметр:

Возвращаемое значение:

Пример:

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('Расписание пользователя не определено');
    }
  });
}

s_form.getDisplayValue(fieldName)

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

Ознакомиться с примерами по типам колонок вы можете в статье Использование типов колонок в клиентских и серверных скриптах.

Параметры:

Возвращаемое значение:

Пример:

s_form.addInfoMessage(`Сервис "${s_form.getDisplayValue('service')}" недоступен`);

s_form.goBack()

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

Возвращаемое значение:

Пример:

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

s_form.isChanged()

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

Возвращаемое значение:

Пример:

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

s_form.hideFieldMsg(fieldName)

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

Параметры:

Возвращаемое значение:

Пример:

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

s_form.hideRelatedLists()

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

Возвращаемое значение:

Пример:

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

s_form.isMandatory(fieldName)

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

Параметр:

Возвращаемое значение:

Пример:

if (s_form.isMandatory('state') && !s_form.getValue('state')) {
  s_form.addInfoMessage('Укажите статус');
}

s_form.hideRelatedList(relListTitle)

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

Параметр:

Возвращаемое значение:

Пример:

if (s_form.getValue('type') == 'external') {
  s_form.hideRelatedList('Клиенты');
}

s_form.isNewRecord()

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

Возвращаемое значение:

Пример:

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

s_form.isReadonly(fieldName)

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

Параметр:

Возвращаемое значение:

Пример:

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

s_form.isSectionVisible(sectionName)

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

Параметр:

Возвращаемое значение:

Пример:

if (s_form.isSectionVisible('Instructions')) {
  s_form.addInfoMessage('Проверьте секцию "Инструкции"', 5000);
}

s_form.isValid()

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

Возвращаемое значение:

Пример:

if (!s_form.isValid()) {
  s_form.addErrorMessage('Эта форма недействительна');
}

s_form.isVisible(fieldName)

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

Параметры:

Возвращаемое значение:

Пример:

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

s_form.refreshUiActions()

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

Возвращаемое значение:

Пример:

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

s_form.removeOption(fieldName, choiceValue)

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

Параметры:

Возвращаемое значение:

Пример:

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

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

Возвращаемое значение:

Пример:

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)

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

Параметры:

Возвращаемое значение:

Пример:

if (s_form.getTableName() == "employee") {  
  s_form.setLabelOf("email", "Личная электронная почта");
  s_form.setLabelOf("manager.email", "Электронная почта менеджера");
} else {
  s_form.setLabelOf("email", "Электронная почта");
}

s_form.setMandatory(fieldName, mandatory)

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

Параметры:

Возвращаемое значение:

Пример:

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)

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

Параметры:

Возвращаемое значение:

Пример:

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)

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

Параметры:

Возвращаемое значение:

Пример:

if (s_form.getTableName() == 'user') {
  s_form.setREMLabelOf('email', 'Электронная почта');
} else {
  s_form.setREMLabelOf('email', 'Личная электронная почта');
}

s_form.setREMMandatory(fieldName, mandatory)

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

Параметры:

Возвращаемое значение:

Пример:

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

s_form.setREMReadOnly(fieldName, readOnly)

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

Параметры:

Возвращаемое значение:

Пример:

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

s_form.setREMValue(fieldName, databaseValue)

При помощи этого метод можно установить значение самого атрибута REM.

Параметры:

Возвращаемое значение:

Пример:

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

s_form.setREMVisible(fieldName, display)

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

Параметры:

Возвращаемое значение:

Пример:

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

s_form.setSectionDisplay(sectionName, display)

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

Параметры:

Возвращаемое значение:

Пример:

if (s_form.getValue('state') == '7') { // Завершено
  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)

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

Параметры:

Возвращаемое значение:

Пример:

await s_form.setValue('state', '7'); // Завершено
await s_form.setValue('closure_notes', articleBodies.join('\n'));
await s_form.setValue('closure_code', '1'); // Решено на 1 уровне
s_form.save()
  .then(() => {
    s_i18n.getMessage(`Применено стандартное решение`, (e) => {
      s_form.addInfoMessage(e);
    })
  });

s_form.setVisible(fieldName, display)

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

Параметры:

Возвращаемое значение:

Пример:

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

s_form.showFieldMsg(fieldName, message, type)

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

Параметры:

Возвращаемое значение:

Пример:

s_form.showFieldMsg('subject', 'Не может быть пустым', 'info');

s_form.showFieldMsg('subject', 'Не может быть пустым', 'warning');

s_form.showFieldMsg('subject', 'Не может быть пустым', 'error');

s_form.showRelatedLists()

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

Возвращаемое значение:

Пример:

s_form.showRelatedLists();

s_form.showRelatedList(listTitle)

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

Параметр:

Возвращаемое значение:

Пример:

s_form.showRelatedList('UI-действия');

s_form.submit()

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

Возвращаемое значение:

Пример:

s_form.submit();

Устаревшие методы

s_form.fieldHasChanges(fieldName)

Параметр:

Возвращаемое значение:

Пример:

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

s_form.hasChanges()

Возвращаемое значение:

Пример:

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