SimpleForm
Данный класс включает в себя методы, позволяющие настраивать формы. Они могут использоваться исключительно на стороне клиента.
Помимо этого, нижеперечисленные методы можно использовать для настройки зависимостей между полями и значениями. Например, для изменения или удаления значений полей.
SimpleForm(table, sys_id)
Используйте этот конструктор для создания экземпляра объекта SimpleForm.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
table | String | Да | Нет |
sys_id | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Object | Метод возвращает объект формы. |
Пример:
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.
Возвращаемое значение:
Тип | Описание |
---|---|
Object | Метод возвращает объект формы. |
Пример:
s_form.modalForm.setValue('state', '2')
Использование глобальных переменных
Внутри каждой формы записи можно использовать преднастроенные глобальные переменные.
Переменная | Описание |
---|---|
currentFieldLabel | Определяет связь поля с объектом его обертки. Эта переменная используется с методом getColumnId(), как в примере: window.currentFieldLabel.getColumnId() Например, при помощи этой переменной можно получить контекстное меню поля. |
currentUiAction | Эта переменная содержит объект с ID записи [UI-действия](/platform/developer-help/user-actions/UI actions). Используйте ее при вызове контекстного меню кнопки. |
s_form.addErrorMessage(message)
Используйте этот метод для отображения всплывающего окна с сообщением об ошибке в нижнем правом углу окна. Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
message | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
s_form.addErrorMessage('Пожалуйста, введите email в следующем формате: joe@example.com');
s_form.addInfoMessage(message, durationMilliseconds)
Используйте данный метод для отображения информационного сообщения, которое всплывает в нижнем правом углу окна. Сообщение исчезнет через некоторое время. В параметре durationMilliseconds можно задать это время в миллисекундах.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
message | String | Да | Нет |
durationMilliseconds | Number | Нет | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
s_form.addInfoMessage('Link copied to clipboard', 2000);
s_form.addSuccessMessage(message, durationMilliseconds)
Используйте метод, чтобы отобразить сообщение об успешном действии в нижнем правом углу окна. Сообщение исчезнет через некоторое время. В параметре durationMilliseconds можно задать это время в миллисекундах.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
message | String | Да | Нет |
durationMilliseconds | Number | Нет | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
s_form.addSuccessMessage('Запись успешно добавлена!', 3000);
s_form.addWarningMessage(message, durationMilliseconds)
Используйте метод, чтобы отобразить сообщение с предупрежде нием в правом нижнем углу. Сообщение исчезнет через некоторое время. В параметре durationMilliseconds можно задать это время в миллисекундах.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
message | String | Да | Нет |
durationMilliseconds | Number | Нет | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
s_form.addWarningMessage('Эта запись изменена другим пользователем', 3000);
s_form.addOption(fieldName, choiceValue)
Используйте данный метод для добавления опции выбора в конец списка поля типа Choice. Пользователь может добавить значения choiceValue, определенные для колонки fieldName в текущем наборе опций таблицы.
Это асинхронный метод. Для оптимальной работы системы используйте ключевое слово await, как показано в примере ниже.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
choiceValue | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Object | Метод возвращает объект Promise object. |
Пример:
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()
Используйте этот метод для того, чтобы закрывать все виды сообщений (информационные и об ошибке) на форме.
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
s_i18n.getMessage('Дата и время завершения не могут быть раньше даты и времени начала', (response) => {
s_form.clearMessages();
s_form.addErrorMessage(response);
});
s_form.clearOptions(fieldName)
Используйте данный метод для удаления всех опций из списка с выбором поля типа Choice.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
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)
Используйте данный метод для удаления значения любого поля.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Boolean | Метод возвращает false, если очистить поле не получилось, в следующих случаях:
|
Пример:
if (!s_form.getValue('sprint')) {
s_form.clearValue('points');
}
s_form.isFieldChanged(fieldName)
Используйте этот метод, чтобы проверить, изменилось ли значение указанного поля.
Если клиентский скрипт меняет значение в поле на форме, метод вернет значение true. Изменения могут быть инициированы как скриптом, так и пользователем.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Boolean | Метод возвращает true, если значение в указанном поле было изменено; в противном случае, метод возвращает false. |
Пример:
if (s_form.isFieldChanged('state') && s_form.getValue('state') != 'new') {
return false; // отмена отправки формы
}
s_form.formId
Используйте это свойство класса, чтобы вернуть ID текущей формы. ID формы – это ID записи в таблице Формы (sys_ui_form).
Возвращаемое значение:
Тип | Описание |
---|---|
String | Метод возвращает 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 – массив с сообщениями об ошибках в случае сохранения формы в текущем состоянии.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
isAll | Boolean | Нет | false |
Возвращаемое значение:
Тип | Описание |
---|---|
Object | При значении isAll false, метод возвращает информацию о полях, значения которых были изменены. При значении true возвращается информация обо всех вынесенных на форму полях, из всех секций, в том числе о скрытых клиентскими скриптами. На форме новой записи, при любом значении isAll, метод возвращает перечень всех полей формы. |
Пример:
if (!s_form.getAllFields(true).data.hasOwnProperty('state')) return;
s_form.getChanges()
Используйте данный метод для получения информации об измененных полях: название поля, предыдущее значение, текущее значение.
Если выполненный на форме клиентский скрипт менял значения полей, то метод getChanges() вернет массив с информацией обо всех измененных полях. Изменения могут быть инициированы как скриптом, так и пользователем.
Возвращаемое значение:
Тип | Описание |
---|---|
Array of Objects | Метод возвращает массив объектов, содержащих название поля, его предыдущее и текущее значения. |
Пример:
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)
Используйте метод, чтобы вернуть отображаемое название поля на форме.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
String | Метод возвращает строку, содержащую отображаемое название поля. |
Пример:
const FIELD_LABEL = s_form.getLabelOf('username');
s_form.addErrorMessage(`Поле "${FIELD_LABEL}" содержит недопустимые символы.`);
s_form.getREMDisplayValue(fieldName)
Используйте метод, чтобы вернуть отображаемое значение REM атрибута.
Ознакомиться с примерами по типам колонок вы можете в статье Использование типов колонок в клиентских и серверных скриптах.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
String | Метод возвращает отображаемое значение атрибута. |
Пример:
s_form.addErrorMessage(`Сервис "${s_form.getREMDisplayValue('service')}" недоступен.`);
s_form.getREMLabelOf(fieldName)
Используйте метод, чтобы вернуть текстовое значение заголовка REM атрибута.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
String | Метод возвращает значение заголовка атрибута. |
Пример:
const FIELD_LABEL = s_form.getREMLabelOf('phone');
s_form.addErrorMessage(`Поле "${FIELD_LABEL}" содержит недопустимые символы.`);
s_form.getREMValue(fieldName)
Используйте метод, чтобы вернуть значение REM атрибута.
Ознакомиться с примерами по типам колонок вы можете в статье Использование типов колонок в клиентских и серверных скриптах.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
String | Метод возвращает значение указанного поля из базы данных. |
Пример:
if (s_form.getREMValue('model')) {
s_form.hideFieldMsg('model');
}
s_form.getSections()
Используйте этот метод, чтобы получить массив секций.
Возвращаемое значение:
Тип | Описание |
---|---|
Array of HTML elements | Метод возвращает массив, содержащий секции формы. |
Пример:
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()
Используйте этот метод для получения массива, содержащего названия всех видимых и скрытых секций.
Возвращаемое значение:
Тип | Описание |
---|---|
Array of String | Метод возвращает массив, содержащий названия секций. |
Пример:
const sectionNames = s_form.getSectionNames();
if (sectionNames.length) {
s_form.addInfoMessage(`Вы можете перемещаться между секциями ${sectionNames.join(', ')}`);
}
s_form.getTableName()
Используйте метод, чтобы вернуть название таблицы, к которой относится указанная запись.
Метод возвращает системное название таблицы, а не ее заголовок. Пример:
- Системное название таблицы – itsm_incident
- Заголовок таблицы – Инциденты
Возвращаемое значение:
Тип | Описание |
---|---|
String | Метод возвращает системное название таблицы. |
Пример:
const TABLE_NAME = s_form.getTableName();
console.log(TABLE_NAME);
s_form.getUniqueValue()
Используйте метод, чтобы вернуть уникальный ID записи.
Возвращаемое значение:
Тип | Описание |
---|---|
String | Метод возвращает ID записи; в противном случае, он возвращает значение null. |
Пример:
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)
Используйте метод, чтобы вернуть значение указанного поля из базы данных.
Ознакомиться с примерами по типам колонок вы можете в статье Использование типов колонок в клиентских и серверных скриптах.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
feldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
String | Метод возвращает значение указанного поля из базы данных. |
Пример:
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)
Используйте метод, чтобы вернуть отображаемое значение поля.
Ознакомиться с примерами по типам колонок вы можете в статье Использование типов колонок в клиентских и серверных скриптах.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
String | Метод возвращает отображаемое значение указанного поля. |
Пример:
s_form.addInfoMessage(`Сервис "${s_form.getDisplayValue('service')}" недоступен`);
s_form.goBack()
Используйте этот метод для перенаправления пользователя на предыдущую страницу. Если это невозможно, пользователь будет перенаправлен на представление записей текущей таблицы в виде списка, например, со страницы записи инцидента на страницу списка инцидентов.
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
if (s_form.isChanged()) {
s_form.save().then(() => s_form.goBack());
} else {
s_form.goBack();
}
s_form.isChanged()
Используйте этот метод, чтобы узнать, была ли запись изменена.
Возвращаемое значение:
Тип | Описание |
---|---|
Boolean | Метод возвращает значение true, если менялись значения каких-либо полей на форме записи; если изменений не было, метод возвращает значение false. |
Пример:
if (s_form.isChanged()) {
s_form.save().then(() => s_form.goBack());
} else {
s_form.goBack();
}
s_form.hideFieldMsg(fieldName)
Используйте метод, чтобы скрыть информационные сообщения или сообщения об ошибке под указанным полем формы.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
if (s_form.getValue('state')) {
s_form.hideFieldMsg('state');
}
s_form.hideRelatedLists()
Используйте этот метод, чтобы скрыть все связанные списки на форме.
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
if (s_form.getValue('type') == 'internal') {
s_form.hideRelatedLists();
}
s_form.isMandatory(fieldName)
Используйте этот метод, чтобы проверить является ли указанное поле обязательным.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Boolean | Метод возвращает значение true, если поле является обязательным, если нет – метод возвращает значение false. |
Пример:
if (s_form.isMandatory('state') && !s_form.getValue('state')) {
s_form.addInfoMessage('Укажите статус');
}
s_form.hideRelatedList(relListTitle)
Используйте этот метод, чтобы указать связанный список, который необходимо скрыть.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
relListTitle | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
if (s_form.getValue('type') == 'external') {
s_form.hideRelatedList('Customer');
}
s_form.isNewRecord()
Используйте этот метод, чтобы проверить является ли текущая запись новой.
Возвращаемое значение:
Тип | Описание |
---|---|
Boolean | Метод возвращает true на форме еще не созданной записи. В противном случае, метод возвращает значение false. |
Пример:
if (s_form.isNewRecord()) {
await s_form.setValue('state', 'new');
s_form.setReadOnly('state', true);
}
s_form.isReadonly(fieldName)
Используйте этот метод, чтобы узнать, доступно ли поле для редактирования через интерфейс или оно доступно пользователям только для чтения.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
feldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Boolean | Метод возвращает значение true, если поле доступно только для чтения, в противном случае, метод возвращает значение false. |
Пример:
if (!s_form.isReadonly('state')) {
await s_form.setValue('state', 'new');
}
s_form.isSectionVisible(sectionName)
Используйте метод, чтобы определить, является ли указанная секция видимой.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
sectionName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Boolean | Метод возвращает значение true, если секция видна; если скрыта – false. |
Пример:
if (s_form.isSectionVisible('Instructions')) {
s_form.addInfoMessage('Check out the "Instructions" section', 5000);
}
s_form.isValid()
Используйте метод, чтобы определить, является ли указанная форма действительной.
Возвращаемое значение:
Тип | Описание |
---|---|
Boolean | Метод возвращает значение true, если форма действительна, если нет – метод возвращает значение false. |
Используйте этот метод, только если форма содержит поля типов Даты и времени, так как данный метод не поддерживает проверку полей других типов.
Пример:
if (!s_form.isValid()) {
s_form.addErrorMessage('Эта форма недействительна');
}
s_form.isVisible(fieldName)
Используйте этот метод чтобы узнать, является ли указанное поле видимым.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Boolean | Метод возвращает значение true, если поле видимое, если нет, метод возвращает false. |
Пример:
if (s_form.isVisible('state')) {
s_form.setSectionDisplay('Controls', true);
}
s_form.refreshUiActions()
Используйте этот метод для перезагрузки всех UI-действий на форме и повторной проверки условий отображения кнопки, которые определены для этих UI-действий, без обновления страницы.
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
const stateValue = s_form.getValue('state');
if (stateValue == 'in-progress') {
s_form.refreshUiActions();
}
s_form.removeOption(fieldName, choiceValue)
Используйте этот метод, чтобы удалить определенную опцию из списка c выбором.
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
choiceValue | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
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()
Используйте данный метод для сохранения записи, не покидая ее формы.
Возвращаемое значение:
Тип | Описание |
---|---|
String | Метод возвращает ID сохраненной записи. |
Пример:
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)
Используйте данный метод для того, чтобы установить текстовое значение для заголовка поля.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
value | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
Void | Метод не возвращает значение. |
Пример:
if (s_form.getTableName() == "employee") {
s_form.setLabelOf("email", "Личная электронная почта");
s_form.setLabelOf("manager.email", "Электронная почта менеджера");
} else {
s_form.setLabelOf("email", "Электронная почта");
}
s_form.setMandatory(fieldName, mandatory)
Используйте этот метод для того, чтобы сделать указанное поле обязательным.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
mandatory | Boolean | Нет | true |
Возвращаемое значение:
Тип | Описание |
---|---|
Boolean | При успешном выполнении метод возвращает значение true. Значение false возвращается при следующих условиях:
|
Пример:
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)
Используйте этот метод, чтобы изменить настройки поля и сделать его редактируемым или доступным только для чтения.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
readOnly | Boolean | Нет | true |
Возвращаемое значение:
Тип | Описание |
---|---|
Boolean | При успешном выполнении метод возвращает значение true. Значение false возвращается при следующих условиях:
|
Пример:
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 атрибуту.
Параметры:
Наименование | Тип | Обязательно | Значение по умолчанию |
---|---|---|---|
fieldName | String | Да | Нет |
value | String | Да | Нет |
Возвращаемое значение:
Тип | Описание |
---|---|
String | Метод возвращает присвоенное значение. |
Пример:
if (s_form.getTableName() == 'user') {
s_form.setREMLabelOf('email', 'Электронная почта');
} else {
s_form.setREMLabelOf('email', 'Личная электронная почта');
}