Tutorial: Build a custom widget

Tutorial: Build a custom widget Tutorial: Build a custom widget

Follow this tutorial to build a custom widget that displays Service Catalog items. Use this tutorial as a model to help you understand the advanced scripting power of the Service Portal .

In this tutorial, you will create the Quick Order widget. This widget: Displays popular items to the user prior to any search. Queries the Service Catalog and displays available options to the user. Includes an embedded SC Catalog Item widget, allowing the user to view and order items within the Quick Order widget. Uses an Angular Provider to display a category icon beside each queried item.

Parent Topic: Developing custom widgets Create a widget and set up a template

Create the Quick Order widget to query items in the Service Catalog .

Role required: admin or sp_admin

Navigate to All > Service Portal > Service Portal Configuration and click Widget Editor . Click Create a new widget . Define the following values. Widget Name : Quick Order Widget ID : quick_order Create a test page : Active Page ID : quick_order

Adding a widget to a test page creates a record in each of the following tables:

sp_page sp_container sp_row sp_column sp_instance sp_widget

Note: You can use the Page Editor in Service Portal Configuration to view the hierarchy of elements on your test page.

Click Submit . From the Widget Editor , open the Quick Order widget. Add the following simple template to the HTML field. Request an item from the catalog My catalog results Click Save . Preview your test page in a new tab using the following URL: /sp?id=quick_order . Your widget template displays on the test page.

Add a server script to query an instance table

After adding your widget and creating a basic template, you can define advanced client and server scripts that enable users to query data from an instance table. You can pass the data model between the client and server by querying data from the database, displaying it to the user, and sending any updates back to the server.

Role required: admin or sp_admin

From the Widget Editor , open the Quick Order widget. Select Server Script to open the server script field. Replace the default server script with the following custom script. ( function () { if (input.keywords != null && input.keywords != '' ) data.items = getCatalogItems(input.keywords); function getCatalogItems(keywords) { var sc = new GlideRecord( 'sc_cat_item' ); sc.addActiveQuery(); sc.addQuery( '123TEXTQUERY321' , keywords); sc.addQuery( 'sys_class_name' , 'NOT IN' , 'sc_cat_item_wizard,sc_cat_item_content' ); sc.addQuery( 'sc_catalogs' , 'e0d08b13c3330100c8b837659bba8fb4' ); sc.setLimit( 100 ); sc.orderByDesc( "ir_query_score" ); sc.query(); var results = []; while (sc.next()) { if (!$sp.canReadRecord(sc)) continue ;

var item = {}; $sp.getRecordDisplayValues(item, sc, 'name,price,sys_id' ); item.category = sc.getValue( 'category' ); results.push(item); } return results; } })();

This script performs a keyword search on the sc_cat_item table using the 123TEXTQUERY321 query method.

Replace the HTML template with the following script: Request an item from the catalog { {item.name}} { {item.price}}

This template adds a search field and displays the results of the query performed in the server script using the following Angular directives. To learn more about these directives, review the Angular API Reference .

Table 1. Angular directives used in the template Angular directive Description ng-model Automatically reads and writes value changes to the model variable c.data.keywords . ng-model-options Configures ng-model behavior. In this template, ng-model updates the model after a user has stopped typing for 250 milliseconds. ng-change Executes c.server.update() after the model value changes. This function posts the data object to the server script. After the script is executed, the data object is automatically updated with the new values from the server generated data object. ng-repeat Creates a template from the parent element and child elements. For each item in c.data.items , an instance of the template is created and the expressions { {item.name}} and { {item.price}} are replaced with the values from each item.

Add the following script to the CSS - SCSS field: .result-container { margin-top : 10 px; }

Refresh your test page preview to view the changes. As you type in the search box, matching catalog items appear. Try searching for ipad .

Manage the empty state of a widget

Display a list of popular items to the user before any search terms are entered.

Role required: admin or sp_admin

Because no search has been executed when the widget initializes, the server input variable is undefined. This empty state may cause confusion when a user first interacts with the widget. To solve this issue, give your widget something to display when the input variable is empty. This initial data can guide your users when initially interacting with your widget.

From the Widget Editor , open the Quick Order widget. Replace the existing server script with the following script: ( function () { if (input.keywords != null && input.keywords != '' ) data.items = getCatalogItems(input.keywords); else data.items = getPopularItems();

function getCatalogItems(keywords) { var sc = new GlideRecord( 'sc_cat_item' ); sc.addActiveQuery(); sc.addQuery( '123TEXTQUERY321' , keywords); sc.addQuery( 'sys_class_name' , 'NOT IN' , 'sc_cat_item_wizard,sc_cat_item_content' ); sc.addQuery( 'sc_catalogs' , 'e0d08b13c3330100c8b837659bba8fb4' ); sc.setLimit( 100 ); sc.orderByDesc( "ir_query_score" ); sc.query(); var results = []; while (sc.next()) { if (!$sp.canReadRecord(sc)) continue ;

var item = {}; $sp.getRecordDisplayValues(item, sc, 'name,price,sys_id' ); item.category = sc.getValue( 'category' ); results.push(item); } return results; }

function getPopularItems() { var items = []; var count = new GlideAggregate( 'sc_req_item' ); count.addAggregate( 'COUNT' , 'cat_item' ); count.groupBy( 'cat_item' ); count.addQuery( 'cat_item.sys_class_name' , 'NOT IN' , 'sc_cat_item_guide,sc_cat_item_wizard,sc_cat_item_content' ); count.addQuery( 'cat_item.sc_catalogs' , 'e0d08b13c3330100c8b837659bba8fb4' ); count.orderByAggregate( 'COUNT' , 'cat_item' ); count.query(); while (count.next() && items.length 9 ) { if (!$sp.canReadRecord( "sc_cat_item" , count.cat_item.sys_id.getDisplayValue())) continue ; // user does not have permission to see this item

var item = {}; item.name = count.cat_item.name.getDisplayValue(); item.category = count.cat_item.category.toString(); item.price = count.cat_item.price.getDisplayValue(); item.sys_id = count.cat_item.sys_id.getDisplayValue(); items.push(item); } return items; } })();

This script introduces a new function getPopularItems() to query the database and return popular items when the input variable is empty.

Replace the HTML template with the following script: Request an item from the catalog Showing the most popular items { {item.name}} { {item.price}} { {c.data.keywords}}

This script provides a template to display the popular items returned from the server script.

Refresh your test page preview to view the changes. The widget displays popular items to the user prior to any search input.

Embed an existing widget

Enable the user to view and purchase Service Catalog items in the Quick Order widget by embedding the SC Catalog Item widget.

Role required: admin or sp_admin

Instead of duplicating code, you can embed widgets to leverage pre-existing functionality. The SC Catalog Item widget is a base system widget that enables the user to view and purchase Service Catalog items.

Inspect the SC Catalog Item widget. Before embedding the SC Catalog Item widget, inspect the widget to understand what data it needs access to. You may need to update your Quick Order widget client or server script to make sure that the correct data is passed to the embedded widget. Navigate to /sp_config?id=widget_editor . Open the SC Catalog Item widget. Note that the widget ID is widget-sc-cat-item . You will use this ID to embed the widget model in the client script. Examine the server script. Notice that the data object includes a sys_id property populated by either the input or options objects. If neither input nor options include a sys_id, the $sp.getParameter() method retrieves the sys_id from the request query string.

To populate the input object, you can pass a catalog item sys_id from the Quick Order widget client script.

From the Widget Editor , open the Quick Order widget. Replace the Quick Order widget client script with the following script. function ($location, spUtil) { var c = this ;

c.select = function (item_id) { if (c.openItem == item_id) { c.openItem = null; return ; }

renderCatalogItemWidget(item_id); }

This script uses spUtil.get() to retrieve the widget model by ID ( widget-sc-cat-item ) and define the {sys_id: item_id} object. This object posts to the server script as input .

Replace the HTML template with the following script: Request an item from the catalog Showing the most popular items { {item.name}} { {item.price}} { {c.data.keywords}}

This template:

Adds on-click behavior using the ng-click directive. Displays the embedded SC Catalog Item widget using the sp-widget directive.

Replace the CSS with the following script: .result-container { margin-top : 10 px; }

.catalog-item { background-color : #f5f5f5; padding : 10 px; @include border-top-radius($panel-border-radius); @include border-bottom-radius($panel-border-radius); }

Refresh your test page preview to view the changes. When you select a search result, the item opens in the embedded SC Catalog Item widget.

Create a reusable directive and add it to a widget

Angular Providers are reusable components that can be added to multiple widgets. Using the Widget Angular Providers table, create a directive that shows a category icon next to each result in the Quick Order widget.

Role required: admin or sp_admin

Angular Providers let you build angular directives and services that can be injected into your client script controller. The code in a Provider differs from a typical Angular directive or service because it must be anonymous, without being appended to a specific module.

Navigate to All > Service Portal > Service Portal Configuration > Portal Tables > Widget Angular Provider . The Widget Angular Providers table opens. Select New to create a new record. Fill out the form. Add the type and name. Type : Directive Name : categoryIcon

Add the client script. function () { return { template: ' {::icon}} fa-stack-1x fa-inverse"> ' , restrict: 'E' , replace: true, scope: { category: '=' }, link: function (scope, element) {

var _iconMap = { "b06546f23731300054b6a3549dbe5dd8" : "tablet" , /* Tablets */ "15706fc0a0a0aa7007fc21e1ab70c2f" : "question" , /* Can we help you? */ "d68eb4d637b1300054b6a3549dbe5db2" : "mobile-phone" , /* Mobiles */ "109cdff8c6112276003b17991a09ad65" : "print" , /* Office and Print */ "5d643c6a3771300054b6a3549dbe5db0" : "print" , /* Printers */ "2c0b59874f7b4200086eeed18110c71f" : "plug" , /* Peripherals */ "2809952237b1300054b6a3549dbe5dd4" : "desktop" , /* Software */ };

scope.icon = _iconMap[scope.category] || "shopping-cart" ; } } }

This script associates the sys_id of the Category record with the Service Catalog item. The icon that displays is the icon defined in the Category record in the Service Catalog .

Select Save .

Associate the new Angular directive with the Quick Order Widget. Navigate to All > Service Portal > Widgets . Open the Quick Order widget. Under Related Lists , select Angular Providers . In the Angular Providers list, select Edit and associate the categoryIcon Angular Provider with the Quick Order widget. Select Save .

Add the categoryIcon directive to your Quick Order HTML template. From the Widget Editor , open the Quick Order widget. Replace the HTML template with the following script. Request an item from the catalog Showing the most popular items { {item.name}} { {item.price}} { {c.data.keywords}}

Refresh your test page preview to view the changes. A category icon displays beside each result.