Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
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).
s_formSimpleForm(table, sys_id)
Instantiates a new SimpleForm object.
Name | Type | Mandatory | Default Value |
---|---|---|---|
table | String | Y | N |
sys_id | String | Y | N |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
const formObject = new SimpleForm(s_form.table, s_form.sysId); |
Return:
Type | Description |
---|---|
Object | This method returns a form object. |
s_form.addErrorMessage(message)
This method displays the error message at the top of the formtoast message in the bottom right corner.
Parameter(s):
Name | Type | Mandatory | Default Value |
---|---|---|---|
Messagemessage | String | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
s_form.addErrorMessage('Need more information'); |
s_form.addInfoMessage(message,
durationdurationMilliseconds)
This method adds an displays an informational toast message to the top of the formin the bottom right corner. The message is expirable, its expire period (in milliseconds) should be specified by $duration second parameter.
Parameter(s):
Name | Type | Mandatory | Default Value |
---|---|---|---|
message | String | Y | N |
durationdurationMilliseconds | Number | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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).
Note |
---|
Please note that this method is asynchronous; for better performing, use the await keyword like shown in the code example below. |
Parameter(s):
Name | Type | Mandatory | Default Value |
---|---|---|---|
fieldName | String | Y | N |
choiceValue | String | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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:
Type | Description |
---|---|
Void | This method does not return a value. |
s_form.clearOptions(fieldName)
This method allows removing all options from the choice list.
Parameter(s):
Code Block |
---|
Return:
Example:
Code Block | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
s_i18n.getMessage('End date time cannot be less than start date time', (response) => { s_form.clearOptionsclearMessages('contact_type'); s_form. |
addErrorMessage( |
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):
Return:
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
s_form.getValue('sprint') === null ? s_form.clearValue('points') : false; |
s_form.getComponent(fieldName)
This method returns the form field by its name.
Parameter(s):
Return:
response);
return false; // abort form submit
}); |
s_form.clearOptions(fieldName)
This method allows removing all options from the choice list.
Parameter(s):
Name | Type | Mandatory | Default Value |
---|---|---|---|
fieldName | String | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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.
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
const component = s_form.getComponent('name'); |
s_form.getLabelOf(fieldName)
This method returns the text value of the field label.
Parameter(s):
Name | Type | Mandatory | Default Value |
---|---|---|---|
fieldName | String | Y | N |
Return:
Type | Description |
---|
Boolean | This method returns the boolean value (TRUE or FALSE) in the cases described above. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
if (!s_form.getLabelOfgetValue('assigned_usersprint')) { s_form.clearValue('points'); } |
s_form.
getSectionsgetLabelOf(fieldName)
This method allows returning returns the array text value of the sectionsfield label.
ReturnParameter(s):
Name | Type | Mandatory |
---|
s_form.getSectionNames()
This method allows returning the array which will contain the names of all sections, whether visible or not.Default Value | |||
---|---|---|---|
fieldName | String | Y | N |
Return:
Type | Description |
---|
String | The text |
of the |
s_form.getUniqueValue()
Returns the unique ID (sys_id) of the record displayed on the form.
Return:
label. |
Example:
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
const sysId = s_form.getUniqueValue(); | ||||||||
if (s_form.getValue( |
Returns the internal (written down to the database) value of the specified field.
Warning |
---|
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):
'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:
Type | Description |
---|---|
Array of HTML elements | The form sections. |
s_form.getSectionNames()
This method allows returning the array which will contain the names of all sections, whether visible or not.
Return:
Type | Description |
---|
This method returns the field values in a various types:
- It returns the database value (that may differ from the displayed value) for the fields of Reference, List, Document ID.
- And for the other field types, like the String, or Duration, or Big Integer, the method just returns the field value.
Example:
Array of strings | Names of the sections |
Code Block | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
Code Block | |||||||||
| |||||||||
if (!!s_form.getValue('caller_id');getSectionNames().includes('Instructions')) { s_form.addInfoMessage('Check out the "Instructions" section', 5000); } |
s_form.
getDisplayValuegetUniqueValue(
fieldName)
This method returns the displayed value of the field.
Parameter(s):
Returns the unique ID (sys_id) of the record displayed on the form.
Return:
Type | Description |
---|---|
String | Returns the record ID; otherwise, returns NULL |
Return:
. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
const sysId = s_form.getDisplayValuegetUniqueValue('incident.description'); const currentRecord = new SimpleRecord(s_form. |
This method, as opposed to the s_form.showFieldMsg() method, allows to hide informational or error messages on the specified form field
Parameter(s):
Return:
Example:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
s_form.hideFieldMsg('state'); |
s_form.hideRelatedLists()
This method allows hiding all related lists on the form.
Return:
s_form.hideRelatedList(relListTitle)
This method allows hiding the specified related list on the formtable);
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.
Warning |
---|
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):
Name | Type | Mandatory | Default Value |
---|---|---|---|
relListTitlefieldName | String | Y | N |
Return:
Type | Description |
---|
String | This method |
returns the internal (written down to the database) value of the specified field. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
const callerId = s_form.hideRelatedList('Note'); |
s_form.isNewRecord()
If the record was never saved then this method returns TRUE; otherwise, it returns FALSE.
Return:
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):
Name | Type | Mandatory | Default value |
---|---|---|---|
fieldName | String |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
s_form.isNewRecord() ? alert('New record') : alert('Not new record'); |
s_form.isSectionVisible(sectionName)
This method returns TRUE if the section is visible; otherwise, it returns FALSE.
Parameter(s):
Y | N |
Return:
Type | Description |
---|
String | The displayed value of the specified field. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
s_form.isSectionVisible('Notes') ? alert('Visible') : alert('Not visible')'addInfoMessage(`Service "${s_form.getDisplayValue('service')}" is no available`); |
s_form.
removeOptionhideFieldMsg(
fieldName, choiceValueinput)
This method removes the selected option from the list., as opposed to the s_form.showFieldMsg() method, allows to hide informational or error messages on the specified form field
Parameter(s):
Name | Type | Mandatory | Default Value |
---|
input | String | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
if (!!s_form.getValue('state')) {
s_form.hideFieldMsg('state');
} |
s_form.hideRelatedLists()
This method allows hiding all related lists on the form.
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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):
Name | Type | Mandatory | Default Value |
---|---|---|---|
relListTitle | String | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
if (s_form.getValue('type') == 'external') {
s_form.hideRelatedList('Customer');
} |
s_form.isNewRecord()
If the record was never saved then this method returns TRUE; otherwise, it returns FALSE.
Return:
Type | Description |
---|---|
Boolean | If the record was never saved then this method returns TRUE; otherwise, it returns FALSE. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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):
Name | Type | Mandatory | Default Value |
---|---|---|---|
sectionName | string | Y | N |
Return:
Type | Description |
---|---|
Boolean | This method returns TRUE if the section is visible; otherwise, it returns FALSE. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
s_form.isSectionVisible('Notes') ? alert('Visible') : alert('Not visible')' |
s_form.removeOption(fieldName, choiceValue)
This method removes the selected option from the list.
Parameter(s):
Name | Type | Mandatory | Default Value |
---|---|---|---|
fieldName | String | Y | N |
choiceValue | String | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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('priorityimpact' , 'low'); s_form. |
This method saves the record without going away (just updating).
Return:
removeOption('urgency', 'low');
}
});
} |
s_form.
setLabelOfsave(
fieldName, value)
This method sets the text value of the field label.
Parameter(s):
saves the record without going away (just updating).
Return:
Type | Description |
---|
Object | This method |
returns a promise containing specific data. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
s_form.save().setLabelOffinally('assigned_user', 'Assigned User'__resolveServerResponse); |
s_form.
setSectionMandatorysetLabelOf(
sectionNamefieldName,
mandatoryvalue)
This method allows making the specified section mandatory. Use UI policy instead of this method if possiblesets the text value of the field label.
Parameter(s):
Name | Type | Mandatory | Default Value |
---|
fieldName | String | Y | N |
value |
String | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
if (s_form.table == 'user') { s_form.isNewRecord() ?setLabelOf('email', 'Email'); } else { s_form.setSectionMandatorysetLabelOf('Defaultemail', ,'Personal trueEmail') :; } |
s_form.setSectionMandatory
s_form.setMandatory(fieldName(sectionName, mandatory)
This method allows making the specified field mandatorysection mandatory. Use UI policy instead of this method if possible.
Parameter(s):
Name | Type | Mandatory | Default Value |
---|---|---|---|
fieldNamesectionName | String | Y | N |
mandatory | Boolean | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value |
Example:
Code Block | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||
if (s_form.getValue('state') == '7') { // Completed s_form.setSectionDisplay('Closure Information', true); s_form.isNewRecord() ?setSectionMandatory('Closure Information', true); s_form.setMandatory('subjectclosure_code' , true); : s_form.setMandatory('subjectclosure_notes' , falsetrue); } |
s_form.
setReadOnlysetMandatory(fieldName,
readOnlymandatory)
This method allows making the specified field read-only or editable.Use field mandatory. 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):
Name | Type | Mandatory | Default Value |
---|---|---|---|
fieldName | String | Y | N |
mandatory | Boolean | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value |
Example:
Code Block | |||||||
---|---|---|---|---|---|---|---|
| |||||||
const mandatoryColumn = (scriptType == 'onChange' || scriptType == 'onCellEdit'); s_form.setReadOnlysetMandatory('priority' 'column_id', truemandatoryColumn); |
s_form.
setSectionDisplaysetReadOnly(
sectionNamefieldName,
displayreadOnly)
This method allows to show or hide a sectionmaking 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):
Name | Type | Mandatory | Default Value |
---|
fieldName | String | Y | N |
readOnly | Boolean | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
s_form.setSectionDisplay('Notes' , 'New Notes'); | ||||||||
| ||||||||
if (!!s_form. |
This method sets the field value.
Warning |
---|
IsDisplayValue parameter has been maintained in earlier versions but will be deprecated after version 1.1. Avoid using it in your scripts. To set a displayed value of a field, use the s_form.setDisplayValue method. |
When setting an empty value (either String type or Array (for the fields of the List type), the field value will be cleared like when using the s_form.clearValue() method.
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
Also please note that this method is asynchronous; for better performing, use the await keyword like shown in the code example below.
Parameter(s):
Name | Type | Mandatory | Default Value |
---|
sectionName | String | Y | N |
display |
Boolean | Y |
N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
awaitif (s_form.getValue('state') == '7') { // Completed s_form.setValuesetSectionDisplay('assigned_userClosure Information', true); s_user.userIDform.setSectionMandatory('Closure Information', true); const currentState = s_form.getValuesetMandatory('state'closure_code', true); if (s_form.getValuesetMandatory('state') != ‘0’)closure_notes', true); } else { await s_form.setValue(‘state’setMandatory('closure_code', ‘0’false); } s_form.save()setMandatory('closure_notes', false); .then(() => { if (currentState === s_form.setSectionDisplay('Closure Information', false); s_form.setSectionMandatory('Closure Information', false); } |
s_form.setValue(fieldName, value)
This method sets the field value.
Warning |
---|
IsDisplayValue parameter has been maintained in earlier versions but will be deprecated after version 1.1. Avoid using it in your scripts. |
Note |
---|
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):
Name | Type | Mandatory | Default Value |
---|---|---|---|
fieldName | String | Y | N |
value | String | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
if (!!s_form.isNewRecord()) { s_form.setValue('name', 'Name created by system'); }getValue('state')) { s_i18n.getMessage(`You can’t change the state`, (response) => { s_form.addInfoMessage(response) }); } else { s_i18n.getMessage(`You've been assigned to current incident`, (response) => { s_form.addInfoMessage(response); }); } }) |
s_form.setVisible(fieldName, display)
This method allows making a field visible or hidden.
If the fieid 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):
Name | Type | Mandatory | Default Value |
---|---|---|---|
fieldName | String | Y | N |
display | Boolean | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
s_form.isNewRecord() ? s_form.setVisible('chronology' , false) : !s_form.setVisible('chronology' , trueisNewRecord()); |
s_form.showFieldMsg(fieldName, message, type)
This method displays an informational message or an error message in a message under the specified form field. Possible type values - 'info', 'error', or 'warning'.
Parameter(s):
Name | Type | Mandatory | Default Value |
---|---|---|---|
fieldName | String | Y | N |
message | String | Y | N |
type | String | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
s_form.showFieldMsg('subject', 'Cannot be empty', 'info'); |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
s_form.showFieldMsg('subject', 'Cannot be empty', 'warning'); |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
s_form.showFieldMsg('subject', 'Cannot be empty', 'error'); |
s_form.showRelatedLists()
This method allows displaying all lists related to the form.
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
s_form.showRelatedList(
listTableNamelistTitle)
This method allows displaying the specified lists related to the form.
Parameter(s):
Name | Type | Mandatory | Default Value |
---|---|---|---|
listTableNamelistTitle | String | Y | N |
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Example:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
s_form.showRelatedList('UI Action'); |
s_form.submit()
This method saves submit the record with navigating away from the form.
Return:
Type | Description |
---|---|
Void | This method does not return a value. |
Table of Contents | ||
---|---|---|
|