Core render middleware

The @dojo/framework/core/vdom module includes foundational middleware that is useful across the majority of Dojo applications. These are mainly useful when building other custom middleware (they underpin the additional middleware offered by the framework), but can occasionally be useful in general widget development.

invalidator

The most important middleware which provides a hook into a widget’s invalidation lifecycle. Calling invalidator() will queue the widget for rendering during the next scheduled render.

API:

import invalidator from '@dojo/framework/core/vdom';

• invalidator()
  • Marks the consuming widget as invalid and requiring a re-render.

node

Provides widgets access to their underlying DOM nodes, identified by node keys. When a valid DOM node is requested but unavailable, Dojo will re-render the widget as soon as the DOM node becomes available.

API:

import node from '@dojo/framework/core/vdom';

• node.get(key: string | number): HTMLElement | null
  • Returns the widget’s specified DOM element, identified by the node’s key property. Returns null if the specified DOM element does not exist for the current widget.

diffProperty

Allows widgets fine-grained control over difference detection by registering their own diff function for a specified property. The function will be called by the framework when attempting to re-render a widget, in order to determine if any changes have been made that require a full re-render to take place. If no differences are detected across a widget’s properties set, the update is skipped and any existing DOM nodes remain as-is.

Writing custom diff functions is typically coupled with use of the invalidator middleware to flag the current widget as invalid when a difference in property values requires the widget’s DOM nodes to be updated.

Note: Only a single diff function can be registered for a given property during the lifetime of a composing widget or middleware, after which subsequent calls will be ignored. By default the rendering engine uses an algorithm that shallowly diffs objects and arrays, ignores functions, and equality checks all other property types. Setting a custom diff function overrides Dojo’s default difference detection strategy for the property.

API:

import diffProperty from '@dojo/framework/core/vdom';

• diffProperty(propertyName: string, diff: (current: any, next: any) => void)
  • Registers the specified diff function that is called to determine if any differences exist between the current and next values of the widget’s propertyName property.

destroy

Assigns a function that is called on widget destruction, allowing any required resource teardown to take place.

Note: destroy() can only be called once for each composing widget or middleware, after which further calls will be ignored. For advanced scenarios that need to conditionally add handles for execution when a widget is removed, a single destroy function should be registered that can keep track of and iteratively destroy all necessary resources.

API:

import destroy from '@dojo/framework/core/vdom';

• destroy(destroyFunction: () => void)
  • Sets the destroyFunction that will be called when the current widget is destroyed. Setting a function will override any destroy function previously set for the widget.

getRegistry

Provides access to the widget’s own Registry instance, as well as the root application Registry if required, via a handler interface.

Note: The registry is an advanced concept not typically required when writing Dojo applications. It is mainly used internally by the framework to implement more advanced user-facing functionality such as Dojo stores.

API:

import getRegistry from '@dojo/framework/core/vdom';

• getRegistry(): RegistryHandler | null
  • Returns the RegistryHandler for the current widget, or null if the widget has not yet been fully initialized.

defer

Allows widgets to pause and resume their rendering logic; useful when short-circuiting rendering until certain conditions are met.

API:

import defer from '@dojo/framework/core/vdom';

• defer.pause()
  • Pauses further rendering of the current widget until flagged otherwise.
• defer.resume()
  • Resumes widget rendering.