Recommendations for developing widgets

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

Create a default state that provides an example to the end user

When initially added to a page, a widget does not have instance options defined. If a default state is not provided, a widget can appear empty and can cause confusion. Instead of creating a widget that defaults to an empty state, give your widget default data to display when no other options are defined to:

  • Clearly demonstrate the widget functionality to the user.
  • Provide data when previewing the widget in the widget editor.

Learn more: Tutorial: Build a custom widget.

Create a directive instead of embedding a complex widget

When an embedded widget is called from the server, all the scripts associated with that widget are returned. If you only need to embed a subsection of a widget, embedding the entire widget creates unnecessary overhead. Instead, use directives to share lightweight code between widgets. Use a directive instead of an embedded widget to:

  • Share scope or custom scope behavior with multiple widgets.
  • Share a reusable, lightweight subsection of a widget.
  • Share a common UI feature, such as a list or an avatar.
  • Augment widget behavior.

Learn more: Reuse components with Angular Providers.

Use a service or factory to share data and persist state

Data services and factories maintain and persist state in a widget without requiring multiple server calls enabling you to:

  • Keep widgets in sync when changing records or filters.
  • Share context between widgets.
  • Develop more performant widgets.

Learn more: Reuse components with Angular Providers.

Handle events with a publish/subscribe service

Avoid using $broadcast in the DOM. $broadcast dispatches the event name to all child scopes notifying registered listeners, which can be an expensive call that requires the use of the $rootScope global object.

Instead, use a publish/subscribe service to handle events. When using a publish/subscribe service, a clear relationship forms between your widgets through callback handlers. In this model, you can better control the state of your events.

Use REST calls to fetch data from the server

When you call server.update(), the entire widget is returned from the server. If your widget includes divergent code paths, multiple calls to update the server can affect performance. As a rule, use your server script to set up the initial state of your widget. For subsequent updates, use scripted REST APIs that call script includes on your instance. This practice:

  • Separates business logic from the display.
  • Centralizes your code, allowing changes to be made in one place.
Develop with localization, accessibility, and UI in mind

To create the best experience for your users, follow these guidelines:

  • Consider the impact of your widget in a mobile environment. For example, avoid using mouseover and other events that do not translate to a mobile device.
  • Use SCSS variables to reuse items.
  • Use variable names when using colors.
  • Wrap strings for translation in localization APIs. See Internationalize a widget.

Service Portal debugging tips