Announcing Dojo 7 Widgets

New Dojo Widgets

The new Card widget provides a simple and consistently styled container for content and actions. It uses the new child renderer pattern, accepting content for different sections in a typed child object and rendering them in the appropriate location with appropriate styling.

src/MyCard.tsx

import { create, tsx } from '@dojo/framework/core/vdom';
import Card from '@dojo/widgets/card';
import Button from '@dojo/widgets/button';
import Icon from '@dojo/widgets/icon';
const mediaSrc = require('./img/card-photo.jpg');

const factory = create();

export default factory(function CardWithMediaContent() {
	return (
		<div styles={{ width: '400px' }}>
			<Card onAction={() => {}} mediaSrc={mediaSrc} title="Hello, World" subtitle="A pretty picture">
				{{
					header: <div>Header Content</div>,
					content: <span>Travel the world today.</span>,
					actionButtons: (
						<virtual>
							<Button>Read</Button>
							<Button>Bookmark</Button>
						</virtual>
					),
					actionIcons: (
						<virtual>
							<Icon type="secureIcon" />
							<Icon type="downIcon" />
							<Icon type="upIcon" />
						</virtual>
					)
				}}
			</Card>
		</div>
	);
});

The PasswordInput widget is one of several new specialized widget variants, automatically handling validation state and messaging internally saving development time and improving productivity.

src/MyPasswordInput.tsx

import { create, tsx } from '@dojo/framework/core/vdom';
import PasswordInput from '@dojo/widgets/password-input';

const factory = create();

export default factory(function Basic() {
	return (
		<PasswordInput
			rules={{
				length: {
					min: 4
				},
				contains: {
					atLeast: 2,
					uppercase: 1,
					specialCharacters: 1,
					numbers: 1
				}
			}}
		>
			{{ label: 'Enter Password' }}
		</PasswordInput>
	);
});

The Form widget provides an opinionated way to use a group of inputs in a form, featuring a custom renderer for defining the form’s inputs and providing a middleware for custom functionality.

src/MyForm.tsx

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

import TextInput from '@dojo/widgets/text-input';
import Form from '@dojo/widgets/form';
import { FormMiddleware } from '@dojo/widgets/form/middleware';

const icache = createICacheMiddleware<{
	basic?: Partial<Fields>;
}>();

const factory = create({ icache });

interface Fields {
	firstName?: string;
	middleName?: string;
	lastName?: string;
	email?: string;
}

const App = factory(function({ middleware: { icache } }) {
	const results = icache.get('basic');

	return (
		<virtual>
			<Form name="basicForm" onValue={(values) => icache.set('basic', { ...icache.get('basic'), ...values })}>
				{({ field }: FormMiddleware<Fields>) => {
					const firstName = field('firstName');
					const middleName = field('middleName');
					const lastName = field('lastName');
					const email = field('email');

					return (
						<virtual>
							<TextInput
								key="firstName"
								placeholder="Enter first name"
								initialValue={firstName.value()}
								onValue={firstName.value}
							>
								{{ label: 'First Name' }}
							</TextInput>
							<TextInput
								key="middleName"
								placeholder="Enter a middle name"
								initialValue={middleName.value()}
								onValue={middleName.value}
							>
								{{ label: 'Middle Name' }}
							</TextInput>
							<TextInput
								key="lastName"
								placeholder="Enter a last name"
								initialValue={lastName.value()}
								onValue={lastName.value}
							>
								{{ label: 'Last Name' }}
							</TextInput>
							<TextInput
								key="email"
								placeholder="Enter an email address"
								initialValue={email.value()}
								onValue={email.value}
								type="email"
							>
								{{ label: 'Email' }}
							</TextInput>
						</virtual>
					);
				}}
			</Form>
			{results && (
				<div key="onValueResults">
					<h2>onValue Results</h2>
					<ul>
						<li>First Name: {results.firstName}</li>
						<li>Middle Name: {results.middleName}</li>
						<li>Last Name: {results.lastName}</li>
						<li>Email: {results.email}</li>
					</ul>
				</div>
			)}
		</virtual>
	);
});

export default App;

View the new Dojo widgets in action on our brand new widget documentation site built using @dojo/parade.

Standardization of Dojo Widget property patterns

This release brings more consistency to property patterns throughout the Dojo Widgets library. The result is a reduced learning curve and improved developer experience. Common widget properties are now aligned across all widgets, ensuring familiarity for end users.

Partial control of Dojo Widgets

One goal with Dojo 7 is to make widgets work out-of-the-box wherever possible, without extra boilerplate for controlling the widget state. As a result, many widgets have been updated to use the icache middleware and now maintain their own state. This is accompanied by a standardized initialValue property that can control the value but does not need to be set each time the onValue callback is called. These widgets can still optionally get controlled using the value and onValue properties for backward compatibility, but we believe this new pattern provides an improvement to the developer experience.

Basic controlled Slider widget, using value and onValue:

src/MyControlledSlider

import icache from '@dojo/framework/core/middleware/icache';
import { create, tsx } from '@dojo/framework/core/vdom';
import Slider from '@dojo/widgets/slider';

const factory = create({ icache });

export default factory(function Controlled({ middleware: { icache } }) {
	const value = icache.getOrSet('value', 50);

	return (
		<Slider
			min={0}
			max={100}
			value={value}
			onValue={(value) => {
				icache.set('value', value);
			}}
		/>
	);
});

Basic Slider widget with initialValue:

src/MySlider

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

const factory = create({});

export default factory(function Basic({}) {
	return <Slider min={0} max={100} />;
});