Page History

Create a widget

A widget includes four components that define its view, execution, and behavior:

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.
Server script runs a JS script on the server-side and processes the data received from the client-side and passes it back.
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 data input received to the server-side.
Demo data specifies widget options available for further customization and processing if it is needed.

Widget creation

Tip
Role required: admin.

To create a widget, follow complete the following steps below:

Navigate to Portal Structure → Widgets.
Click New and fill in the fields.
Click Save or Save and Exit to apply the changes.

Widget form fields

Field	Mandatory	Description
Name	Y	Specify the name of

your

the widget.
Description	N

Describe

Add a detailed description of the widget

in details

.
Active	N	Select this checkbox to

make

enable the widget functionality

available

.

Template

N

Determine the widget display view with the <div> container:

Code Block

language	xml

<div></div>

Use SimpleTags to define the form, fields, and the behavior you need:

Code Block

language	xml
linenumbers	true

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

Apply

Widget

Tag Attributes to specify and describe the widget element behavior:

Code Block

language	xml
linenumbers	true

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

CSS

N

Specify the CSS classes

for

to create the

widget

structure and style of the widget.
Tables	N

A list field type with reference to the Table (sys_db_table) dictionary.

Specify the tables

, which views can be extended by adding a

to add the widget to their forms using the Form Layout functionality.

To make the widget available for adding to any table, choose the Global (sys_global) table.

Inheritance

N

Select this checkbox if you

want

need to make

a

the widget available for adding to child

tables'

table records.
Server Script	N

Use this controller to specify

Specify a script that defines how the widget sends, receives and processes system events on the server-side.

The server script uses the input object to access the data received from the client controller and the data

object

object for processing and sending it back

as

in JSON.

Use the Server API

to

to create a server script

code

.
Client Script	N

Use this controller to specify

Specify a script that defines how the widget sends, receives and processes system events on the client-side.

The client script uses the data object to access the server data. After processing the data by the client script, invoke the s_widget.serverUpdate() method to send the data to the server controller. When calling this method, the server script data object automatically overwrites the client controller data object.

Use the Client API to create a client script code.

Info
The client controller uses the s_widget object to invoke widget API methods.

Warning
It is not recommended to use native JS methods and properties manipulating the Document Object Model in widget client scripts. For example, using such properties as Element.innerHTML or Element.outerHTML in the client scripts

may

can cause malfunction.

To avoid errors, please use the methods provided and supported by the vendor instead. See the example below.

Code Block

language	js
theme	Eclipse
title	Usage example
linenumbers	true

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

Demo Data

N

Specify the widget options used for the preset configuration. Use the formatting below to define the options:

Code Block
{ value_1: '1'; value_2: 'abc' }

value_1 and and value_2 are options with the '1' and 'abc' default values set.

These options

may

can be overridden

in the situations below

:

when

adding a

the widget is added to a form.
when

adding a

the widget is added to a portal page.

Widget example

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

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

Server controller

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

getting the incident description within the getIncidentDescription(incident_id) function.
updating it within the sendIncidentDescription(sys_id, description) function.
getting a redirect URL within the createUrlFromIncidentNumber(sys_id) function.

Code Block

language	js
title	Server script
linenumbers	true
collapse	true

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

The client script includes the 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 item 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 received from the server script.

Code Block

language	js
title	Client script
linenumbers	true
collapse	true

;(() => {
  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.

Code Block

language	xml
title	Template
linenumbers	true
collapse	true

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

Code Block

language	css
title	CSS
linenumbers	true
collapse	true

.textColorRed textarea {
   color: red;
}

Table of Contents

class	fixedPosition

Page tree

Versions Compared

Old Version 2

New Version 3

Key

Create a widget

Widget example

Server controller

Client controller

HTML Template