widget | References | ArcGIS Maps SDK for JavaScript

import { accessibleHandler, messageBundle, vmEvent, isRTL, cssTransition } from "@arcgis/core/widgets/support/widget.js";

Since: ArcGIS Maps SDK for JavaScript 4.2

This module contains widget helpers.

See also

Functions

Name	Return Type	Object
`accessibleHandler`	`PropertyDecorator`
`messageBundle`	`PropertyDecorator`
`vmEvent`	`PropertyDecorator`
`isRTL`	`boolean`
`cssTransition`	`any`
`isActivationKey`	`boolean`
`storeNode`	`void`
`tsx`	`any`

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.

Signature: accessibleHandler (): PropertyDecorator

Returns: PropertyDecorator
The property descriptor.

Example

// .tsx syntax providing accessibility on a widget method
@accessibleHandler()
reset: () => void;

messageBundle

Function

Since: ArcGIS Maps SDK 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 Widget.postInitialize() method is called, followed by the first call to Widget.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 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.

See also

Signature: messageBundle (bundleId: string): PropertyDecorator

Parameters

Parameter	Type	Description	Required
bundleId	`string`	The bundle identifier passed to fetchMessageBundle().

Returns: PropertyDecorator
The property decorator.

Example

// .tsx syntax to define a message bundle property
@property()
@messageBundle("my-application/MyBundle")
messages: { [key: string]: any };

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

vmEvent

Function

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

Signature: vmEvent (eventNames: string | string[]): PropertyDecorator

Parameters

Parameter	Type	Description	Required
eventNames	`string \| string[]`	The event names to re-dispatch.

Returns: PropertyDecorator
The property decorator.

Example

// .tsx syntax dispatching view model events
@property()
@vmEvent("search, search-clear, suggest")
viewModel: SearchViewModel;

isRTL

Function

Since: ArcGIS Maps SDK for JavaScript 4.9

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

Signature: isRTL (): boolean

Returns: boolean
true if the directionality of the text of the document is right-to-left.

cssTransition

Function

Since: ArcGIS Maps SDK for JavaScript 4.7

Utility method used for creating CSS animation/transition functions.

Signature: cssTransition (type: "enter" | "exit", className: string): any

Parameters

Parameter	Type	Description	Required
type	`"enter" \| "exit"`	The animation/transition type.
className	`string`	The animation/transition class name.

Returns: any
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>
  );
}

isActivationKey

Function

Since: ArcGIS Maps SDK for JavaScript 4.19

Utility method used to determine if a pressed key should activate button behavior. If the returned KeyboardEvent.key is either Enter or a space (" "), it returns true.

See also

developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key

Signature: isActivationKey (key: KeyboardEvent["key"]): boolean

Parameters

Parameter	Type	Description	Required
key	`KeyboardEvent["key"]`	The KeyboardEvent.key

Returns: boolean
Indicates whether the pressed keyboard key is either Enter or a space (" ").

storeNode

Function

Type parameters: <T extends Widget>

Since: ArcGIS Maps SDK 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}.

Signature: storeNode <T extends Widget>(node: Element): void

Parameters

Parameter	Type	Description	Required
node	`Element`	The referenced DOM node.

Returns: void

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

Function

Since: ArcGIS Maps SDK 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.

Signature: tsx (tagNameOrComponent: string | Function, properties: any | null | undefined, ...children: any[]): any

Parameters

Parameter	Type	Description
tagNameOrComponent	`string \| Function`	The element to create.
properties	`any \| null \| undefined`	The element's properties.
children	`any[]`	The element's children.

Returns: any
The virtual node.

Example

// .tsx syntax importing jsxfactory
import { tsx } from "@arcgis/core/widgets/support/widget.js";