Widget instance options

Widget developers can configure their own options for a widget instance.

Widget instances allow users to uniquely configure each widget they add to a page. When you build a widget from scratch you can also add instance options to your widget using the Option Schema.

An Option Schema is a way of defining what properties users of your widgets can define. Any properties declared here display when a user is editing the instance of a widget. Use the Option Schema to enable users to declare many types of fields, from primitive String and Numbers to reference fields.

  1. From the Service Portal Configuration page, navigate to the Widget Editor, and select the widget you want to configure the Option Schema for.
  2. Click the menu icon (Menu icon) and select Edit Option Schema.

    Blank widget options schema menu

  3. Click the + icon to add a widget option with a label, a name, a type, and a hint.

    Blank widget options schema menu

  4. Save your changes, then view your configuration by navigating to an instance of the widget on a page. Then Control + right-click the widget and select Instance Options.

Use options in a widget

Access options in the widget from both the client script and the server script.

Client script
function() {
  /* widget controller */var c =this;
    console.log(c.options.text_color) //Outputs the text_color option for this instance
}
Server script
(function() {
     $sp.log(options.text_color) //Logs the value of the text_color option to the browser console.
})();

Default options

Before an option value is set on an instance, it appears as an undefined value when you access that option variable. Use the server script of a widget to specify default values for your options, in order to handle the situation where those option values haven't been provided yet.

For example, the Server Script in JavaScript:
(function() {
  options.text_color=options.text_color||"blue";
  options.maximum_entry_count=options.maximum_entry_count||5;
})