registerRefreshHandler()

Registers a component’s refresh handler method to be included in a refresh process.

• contextElement—(Required) An HTMLElement representing the container that is participating in the refresh process.
• providerMethod—(Required) A Function identifying the callback method to be invoked when the refresh process begins. The handler callback is required to return a Promise that represents the refresh status of its particular element.

Returns a numeric refreshNode.handle value that uniquely identifies the node of this component on the refresh tree. You can pass this value to unregisterRefreshHandler() to remove this component’s refresh handler method from the refresh process.

Use the registerRefreshHandler() method to register components belonging to refresh-enabled views to be included in the refresh process.

To participate in a view refresh, a component registers a handler method. Use the registerRefreshHandler() method in the container’s connectedCallback() to register a handler method.

A handler method is invoked after a container has received RefreshEvent. Registered containers compose a "refresh tree" of registered refresh handlers, the order of which emulates the DOM.

Registered refresh methods in the refresh tree are invoked in a breadth-first order from the registered container’s node. This ensures that higher level (parent) handlers resolve before lower level (child) handlers are invoked.

The registered container callback method must:

• Return a Promise that resolves to a Boolean:
  • true if the component has completed operations for a refresh and the refresh process should continue down the refresh tree from this node
  • false to prevent the refresh process from continuing to child elements of this node
• Perform necessary view update operations in accordance with current state.
• Ensure data and state are resynchronized, if necessary.
• Show appropriate UI during the process, such as spinners or toasts.

You must unregister your component’s handler methods by calling unregisterRefreshHandler() in disconnectedCallback().

See Also

• RefreshView API Example
• Use RefreshView API