Embedded Widgets

In Service Portal, widgets can be embedded inside other widgets. This technique is useful for creating more powerful widgets through the composition of other widgets.

For a direct example of this, see the Social QA Question widget, which embeds a login widget next to the Answer Question section for an easy way to prompt users to login to answer questions.

Widget Directive Syntax

You can embed any widget inside of your widget’s HTML template using the custom <widget><widget> element. The basic usage looks like this:

HTML Template
  <widget id="widget-cool-clock"></widget>

The id parameter is simply the id of the widget you're trying to embed.

Widget Options

Widgets might have options that you can setup. You can define their values in JSON format:

Providing options in the HTML template

HTML Template
<widget id="widget-cool-clock" options='{"zone": "America/Los_Angeles","title": "San Diego, CA"}'><widget>

Clock Options

You don't necessarily need to provide options in the HTML template.

Providing options server-side

HTML template
<widget id="widget-cool-clock" options='data.clockOptions'><widget>
Server Script
(function() {
  data.clockOptions = {"zone": "America/Los_Angeles","title": "San Diego, CA"};

Embedded Widgets client-side

HTML Template
<sp-widget widget="c.myClockWidget"></sp-widget>
Client Script
function(spUtil) {
    var c = this;
    spUtil.get("widget-cool-clock").then(function(response) {
            c.myClockWidget = response;

Example: How to embed a widget multiple times with custom options

Each instance of the clock is provided a different timezone and title.

To see what options are configurable in the cool clock widget, open it in the widget editor. It uses the options object for the title, second hand color, and the timezone. This screenshot shows you where they're hiding.

Cool clock client script

Edit the "Embedded clock" widget and replace with the following code blocks:

HTML Template
<div class="panel panel-default">
  <div class="panel-heading">Time across the US</div>
  <div class="panel-body">
    <div class="row">
      <div class="col-sm-3" ng-repeat="myClock in c.data.clocks">
        <sp-widget widget="myClock"></sp-widget>
.panel {
    margin-top: 10px;
Client Script
function() {
    // nothing to do here...
Server Script
(function() {
    var options = [
        {zone: "America/Los_Angeles", title: "San Diego"},
        {zone: "America/Denver", title: "Denver"},
        {zone: "America/Chicago", title: "Chicago"},
        {zone: "America/New_York", title: "New York"}

    data.clocks = [];
    for (var i in options) {
        data.clocks.push($sp.getWidget("widget-cool-clock", options[i]));


Each instance of the clock widget has a different timezone and title.

Embedded clock

API Reference

Client Side

spUtil.get() - Get a widget model via client script
spUtil.get("widget-sc-cat-item", {sys_id: "your_catalog_item_sys_id"}).then(function(response) {
    c.catalogItemWidget = response;


  • (string) widget_id
    Can be a widget_id or widget sys_id.
  • (object) data
    An object to post to the widget's server script. Refer to this object as input in your server script.


The callback function is called when the widget model is ready. The response object contains the full widget model.

Server Side

$sp.getWidget() - Get a widget model via server script
data.catalogItemWidget = $sp.getWidget("widget-sc-cat-item", {sys_id: "your_catalog_item_sys_id"});


  • (string) widget_id
    Can be a widget_id or widget sys_id.
  • (object) options
    An object to pass to the widget's server script. Refer to this object as options in your server script.

Note: As of all versions of Helsinki, any options passed into this function will only be available in the embedded widget's server script on the first execution of that script. Any subsequent calls into the server script from the embedded widget will not contain the object properties passed in. This is something we are investigating for a future version of Helisinki or Istanbul.

Widget Model in depth

The widget model contains all of the client-side parts of a widget needed to create an angular directive. The HTML template, client script, and link function are loaded just as they are in the sp_widget record. The data property is the result of the widget's server script execution. Anything that you put on the data object on the server is available in the data object on the client.

Here is a detailed look at some of the fields in the widget model:

Property name Type Description
client_script string The widget's client script field
css string The compiled css output from the widget's sass field
data object The data object containing all of the keys and values added to it in the widget's server script
dependencies array A collection of javascript libraries to load before the widget executes
options object The options used to initialize the widget
template string The widget's HTML Template field

Error: Please enter a valid email address

Error: Invalid email

Error: Please enter your first name

Error: Please enter your last name

Error: Please enter a username

Error: Please enter a password

Error: Please confirm your password

Error: Password and password confirmation do not match