Core render middleware

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.

An additional use for diffProperty is to be able to return a value that will be available from the widget properties. A value that is returned from the callback is used to replace the corresponding value on the widget's properties.

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, properties: () => WidgetProperties (current: WidgetProperties, next: WidgetProperties) => void | WidgetProperties[propertyName])
  • 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. The function uses the properties function to determine the available properties and the typings of the callback, both the parameters and the return value.

Example:

src/customMiddleware.tsx

import { create, diffProperty } from '@dojo/framework/core/vdom';

const factory = create({ diffProperty }).properties<{ foo?: string }>;

export const customMiddleware = factory(({ properties, middleware: { diffProperty } }) => {
    diffProperty('foo', properties, (current, next) => {
        if (!next.foo) {
            return 'default foo';
        }
    });
    // The rest of the custom middleware that defines the API
});

## `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:**

```ts
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.