widget

require(["esri/widgets/support/widget"], function(widget) { /* code goes here */ });
Object: esri/widgets/support/widget
Since: ArcGIS API for JavaScript 4.2

This module contains widget helpers which aid in custom widget development.

Method Overview

Name Return Type Summary Object
Function

This convenience decorator is used to help simplify accessibility within the widget keyboard events.

more details
more detailswidget
Function

Utility method used for creating CSS animation/transition functions.

more details
more detailswidget
Boolean

Utility method used to determine if the directionality of the text of the document is right-to-left.

more details
more detailswidget
Function

This convenience decorator is used to help simplify localization of the widget.

more details
more detailswidget
Function

This convenience decorator marks a property for automatic rendering.

more details
more detailswidget

This convenience method is used to assign an HTMLElement DOM node reference to a variable.

more details
more detailswidget
Object

This convenience method is used to render the JSX in the widget.render() method.

more details
more detailswidget
Function

This convenience decorator helps dispatch view model events on the widget instance.

more details
more detailswidget

Method Details

accessibleHandler(){Function}

This convenience decorator is used to help simplify accessibility within the widget keyboard events. For example, it can be used to execute a method when the space or enter keys are pressed.

Returns:
Type Description
Function The property descriptor.
Example:
// .tsx syntax providing accessibility on a widget view model's reset method
@accessibleHandler()
@aliasOf("viewModel.reset")
reset: () => void;
cssTransition(type, className){Function}
Since: ArcGIS API for JavaScript 4.7

Utility method used for creating CSS animation/transition functions.

Parameters:
type String

The animation/transition type.

Possible Values:"enter"|"exit"

className String

The animation/transition class name.

Returns:
Type Description
Function The animation/transition function.
Example:
// .tsx syntax showing how to set up node enter/exit animations

render() {
  const content = this.visible ? (
    <div enterAnimation={cssTransition("enter", CSS.fadeIn)}
         exitAnimation={cssTransition("exit", CSS.fadeOut)}>
      I fade in and out.
    </div>
  ) : null;

  return (
    <div class={CSS.base}>{content}</div>
  );
}
isRTL(){Boolean}
Since: ArcGIS API for JavaScript 4.9

Utility method used to determine if the directionality of the text of the document is right-to-left.

Returns:
Type Description
Boolean true if the directionality of the text of the document is right-to-left.
messageBundle(bundleId){Function}
Since: ArcGIS API for JavaScript 4.18

This convenience decorator is used to help simplify localization of the widget. It is useful to decorate a property that will be automatically populated with the localized message bundled specified by the identifier bundleId. The property can then be used in the render() function to display the localized content.

When a widget is instantiated, all of the message bundles are loaded and assigned to their corresponding properties. The widget's postInitialize method is called, followed by the first call to render.

When the locale changes, all of the message bundles for all of the active widgets are reloaded and reassigned. The widgets then render simultaneously.

If functions are working with translated strings outside of a widget, use intl.fetchMessageBundle instead.

Note that the first call to render() only occurs after all the properties decorated with @messageBundle have been populated with their corresponding bundle.

Parameter:
bundleId String
optional

The bundle identifier passed to intl.fetchMessageBundle().

Returns:
Type Description
Function The property decorator.
See also:
Example:
// .tsx syntax to define a message bundle property
@property()
@renderable()
@messageBundle("my-application/MyBundle")
messages: { [key: string]: any };

render() {
  return (
    <div>{this.messages.myMessage}</div>
  );
}
renderable(propertyName){Function}

This convenience decorator marks a property for automatic rendering. It is useful when you want rendering to be scheduled whenever the decorated property changes. Many times this decorator is used in conjunction with the @property decorator. Rendering on deep properties is also supported by providing a path to a property deeper in the instance.

Parameter:
propertyName String|String[]
optional

Names of nested renderable properties.

Returns:
Type Description
Function The property decorator.
Examples:
// .tsx syntax setting a renderable property
@property()
@renderable()
name: string = "name";
// .tsx syntax setting a renderable nested property.
@property()
@renderable("viewModel.name.first")
viewModel: PersonViewModel;
storeNode(node)
Since: ArcGIS API for JavaScript 4.6

This convenience method is used to assign an HTMLElement DOM node reference to a variable. It does this by taking a HTMLElement passed from either the afterUpdate or afterCreate callbacks. In order to use this, the element must have a set data-node-ref attribute. In addition, it must also be bound to the widget instance, e.g. bind={this}.

Parameter:

The referenced DOM node.

See also:
Example:
// The storeNode function is called after the node is
// added to the DOM. Bind the node to the widget and
// pass in the node's root element name.

render() {
  return (
    <div afterCreate={storeNode} bind={this} data-node-ref="rootNode" />
  );
}
tsx(selector, properties, children){Object}
Since: ArcGIS API for JavaScript 4.4

This convenience method is used to render the JSX in the widget.render() method. It is required to import tsx even though it is not explicitly called.

Parameters:
selector String

The element to create.

properties Object
optional

The element's properties.

children Object
optional

The element's children.

Returns:
Type Description
Object The virtual node.
See also:
Example:
// .tsx syntax importing jsxfactory
import { tsx } from "esri/widgets/support/widget";
vmEvent(eventNames){Function}

This convenience decorator helps dispatch view model events on the widget instance.

Parameter:
eventNames String|String[]

The event names to re-dispatch.

Returns:
Type Description
Function The property decorator.
Example:
// .tsx syntax dispatching view model events
@property()
@vmEvent("search, search-clear, suggest")
viewModel: SearchViewModel;

Type Definitions

GoToOverride(view, goToParameters)

The following properties define a goTo override function.

Parameters:
Specification:

A reference to the MapView or SceneView where the navigation takes place.

goToParameters Object

The overriding target and optional parameters to pass to the MapView's goTo() or SceneView's goTo() method.

Specification:

The target location/viewpoint/extent to animate to.

optional

Options defining the animation, duration, and easing of the navigation.