spUtil- Client

The spUtil API provides utility methods to perform common functions in a Service Portal widget client script.

These functions include:

• Display a notification error message. spUtil - addErrorMessage(String message)
• Display a notification info message. spUtil - addInfoMessage(String message)
• Display a trivial notification message. spUtil - addTrivialMessage(String message)
• Create a unique identifier. spUtil - createUid()
• Format a string with variables. spUtil - format(String template, Object data)
• Embed a widget model in a widget client script. spUtil - get(String widgetId Object data)
• Retrieve all headers to use for API calls. spUtil - getHeaders()
• Return the complete host domain. spUtil - getHost()
• Execute the callback with User Preference response by passing the preference name. spUtil - getPreference(String preference, Function callback)
• Return the current service portal URL information. spUtil - getURL()
• Check if the current client is a mobile device. spUtil - isMobile()
• Parse the comma-separated attributes within a specified string. spUtil - parseAttributes(String attributes)
• Watch for updates to a table or filter and returns the value from the callback function. spUtil - recordWatch(Object $scope, String table, String filter, Function callback)
• Call the server and replaces the current options and data with the server response. spUtil - refresh(Object $scope)
• Scroll to the element with the specified selector, over a specified period of time. spUtil - scrollTo(String selector, Number time)
• Update the header breadcrumbs. spUtil - setBreadCrumb(Object $scope, Array breadcrumbs)
• Set a user preference. spUtil - setPreference(String pref, String value)
• Update the search page. spUtil - setSearchPage(String searchPage)
• Update the data object on the server within a given scope. spUtil - update(Object $scope)

For additional information on widgets, see Service Portal widgets.

Parent Topic:Client API reference

spUtil - addErrorMessage(String message)

Displays a notification error message.

spUtil.addErrorMessage("There has been an error processing your request")

spUtil - addInfoMessage(String message)

Displays a notification info message.

spUtil.addInfoMessage("Your order has been placed")

spUtil - addTrivialMessage(String message)

Displays a trivial notification message.

Trivial messages disappear after a short period of time.

spUtil.addTrivialMessage("Thanks for your order")

spUtil - createUid()

Create a unique identifier.

spUtil - get(String widgetId Object data)

Embeds a widget model in a widget client script.

The callback function returns the full widget model. For additional information on widgets, see Service Portal widgets.

Without data passed.

spUtil.get("widget-cool-clock").then(function(response) {
  c.coolClock = response;
});

With data passed.

spUtil.get('pps-list-modal', {title: c.data.editAllocations, 
  table: 'resource_allocation', 
  queryString: 'GROUPBYuser^resource_plan=' + c.data.sysId, 
  view: 'resource_portal_allocations' }).then(function(response) {
    var formModal = response;
    c.allocationListModal = response;
  });   

spUtil - getHeaders()

Retrieves all headers to use for API calls.

spUtil - getHost()

Returns the complete host domain.

spUtil - getPreference(String preference, Function callback)

Executes the callback with User Preference response by passing the preference name.

spUtil - getURL()

Returns the current service portal URL information.

spUtil - format(String template, Object data)

Formats a string that contains variables.

Use this method as an alternative to string concatenation.

spUtil.format('An error ocurred: {error} when loading {widget}', {error: '404', widget: 'sp-widget'})

Output:

'An error occurred: 404 when loading sp-widget'

spUtil - isMobile()

Checks if the current client is a mobile device.

spUtil - parseAttributes(String attributes)

Parses the comma-separated attributes within a specified string.

function getRefQualElements() {
  var refQualElements = [];
  if (field && field.attributes && field.attributes.indexOf('ref_qual_elements') > -1) {
    var attributes = spUtil.parseAttributes(field.attributes);
    refQualElements = attributes['ref_qual_elements'].split(';');
  }
  return refQualElements;
}

spUtil - recordWatch(Object $scope, String table, String filter, Function callback)

Watches for updates to a table or filter and returns the value from the callback function.

Allows a widget developer to respond to table updates in real-time. For instance, by using recordWatch(), the Simple List widget can listen for changes to its data table. If records are added, removed, or updated, the widget updates automatically.

Note: When passing the $scope argument into the recordWatch() function, inject $scope into the parameters of your client script function.

//A simple recordWatch function.
spUtil.recordWatch($scope, "live_profile", "sys_id=" + liveProfileId);

//In a widget client script
function(spUtil, $scope) {
  /* widget controller */
  var c =this;

  // Registers a listener on the incident table with the filter active=true, 
  // meaning that whenever something changes on that table with that filter, 
  // the callback function is executed.    
  // The callback function takes a single parameter 'response', which contains 
  // the property 'data'. The 'data' property contains information about the changed record. 
  spUtil.recordWatch($scope, "incident", "active=true", function(response) {

    // Returns the data inserted or updated on the table 
    console.log(response.data);   

    });
}

spUtil - refresh(Object $scope)

Calls the server and replaces the current options and data with the server response.

Calling spUtil.refresh() is similar to calling server.refresh(). However, when you call spUtil.refresh(), you can define the $scope object.

spUtil - scrollTo(String selector, Number time)

Scrolls to the element with the specified selector, over a specified period of time.

spUtil - setBreadCrumb(Object $scope, Array breadcrumbs)

Updates the header breadcrumbs.

spUtil - setPreference(String pref, String value)

Sets a user preference.

spUtil - setSearchPage(String searchPage)

Updates the search page.

spUtil - update(Object $scope)

Updates the data object on the server within a given scope.

This method is similar to server.update(), but includes a $scope parameter that defines the scope to pass over.

The following example includes a P1 widget that watches for changes to the state field and uses a filter to watch all active P1s and let the callback function determine whether to refresh the data. The data.changes property contains an array of any updated fields. If the state of any fields have changed, the data is updated in the widget.

var q = "priority=1^active=true^EQ";
spUtil.recordWatch($scope, "incident", q, function(event, data) {
   if (data.changes.includes("state")) { // only update if state was updated.
      spUtil.update($scope);
   }
});