Widget option schema

Widget instances allow users to uniquely configure each widget they add to a page. Use the option schema to define the parameters for your widget.

Storing instance options

When developing a widget, you can edit the option schema to create parameters for your widget, or you can create a table to store instance options. If you edit the existing option schema, any instance options defined are stored in JSON format in the Additional options, JSON format field in the sp_instance table. The following field types are available:

  • String
  • Boolean
  • Integer
  • Reference
  • Choice
  • Field_list (depends on table)
  • Field_name (depends on table)
  • Glide_list

To use other field types not supported in the option schema, create an extension table to store your custom widget option schema. Using a table enables you to:

  • Add any ServiceNow field type, including fields with advanced customization, to the option schema.
  • Define a complex option schema.
  • Search and filter instance options.
Note: While storing options in a table enables you to define more complex options, this method is more difficult to maintain than editing the option schema. To avoid creating unnecessary tables and adding additional server calls to your widget, edit the existing option schema when possible. Store options in a table only when complex or searchable options are required.

Using options in a widget

Access options in the widget from both the client script and the server script using the options global variable. You can access to any option value in your widget client script or server script using options.optionName.

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

Define 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 widget server script to specify default values for your options.

(function() {
  options.text_color=options.text_color||"blue";
  options.maximum_entry_count=options.maximum_entry_count||5;
})