Developing custom widgets

  • Release version: Xanadu
  • Updated August 1, 2024
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Developing custom widgets

    Develop custom widgets in ServiceNow portals using AngularJS, Bootstrap, and the ServiceNow API to create dynamic, reusable components that enhance user experience. Widgets enable you to interact with server data, gather user input, and customize portal pages with flexible options and external dependencies.

    Show full answer Show less

    Key Components of a Widget

    • HTML template: Mandatory component using AngularJS to render views, bind variables, and collect user input.
    • Client script: Mandatory controller script using AngularJS and ServiceNow API to map server data, process data before display, and send user input back to the server.
    • Server script: Mandatory script that initializes widget state, runs server-side queries, and sends data to the client.
    • Link function: Optional AngularJS function to manipulate the DOM directly.
    • Option schema: Optional configuration allowing portal admins to define widget parameters for flexible instances.
    • Angular Providers: Optional reusable components to share data, maintain state, and inject behaviors across multiple widgets for better performance.
    • Dependencies: Optional external JavaScript or CSS resources linked to widgets for enhanced functionality or styling.

    Global Objects and Data Flow

    Widgets use three global objects during rendering: input (data from client to server), options (widget initialization parameters), and data (server data sent to client). The server script initializes these, sending data as JSON to the client script, which accesses it via c.data. Client scripts use server.update() to send updates back, with c.options providing read-only configuration values.

    Developing and Managing Widgets

    • Widget Editor: Use this IDE-like environment in Service Portal Configuration to create, edit, and preview widgets in real time.
    • Creating and cloning widgets: Build new widgets from scratch or clone existing ones to leverage reusable code.
    • Option schema: Define customizable parameters so users can tailor widget instances on portal pages.
    • Widget API: Utilize provided client-side and server-side APIs for efficient scripting within widgets.
    • Reuse with Angular Providers: Implement reusable services to improve performance and maintain shared state across widgets.
    • Embedded widgets: Include widgets within other widgets’ HTML, client, or server scripts.
    • Widget dependencies: Link third-party libraries and stylesheets to widgets for extended functionality.
    • Internationalization: Use syntax like ${} or gs.getMessage() to enable translation and localization of widget content.
    • Replacing UI Macros: Create widgets to replace Service Catalog form UI Macros, allowing better reuse and integration.

    Troubleshooting

    Use the Widget Diagnostics tool to detect customization levels and debug widget issues directly from Service Portal pages, helping identify and resolve unexpected behaviors quickly.

    Develop custom widgets for portals using AngularJS, Bootstrap, and the ServiceNow API.

    Before you begin

    To develop widgets, you need ServiceNow API experience to:
    • Run record queries on the server.
    • Create and update records.
    You need AngularJS experience to:
    • Bind variables to client controllers.
    • Access server objects in a widget.
    • Gather user input.

    Optionally, you can build on the Bootstrap template by accessing Bootstrap components.

    Parts of a widget

    Like Angular directives, widgets execute a specified behavior within a Service Portal page. A widget includes mandatory and optional scripting components.

    HTML template

    A mandatory widget component.

    The HTML template requires knowledge of AngularJS to display and gather data. Use the HTML template to:

    • Render the dynamic view that a user sees in the browser using information from the model and controller.
    • Bind client script variables to your markup.
    • Gather data from the end user.
    Client script

    A mandatory widget component.

    A client script requires knowledge of both the ServiceNow API and AngularJS to create a client controller. Use the client script to:

    • Map server data from JavaScript and JSON objects to client objects.
    • Process data before rendering it.
    • Pass data to the HTML template.
    • Pass user input and data back to the server for processing.
    Server script

    A mandatory widget component.

    A server script requires knowledge of the ServiceNow API to work with record data. Use the server script to:

    • Set the initial state of the widget.
    • Send record data to the widget client script using the data variable.
    • Run server-side queries.
    Link function

    An optional widget component.

    The link function requires knowledge of AngularJS. Use a link function to directly manipulate the DOM.

    Option schema

    An optional widget component.

    Allows a Service Portal admin to configure a widget. Use the option schema to:

    • Specify the parameters for a widget.
    • Allow admin users to define instance options for a widget instance.
    • Develop flexible, reusable widgets.
    Angular Providers

    An optional widget component.

    Angular Providers require knowledge of AngularJS. Use Angular Providers to:

    • Keep widgets in sync when changing records or filters.
    • Share context between widgets.
    • Maintain and persist state.
    • Create reusable behaviors and UI components and inject them into multiple widgets.
    Dependencies

    An optional widget component.

    A widget dependency is an external resource used by your widget such as JavaScript or CSS files.

    Global objects in widgets

    When a widget begins to render for the first time on a page, the server script executes first and accesses three global objects: input, options, and data. Because the input variable is a data object sent from the client script, this variable is undefined when first initialized.

    Available variables in server and client script global

    When a widget is first instantiated, the server script:

    1. Initializes an empty data object.
    2. Initializes the input object with any data sent from the client controller, or the options object with any data used to initialize the widget.
    3. Sends the data object to the client controller as JSON.

    The client script:

    1. Accesses the server data object using c.data.

      Note:
      By default, widgets use the c variable to represent the controller instance using controller as syntax. You can change this variable when creating or cloning widgets.

    2. Uses server.update() to post changes to the data model. This method updates the server script using the input object.

      Note:
      After calling server.update(), the client script data object is automatically overwritten by the server script data object.
    3. Uses c.options to access the values used to invoke the widget on the server. This object is read-only.

    Using the Widget Editor

    When you create a widget, a record is created in the sp_widget table. However, you can use the Widget Editor in Service Portal Configuration as your scripting environment. The Widget Editor is a full page application similar to an IDE. You can show the parts of the widget you want to edit and hide the rest, while previewing your changes in real time.

    Widget editor with the calculator widget showing script examples for the HTML template, CSS, Client script, and the server script