Rendering widgets

TSX-enabled applications

TSX-enabled projects can easily get scaffolded via the dojo create app --tsx CLI command.

For Dojo projects that were not scaffolded in this way, TSX can be enabled with the following additions to the project's TypeScript config:

./tsconfig.json

{
	"compilerOptions": {
		"jsx": "react",
		"jsxFactory": "tsx"
	},
	"include": ["./src/**/*.ts", "./src/**/*.tsx", "./tests/**/*.ts", "./tests/**/*.tsx"]
}

TSX widget example

Widgets with a .tsx file extension can output TSX from their render function by simply importing the tsx function from the @dojo/framework/core/vdom module:

src/widgets/MyTsxWidget.tsx

Function-based variant:

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

const factory = create();

export default factory(function MyTsxWidget() {
	return <div>Hello from a TSX widget!</div>;
});

Class-based variant:

import WidgetBase from '@dojo/framework/core/WidgetBase';
import { tsx } from '@dojo/framework/core/vdom';

export default class MyTsxWidget extends WidgetBase {
	protected render() {
		return <div>Hello from a TSX widget!</div>;
	}
}

Widgets that need to return multiple top-level TSX nodes can wrap them in a <virtual> container element. This is a clearer option than returning an array of nodes as it allows for more natural automated code formatting within TSX blocks. For example:

src/widgets/MyTsxWidget.tsx

Function-based variant:

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

const factory = create();

export default factory(function MyTsxWidget() {
	return (
		<virtual>
			<div>First top-level widget element</div>
			<div>Second top-level widget element</div>
		</virtual>
	);
});

VDOM node types

Dojo recognizes two types of nodes within its VDOM:

• VNodes, or Virtual Nodes, which are virtual representations of concrete DOM elements, and serve as the lowest-level rendering output for all Dojo applications.
• WNodes, or Widget Nodes, which tie Dojo widgets into the VDOM hierarchy.

Both VNodes and WNodes are considered subtypes of DNodes within Dojo's virtual DOM, but applications don't typically deal with DNodes in their abstract sense. Using TSX syntax is also preferred as it allows applications to render both virtual node types with uniform syntax.

Instantiating VDOM nodes

If TSX output is not desired, widgets can import one or both of the v() and w() primitives provided by the @dojo/framework/core/vdom module. These create VNodes and WNodes, respectively, and can be used as part of the return value from a widget's render function. Their signatures, in abstract terms, are:

• v(tagName | VNode, properties?, children?):
• w(Widget | constructor, properties, children?)

Virtual nodes example

The following sample widget includes a more typical render function that returns a VNode. It has an intended structural representation of a simple div DOM element which includes a text child node:

src/widgets/MyWidget.ts

Function-based variant:

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

const factory = create();

export default factory(function MyWidget() {
	return v('div', ['Hello, Dojo!']);
});

Class-based variant:

import WidgetBase from '@dojo/framework/core/WidgetBase';
import { v } from '@dojo/framework/core/vdom';

export default class MyWidget extends WidgetBase {
	protected render() {
		return v('div', ['Hello, Dojo!']);
	}
}

Composition example

Similarly, widgets can compose one another using the w() method, and also output several nodes of both types to form a more complex structural hierarchy:

src/widgets/MyComposingWidget.ts

Function-based variant:

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

const factory = create();

import MyWidget from './MyWidget';

export default factory(function MyComposingWidget() {
	return v('div', ['This widget outputs several virtual nodes in a hierarchy', w(MyWidget, {})]);
});

Class-based variant:

import WidgetBase from '@dojo/framework/core/WidgetBase';
import { v, w } from '@dojo/framework/core/vdom';

import MyWidget from './MyWidget';

export default class MyComposingWidget extends WidgetBase {
	protected render() {
		return v('div', ['This widget outputs several virtual nodes in a hierarchy', w(MyWidget, {})]);
	}
}

MountOptions properties

The Renderer.mount() method accepts an optional MountOptions argument that configures how the mount operation gets performed.

For example, to mount a Dojo application within a specific DOM element other than document.body:

src/index.html

<!DOCTYPE html>
<html lang="en-us">
	<body>
		<div>This div is outside the mounted Dojo application.</div>
		<div id="my-dojo-app">This div contains the mounted Dojo application.</div>
	</body>
</html>

src/main.tsx

import renderer, { tsx } from '@dojo/framework/core/vdom';

import MyComposingWidget from './widgets/MyComposingWidget';

const dojoAppRootElement = document.getElementById('my-dojo-app') || undefined;
const r = renderer(() => <MyComposingWidget />);
r.mount({ domNode: dojoAppRootElement });

dom() API

• dom({ node, attrs = {}, props = {}, on = {}, diffType = 'none', onAttach })

External DOM node change detection

External nodes added through dom() are a step removed from regular virtual DOM nodes as it is possible for them get managed outside of the Dojo application. This means Dojo cannot use the VNode's properties as the master state for the element, but instead must rely on the underlying JavaScript properties and HTML attributes on the DOM node itself.

dom() accepts a diffType property that allows users to specify a property change detection strategy for the wrapped node. A particular strategy given the wrapped node's intended usage can help Dojo to determine if a property or attribute has changed, and therefore needs to be applied to the wrapped DOM node. The default strategy is none, meaning Dojo will simply add the wrapped DOM element as-is within the application's output on every render cycle.

Note: All strategies use the events from the previous VNode to ensure that they are correctly removed and applied upon each render.

Available dom() change detection strategies: