Widget Scripts

Create a widget

A widget includes four components that define its appearance and behavior:

1. Template specifies widget views and the way they are displayed with HTML and SimpleTags. It also allows end-users to input and to interact with data. 
2. Server script runs a JS script on the server-side and processes the data received from the client-side and passes it back. 
3. Client script runs a JS script on the client-side, so that it receives the data from the server-side, processes the data before rendering, then passes it to the widget template. Also, the client script passes the input data received to the server-side.
4. Demo data specifies widget options available for further customization and processing if needed.

To create a widget, complete the following steps:

1. Navigate to Portal Structure → Widgets.
2. Click New and fill in the fields.
3. Click Save or Save and exit to apply the changes.

Widget form fields 

<div></div> 

<div>
	<textarea></textarea>
	<button></button>
</div> 

<div>
	<textarea label="Name" model="data.name">
	</textarea>
	<button event-click="window.s_widget_custom.submit();">
		OK
	</button>
</div> 

// Not Recommended
document.querySelector(".article-body").innerHTML = s_widget.getFieldValue('body');
// Recommended
s_widget.addTemplate('body', s_widget.getFieldValue('body'));

{"value_1": "1"; "value_2": "abc"}

The following scheme illustrates how the data is passed between the server and client scripts using the global objects:

Widget example

The following example illustrates the components of the widget that display the fields:

• Incident – a reference field that allows selecting an item from the Incident (itsm_incident) table.
• Description – a text field with a description of the selected Incident (itsm_incident). The field is empty by default.
• The Get button – fills in the Description field with the description of the related incident.
• The Send button – overwrites the selected incident description in the database with the value specified in the Description field.
• The Go button – opens the selected incident item on the current page.

Server controller

The server controller uses the data.incident variable to access the input.incident variable data received from the client controller. Depending on the input.operation_code variable value received, the server controller runs the query to the database to:

1. Get the incident description within the getIncidentDescription(incident_id) function.
2. Update it within the sendIncidentDescription(sys_id, description) function.
3. Get a redirect URL within the createUrlFromIncidentNumber(sys_id) function.

;(function() {
    const OPERATION_GET_DESCRIPTION = 1;
    const OPERATION_SAVE_DESCRIPTION = 2;
    const OPERATION_GO_TO_INCIDENT = 3;    
	data.incident = input.incident;    
	if (!input.operation_code) {
        getTableId(options.table);
        return;
    }    
	if (!input.incident || !input.incident.database_value) {
        ss.addInfoMessage('Select record.');
        return;
    }    
	if (input.operation_code == OPERATION_GET_DESCRIPTION) {
        data.description = getIncidentDescription(input.incident.database_value);
    }    
	if (input.operation_code == OPERATION_SAVE_DESCRIPTION) {
        sendIncidentDescription(input.incident.database_value, input.description);
        ss.addInfoMessage('The incident description is updated.');
    }    
	if (input.operation_code == OPERATION_GO_TO_INCIDENT) {
        data.redirect_url = createUrlFromIncidentNumber(input.incident.database_value);
    }    
	function getIncidentDescription(incident_id) {
      	if (!incident_id) {
        	return;
        }
        let record = new SimpleRecord('itsm_incident');
        record.addQuery('sys_id', incident_id);
        record.query();
       	if (record.next()) {
        	return record.description;
        }
        ss.addInfoMessage('Incident is not found');
    }    
	function sendIncidentDescription(sys_id, description) {
        let record = new SimpleRecord('itsm_incident');
        record.addQuery('sys_id', sys_id);
        record.query();
        if (record.next()) {
            record.description = description;
            record.update();
        }
    }    
	function createUrlFromIncidentNumber(sys_id) {
        return `/record/itsm_incident/${sys_id}`;
    }    
	function getTableId(tableName) {
        let record = new SimpleRecord('sys_db_table');
        record.addQuery('name', tableName);
        record.query();
        if (record.next()) {
            data.table_id = record.sys_id;
        }
    }
})();

Client controller

You can set user methods for the widgets with the window.s_widget_custom variable in the client script.

The client script includes three s_widget_custom methods declared:

• window.s_widget_custom.getDescription – to get an incident description from the server controller.
• window.s_widget_custom.sendDescription – to send it back.
• window.s_widget_custom.goToIncident – to open the incident record form.

Each method invokes s_widget.serverUpdate() for sending and receiving data back from the server controller. The data object allows accessing the redirect_url variable received from the server script.

;(() => {
  window.s_widget_custom = window.s_widget_custom || {}; 
  s_widget.serverUpdate();
  window.s_widget_custom.getDescription = function () {
    s_widget.setFieldValue('operation_code', 1);
    s_widget.serverUpdate();
  };  
  window.s_widget_custom.sendDescription = function () {
   	s_widget.setFieldValue('operation_code', 2);
    s_widget.serverUpdate();
  };  
  window.s_widget_custom.goToIncident = async function () {
    s_widget.setFieldValue('operation_code', 3);
    const response = await s_widget.serverUpdate();
    const data = response.getData();
    s_go.open(data.data.redirect_url);};
})();

HTML Template

The widget template defines the fields and buttons displayed using HTML and SimpleTags. Clicking the buttons activates the methods declared in the client controller.

<div style="width: '600px', marginBottom: '20px'">
    <h2>Incident Description Widget</h2>
    <reference data-table="itsm_incident" 
		data-table_id="options.table" label="Incident" 
		model="data.incident"></reference>
    <textarea label="Description" model="data.description" 
		class="textColorRed"></textarea>
    <button event-click="window.s_widget_custom.getDescription();">get</button>
    <button event-click="window.s_widget_custom.sendDescription();">send</button>
    <button event-click="window.s_widget_custom.goToIncident();">go</button>
</div>

Use the CSS field to specify a style of the template components displayed.

.textColorRed textarea {
   color: red;
}

Widget interaction

In cases when you need widgets to interact with each other, use s_widgets methods in your client scripts: 

• Receive and change the widget data with the s_widgets.getFieldValue(widgetID, key) and s_widgets.setFieldValue(widgetID, key, value) methods:

  window.s_widgets.getFieldValue('157555401214600424', 'name');
  window.s_widgets.getFieldValue('157555401214600424', 'name', 'Alex');

• Get all the IDs of the widgets on the current page using the s_widgets.getWidgets() method:

  window.s_widgets.getWidgets();

• See what elements the widget contains using the s_widget.getElements() method:

  window.s_widget.getElements();