Product documentation Docs
    • English
    • Deutsch
    • 日本語
    • 한국어
    • Français
  • More Sites
    • Now Community
    • Developer Site
    • Knowledge Base
    • Product Information
    • ServiceNow.com
    • Training
    • Customer Success Center
    • ServiceNow Support Videos
  • Log in

Product documentation

  • Home
How search works:
  • Punctuation and capital letters are ignored
  • Special characters like underscores (_) are removed
  • Known synonyms are applied
  • The most relevant topics (based on weighting and matching to search terms) are listed first in search results
Topics are ranked in search results by how closely they match your search terms
  • A match on the entire phrase you typed
  • A match on part of the phrase you typed
  • A match on ALL of the terms in the phrase you typed
  • A match on ANY of the terms in the phrase you typed

Note: Matches in titles are always highly ranked.

  • Release version
    Table of Contents
    • Now Platform capabilities
Table of Contents
Choose your release version
    Home New York Now Platform Capabilities Now Platform capabilities Service Portal Service Portal widgets Widget developer guide

    Widget developer guide

    • Save as PDF Selected topic Topic & subtopics All topics in contents
    • Unsubscribe Log in to subscribe to topics and get notified when content changes.
    • Share this page

    Widget developer guide

    Develop custom widgets in the Service Portal using AngularJS, Bootstrap, and the ServiceNow API.

    What to know 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. Service Portal uses Bootstrap version 3.3.6.

    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
    • Recommendations for developing widgets

      When developing custom widgets, keep these recommendations in mind for optimal performance, scalable development, and a good user experience.

    • Clone a widget

      Take advantage of existing code by cloning and editing an existing widget.

    • Create a new widget

      Create a new widget to build a custom widget from scratch.

    • 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.

    • Reuse components with Angular Providers

      Angular Providers are reusable components that can be injected into multiple widgets. To ensure quick loading widgets and a high performing portal, create Angular Providers instead of overloading your client controllers with persistent data and additional logic. With Angular Providers, you can maintain data for the lifetime of your Service Portal and reuse components and data objects across multiple widgets.

    • Embedded widgets

      Embed a widget in the HTML template, server script, or client script.

    • Create a widget dependency

      In Service Portal, you can link JavaScript and CSS files to widgets to create dependencies between widgets and third-party libraries, external style sheets, and angular modules.

    • Internationalize a widget

      Use the ${} or gs.getMessage() syntax in widgets to tag strings for translation so you can localize your Service Portal content.

    • Tutorial: Build a custom widget

      Follow this tutorial to build a custom widget that displays Service Catalog items. Use this tutorial as a model to help you understand the advanced scripting power of the Service Portal.

    • Widget API reference

      Service Portal includes client and server side APIs to use in widget client and server scripts.

    • Widget troubleshooting guide

      Use the following tools to investigate and resolve unexpected behavior in your custom Service Portal widgets.

    Tags:

    Feedback
    On this page

    Previous topic

    Next topic

    • Contact Us
    • Careers
    • Terms of Use
    • Privacy Statement
    • Sitemap
    • © ServiceNow. All rights reserved.

    Release version
    Choose your release version

      Widget developer guide

      • Save as PDF Selected topic Topic & subtopics All topics in contents
      • Unsubscribe Log in to subscribe to topics and get notified when content changes.
      • Share this page

      Widget developer guide

      Develop custom widgets in the Service Portal using AngularJS, Bootstrap, and the ServiceNow API.

      What to know 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. Service Portal uses Bootstrap version 3.3.6.

      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
      • Recommendations for developing widgets

        When developing custom widgets, keep these recommendations in mind for optimal performance, scalable development, and a good user experience.

      • Clone a widget

        Take advantage of existing code by cloning and editing an existing widget.

      • Create a new widget

        Create a new widget to build a custom widget from scratch.

      • 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.

      • Reuse components with Angular Providers

        Angular Providers are reusable components that can be injected into multiple widgets. To ensure quick loading widgets and a high performing portal, create Angular Providers instead of overloading your client controllers with persistent data and additional logic. With Angular Providers, you can maintain data for the lifetime of your Service Portal and reuse components and data objects across multiple widgets.

      • Embedded widgets

        Embed a widget in the HTML template, server script, or client script.

      • Create a widget dependency

        In Service Portal, you can link JavaScript and CSS files to widgets to create dependencies between widgets and third-party libraries, external style sheets, and angular modules.

      • Internationalize a widget

        Use the ${} or gs.getMessage() syntax in widgets to tag strings for translation so you can localize your Service Portal content.

      • Tutorial: Build a custom widget

        Follow this tutorial to build a custom widget that displays Service Catalog items. Use this tutorial as a model to help you understand the advanced scripting power of the Service Portal.

      • Widget API reference

        Service Portal includes client and server side APIs to use in widget client and server scripts.

      • Widget troubleshooting guide

        Use the following tools to investigate and resolve unexpected behavior in your custom Service Portal widgets.

      Tags:

      Feedback

          Share this page

          Got it! Feel free to add a comment
          To share your product suggestions, visit the Idea Portal.
          Please let us know how to improve this content

          Check any that apply

          To share your product suggestions, visit the Idea Portal.
          Confirm

          We were unable to find "Coaching" in Jakarta. Would you like to search instead?

          No Yes
          • Contact Us
          • Careers
          • Terms of Use
          • Privacy Statement
          • Sitemap
          • © ServiceNow. All rights reserved.

          Subscribe Subscribed Unsubscribe Last updated: Tags: January February March April May June July August September October November December No Results Found Versions Search preferences successfully updated My release version successfully updated My release version successfully deleted An error has occurred. Please try again later. You have been unsubscribed from all topics. You are now subscribed to and will receive notifications if any changes are made to this page. You have been unsubscribed from this content Thank you for your feedback. Form temporarily unavailable. Please try again or contact  docfeedback@servicenow.com  to submit your comments. The topic you requested does not exist in the release. You were redirected to a related topic instead. The available release versions for this topic are listed There is no specific version for this documentation. Explore products Click to go to the page. Release notes and upgrades Click to open the dropdown menu. Delete Remove No selected version Reset This field is required You are already subscribed to this topic Attach screenshot The file you uploaded exceeds the allowed file size of 20MB. Please try again with a smaller file. Please complete the reCAPTCHA step to attach a screenshot
          Log in to personalize your search results and subscribe to topics
          No, thanks Login