Building a simple app in Dojo

dojo app

I’ve been thinking about how I could demonstrate building a basic Dojo application beyond a hello world app or a Todo app. There are some really good samples in the dojo/examples repo. Then I came across this react application for searching for emojis and who doesn’t have to search for emojis regularly, so I knew I found my demo. It also helps that the dojo template on Code Sandbox now uses TSX/JSX as the default.

Because the dojo template app uses JSX by default, it made this sample almost a complete one to one of the react sample. I won’t go into detail of this application line by line, but I do want to cover some core concepts it shows.

Get Meta

Meta in Dojo is meta information about your widget. Pretty meta right?

When you build Dojo widgets, you never touch the output HTML of your application. There is no widget method to get a reference to the DOM. This prevents you from inadvertently changing a DOM element that is referenced by Dojos virtual DOM engine, which would be bad. So don’t get too crazy here. But there are valid reasons for wanting to access a DOM node in your application. In the case of my emoji application, I am using a small library called clipboardjs to let me copy emojis to my clipboard from my application. This library requires I pass a DOM node it will use to copy data to the clipboard.

You can get this information in Dojo is via a meta. Dojo provides some metas out of the box for you, like Dimensions, Animations, Intersection, and more. You can implement your own custom meta to access DOM nodes using `@dojo/framework/widget-core/meta/Base`.

// src/widgets/ElementMeta.ts
import { Base as MetaBase } from "@dojo/framework/widget-core/meta/Base";

class ElementMeta extends MetaBase {
  get(key: string): Element {
    const node = this.getNode(key);
    return node as Element;
  }
}

export default ElementMeta;

The meta implements a get() method that will get the DOM node via a given key and return that DOM node. Now in my application, where I use clipboardjs, I can use my meta in combination with the this.meta() method of the Widget to get a referenced DOM node.

// src/widgets/EmojiResultsRow.tsx
import { tsx } from "@dojo/framework/widget-core/tsx";
import { WidgetBase } from "@dojo/framework/widget-core/WidgetBase";

import * as css from "./styles/EmojiResultsRow.m.css";

import ElementMeta from "./ElementMeta";
import * as Clipboard from "clipboard";

export interface EmojiResultsRowProperties {
  title: string;
  symbol: string;
}

export class EmojiResultsRow extends WidgetBase<EmojiResultsRowProperties> {
  clipboard: Clipboard = null;

  onAttach() {
    // use my meta to get a DOM node
    const element = this.meta(ElementMeta).get(this.properties.title);
    this.clipboard = new Clipboard(element);
  }
  onDetach() {
    this.clipboard.destroy();
  }

  protected render() {
    const { title, symbol } = this.properties;
    const codePointHex = symbol.codePointAt(0).toString(16);
    const src = `//cdn.jsdelivr.net/emojione/assets/png/${codePointHex}.png`;
    // provide a `key` property to my widget element to
    // reference with my meta
    return (
      <div
        key={title}
        classes={[css.root, "copy-to-clipboard"]}
        data-clipboard-text={symbol}
      >
        <img alt={title} src={src} />
        <span classes={[css.title]}>{title}</span>
        <span classes={[css.info]}>Click to copy emoji</span>
      </div>
    );
  }
}

export default EmojiResultsRow;

Now I am able to use my custom meta to get a DOM node created by my widget. This makes access to output DOM nodes flexible, but also protects me from shooting myself in the foot unintentionally. If I break my DOM, it is totally my fault now.

Core Widgets

Dojo provides a suite of widgets you can use for your own applications. This includes items like TimePicker, Select and layout widgets. For my application, I’m interested in having an input that I can use for search. Every time I update the input element, I want to filter the list of emojis shown in my application. So I’m going to wrap a TextInput widget so I can manage some local state and pass the value of the input to a filter method.

// src/widgets/SearchInput.tsx
...
export class SearchInput extends WidgetBase<SearchInputProperties> {
  @watch() private searchValue = "";

  private onChange(value) {
    if (!value) {
      return;
    }
    this.searchValue = value;
    const { handleChange } = this.properties;
    handleChange(value);
  }

  protected render() {
    return (
      <div classes={[css.root]}>
        <div>
          <TextInput
            placeholder="Search for emoji"
            value={this.searchValue}
            onInput={this.onChange}
          />
        </div>
      </div>
    );
  }
}

Yes, I could have used a regular <input type="text" /> here, but the TextInput is very convenient as it already has an onInput method I can use that passes the value of the input directly, and not an event I would need to do event.target.value which, because I am lazy, I can really appreciate. Then I would need to use a keyup event, and maybe do some handling for different keys to on whether I want to get my value and why hassle with all that when Dojo provides a nice way to do it already.

I am also taking advantage of the @watch decorator to manage local state in my widget. I talked about this method in more detail here. This makes it very simple to manage the value of my input at all times.

You can see the full application in action here.

You can see that building applications in Dojo provides some safety and flexibility for you to piece together everything you need to build solid, and awesome applications. Dojo isn’t just a toolkit anymore, it’s a full blown framework and has a lot to offer!

Watch for property changes in Widgets

dojo watch decorator

We’ve seen how you can manage more complex state in your Dojo applications with Containers, but with the release of Dojo 4 we now have access to a new @watch decorator.

This very useful for managing the internal state of your widgets, because you no longer have to concern yourself with having to call a widgets invalidate() method if you don’t want to.

For example, let’s say that I want to have a simple clock widget in my application that is just going to display the current time. For demo purposes, I’ll display the time up to the second.

I can create a Clock widget that will do exactly that.

class Clock extends WidgetBase {
  // use watch decorator so that any updates
  // to this property will now call the
  // internal invalidate() method and
  // rerender my widget
  @watch() private _currentTime = new Date();

  // a widget lifecycle method that is called
  // when a widget is added to the DOM
  onAttach() {
    // update time every second
    setInterval(() => {
      this._currentTime = new Date();
    }, 1000);
  }

  protected render() {
    return v("h1", { classes: css.root }, [
      `Time: ${this._currentTime.toLocaleTimeString()}!`
    ]);
  }
}

As you can see, this greatly simplifies my widget so that I can just update my internal state without having to worry about invalidating my widget. This is powerful stuff!

Here is a live demo of this application.

There have been some other great updates to Dojo 4 such as a simplified render method to mount Dojo widgets and much more!

Dojo Containers

Once you start building applications that begin to compose multiple widgets and you are trying to manage state across those widgets, you might want to start looking at Dojo Containers. Containers allow you to inject values into widget properties, without having to import state directly into your widget.

To do this, Dojo provides a higher order component, similar to what you might use with React. That HOC is located in the @dojo/framework/widget-core/Container.

Let’s say that you wanted to work with a streaming API and update your widget when the stream returns new data. We want to display this data in a simple list.

// src/widgets/Items.ts
export class Items extends WidgetBase<ItemsProperties> {
  protected render() {
    const { items } = this.properties;
    return v(
      "ul",
      { classes: css.root },
      items.map((x, idx) =>
        v("li", { innerHTML: x.name, key: `${x.name}-${idx}` })
      )
    );
  }
}

This widget has an items array in the properties. You could bind this widget directly a data store and update the widget when new data comes in, but again, maybe we want that data available in the parent widget, or other widgets in use.

Let’s create a parent Application container that will render this widget.

// src/containers/AppContainer.ts
class AppContainer extends WidgetBase<ItemsProperties> {
  protected render() {
    return v("div", {}, [w(Items, { items: this.properties.items })]);
  }
}

This particular container is not doing much other than passing its properties to the child Items widget.

To use the Dojo Container, we need to create a getProperties function that defines the properties returned to the Container.

// src/containers/AppContainer.ts
function getProperties(inject: Context, properties: any) {
  const { items } = inject;
  return { items };
}

Now we can wrap our AppContainer in the Dojo Container.

// src/containers/AppContainer.ts
export default Container(AppContainer, "state", { getProperties });

In this case "state" is the name I’m providing for my context, which I refer to as my injector since it allows me to inject values into my widgets.

At this point, you have an option for how to manage your state. You can use Dojo stores or you can create a class that accepts an invalidator and you can use this invalidator to let the higher order component know that state has changed and it will pass it to the widget that it has wrapped.

For now, let’s go with a class that takes an invalidator and call it a context for our container. We can cover Dojo stores in another post.

// src/context.ts
export default class Context {
  private _items: Item[];

  private _invalidator: () => void;

  constructor(invalidator: () => {}, items: Item[] = []) {
    this._items = items;
    this._invalidator = invalidator;
    // subscribe to updates from our stream
    stream.subscribe((a: Item) => {
      this._addItem(a);
    });
  }

  get items(): Item[] {
    return this._items;
  }

  private _addItem(item: Item) {
    this._items = [...this._items, item];
    // call the invalidator to update wrapped container
    this._invalidator();
  }
}

It’s in this Context that I am subscribing to my data stream and updating the items array when new data is streamed in.

Ok, let’s tie it all together in our main.ts that kick starts the whole application.

// src/main.ts
const registry = new Registry();
// the `defineInjector` will provider the invalidator
registry.defineInjector("state", (invalidator: () => any) => {
  // create a new context and return it
  const context = new Context(invalidator);
  return () => context;
});

const Projector = ProjectorMixin(AppContainer);
const projector = new Projector();
// pass the registry to the projector
projector.setProperties({ registry });

projector.append();

When the Registry is passed to the projector, it will make sure everything is wired up as needed.

This may seem like a few steps, but it makes state management very flexible in your widgets without having to bind widgets to a data source, which makes them incredibly reusable.

You could create containers for each individual widget in your application and manage their state independently, this would be very powerful!

You can see a sample of this application above here:

Be sure to subscribe to the newsletter and stay up to date with the latest content!

Web Components with Dojo

We previously saw how we can create a custom date picker with Dojo. If building custom widgets with Dojo wasn’t cool enough, one of the features that Dojo provides that set it apart is the ability to export your custom widgets to Web Components.

This is incredibly useful because you could create a encapsulated widget in Dojo, including all business logic and now reuse this component anywhere you want.

You can review the documentation on how to export widgets to web components here.

Firs thing you need to do is npm install @dojo/cli-build-widget in our DatePicker project. Once that is done, we just need to make some updates to the widget in our application to encapsulate some styles and other small bits.

First, let’s update src/widgets/styles/datepicker.m.css.

@import url("https://fonts.googleapis.com/css?family=Roboto");
@import url("https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css");

.root {
    font-family: "Roboto", sans-serif;
  text-align: center;
  padding: 0.5em;
  color: #000;
}

input {
  font-size: 1.2em;
}

button {
  color: #fff;
  background: rgb(16, 184, 10);
  padding: 1em;
}

.hidden {
  display: none;
}

.calendarcontainer {
  background: #fff;
}

Now we have included all the styling for our widget, including the required fonts into the css for the widget.

Next, we need to add the customElement decorator to our widget to define the tags and any attribute and event information.

// src/widgets/DatePicker.ts

import { v, w } from '@dojo/framework/widget-core/d';
import { WidgetBase } from '@dojo/framework/widget-core/WidgetBase';
import Calendar from '@dojo/widgets/calendar';
import EnhancedTextInput from '@dojo/widgets/enhanced-text-input';
// Used to define web component element tag name
import customElement from '@dojo/framework/widget-core/decorators/customElement';

import * as css from './styles/datePicker.m.css';

...

@customElement<DatePickerProperties>({
  tag: 'date-picker' // custom element can be defined as <date-picker></date-picker>
})
export class DatePicker extends WidgetBase<DatePickerProperties> {
  ...
}

export default DatePicker;

Now the last thing we need to do is update the .dojorc with a "build-widget" section.

{
  "build-widget": {
    "elements": ["src/widgets/DatePicker"]
  }
}

With all these changes in place, you should be able to now run dojo build widget --mode dist.

To test that our web component works correctly, we can create a new HTML file that uses it.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <link rel="stylesheet" href="./output/dist/date-picker/date-picker-1.0.0.css">
  <script src="./output/dist/date-picker/date-picker-1.0.0.js"></script>
  <title>Date Picker Demo</title>
</head>
<body>
  <!-- Custom Element -->
  <date-picker></date-picker>
</body>
</html>

You should see a page with your date picker component now!

You can find the source code here.

And there you go, we just exported a Dojo widget that we previously built into a reusable web component. Try it out with your own components and feel confident that you can build awesome widgets that you can use anywhere!

Creating a DatePicker with Dojo

I recently talked about getting started with the @dojo/cli. This time around, I wanted to dive a little deeper and talk about using some of the provided widgets with Dojo to build a useful DatePicker widget.

This sample covers some pretty interesting concepts of Dojo, including widget composition, styling, date formatting with internationalization, and more.

Before we start, delete the default HelloWorld.ts and widget css file that came with the @dojo/cli output.

Create the widget

Our first step is to install the widgets library.

npm install --save @dojo/widgets

Now we can create a DatePicker.ts in the src/widgets folder.

// src/widgets/DatePicker.ts
import { v, w } from '@dojo/framework/widget-core/d';
import { WidgetBase } from '@dojo/framework/widget-core/WidgetBase';
import Calendar from '@dojo/widgets/calendar';

interface DatePickerProperties {
  selectedDate: Date;
}

interface DatePickerState {
  month?: number;
  year?: number;
  selectedDate?: Date;
}

export class DatePicker extends WidgetBase<DatePickerProperties> {
  state: DatePickerState = {
    month: 1,
    selectedDate: this.properties.selectedDate,
    year: 2018
  };

  protected render() {
    return v('div', [
      v(
        'section',
        {},
        [
          w(Calendar, {
            month: this.state.month,
            selectedDate: this.state.selectedDate,
            year: this.state.year,
            onMonthChange: (month: number) => {
              this.setState({ month: month });
            },
            onYearChange: (year: number) => {
              this.setState({ year: year });
            },
            onDateSelect: (date: Date) => {
              this.setState({ selectedDate: date });
            }
          })
        ]
      )
    ]);
  }

  // helper method to set the state
  protected setState(state: DatePickerState) {
    this.state = { ...this.state, ...state };
    this.invalidate();
  }
}

export default DatePicker;

In this widget, we are going to make use of the Calendar widget we get in @dojo/widgets.

This widget will have some simple state properties related to picking a date.

state = {
  month: 1,
  selectedDate: this.properties.selectedDate,
  year: 2018
};

You may also notice the helper method I added to help me update the state of my widget.

// helper method to set the state
protected setState(state: any) {
  this.state = { ...this.state, ...state };
  this.invalidate();
}

This will update the state object of my widget and call a this.invalidate() method that will update my widget based on the new state changes. This invalidate() method will be replaced by a @watch() decorator on properties in a future version of Dojo to simplify updates. Other than that, I pretty much followed the Calendar example provided in the documentation.

But let’s make things a little more interesting. I want an input box that will display my selected date. For this, I’m going to use the EnhancedTextInput.

w(EnhancedTextInput, {
  addonAfter: [
    v(
      'button',
      {},
      [
        v('i', {
          classes: [
            'fa',
            'fa-chevron-down'
          ]
        })
      ]
    )
  ],
  label: 'Pick a date',
  value: this.state.selectedDate
})

I wanted to use the EnhancedTextInput because it lets me add a button to it using the addonAfter contents. I found this to be very useful! You’ll notice I’m using Font Awesome to help me out here. Since we’re at it, let’s talk about some styling.

CSS

Create a src/widgets/styles/datepicker.m.css file.

/* src/widgets/styles/datepicker.m.css */
.root {
    text-align: center;
    padding: 0.5em;
    color: #000;
}

.hidden {
  display: none;
}

.calendarcontainer {
  background: #fff;
}

Notice I added a hidden class. We’ll use that in a moment. But first, let’s modify the src/main.css file.

/* src/main.css */
@import url('https://fonts.googleapis.com/css?family=Roboto');
@import url('https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css');

body {
    font-family: 'Roboto', sans-serif;
    color: #fff;
    background: #1d1f20;
}
input {
  font-size: 1.2em;
}

button {
  color: #fff;
  background: rgb(16, 184, 10);
  padding: 1em;
}

Here, I provide some styling for my input, my buttons and some typography.

With the css ready for the application, we can start making the widget a little more interactive.

Interactivity

Part of the functionality of the DatePicker is to have the calendar open and close on a button click. We can add a visible property to our state object.

state = {
  month: 1,
  selectedDate: this.properties.selectedDate,
  year: 2018,
  visible: false
};

Lets modify the button to update the visible state.

v(
  'button',
  {
    onclick: () => {
      this.setState({ visible: !this.state.visible });
    }
  },
  [
    v('i', {
      classes: [
        'fa',
        this.state.visible ? 'fa-chevron-up' : 'fa-chevron-down'
      ]
    })
  ]
)

Now onclick will update the visible state and that will determine the button icon. We’ll also update the container for the Calendar so it can toggle the visibility.

v(
  'section',
  {
    classes: [this.state.visible ? '' : css.hidden, css.calendarcontainer]
  },
  [
    w(Calendar, {
      ...
    })
  ]
)

AWESOME!! We now have a fully interactive DatePicker. But we’re not updating the value of the EnhancedTextInput with the selected date. But we can’t just show the date any normal way. We want our DatePicker to support various locales. We can do with @dojo/framework/i18n.

Internationalization

I’m not going to get in to detail on using i18n, it’s incredibly powerful. But we’re going to use it to support formatting our dates accordingly.

First, we need cldr-data for our application to use.

npm install --save cldr-data

Next, update the .dojorc file to use it.

{
    "build-app": {
        "locale": "en",
        "supportedLocales": [ "es", "fr", "hi", "ar", "ja" ],
        "cldrPaths": [
            "cldr-data/main/{locale}/ca-gregorian",
            "cldr-data/main/{locale}/dateFields",
            "cldr-data/main/{locale}/numbers",
            "cldr-data/main/{locale}/timeZoneNames",
            "cldr-data/supplemental/likelySubtags",
            "cldr-data/supplemental/numberingSystems",
            "cldr-data/supplemental/ordinals",
            "cldr-data/supplemental/plurals",
            "cldr-data/supplemental/timeData",
            "cldr-data/supplemental/weekData"
        ]
    },
    "test-intern": {},
    "create-app": {}
}

Now we can support various locales for working with dates.

// src/widgets/DatePicker.ts
import { formatDate } from '@dojo/framework/i18n/date';

...

w(EnhancedTextInput, {
  addonAfter: [
    ...
  ],
  label: 'Pick a date',
  value: formatDate(
    this.state.selectedDate || this.properties.selectedDate,
    { date: 'short' }
  )
})

We are going to use the formatDate() method to format our date in the EnhancedTextInput accordingly. I could take this a step further and provide the Pick a date text in various locales, which isn’t difficult to do. You can read more about supporting various languages here.

Put it all together

Now we can add the DatePicker to our main application.

// src/main.ts
...

class App extends WidgetBase {
  protected render() {
    return v('div', [
      w(DatePicker, { selectedDate: new Date() })
    ]);
  }
}
...

And voila! You have a finished and useable DatePicker with styling and internationalization. I’m sure you could make this look better than I did, I never claimed to be a good designer, I just know enough to get things done.

You can see the source code for the complete application on github.

I also want to point out that you can try out some Dojo in codesandbox, although I have had some issues with i18n in the sandbox, which is why this sample isn’t provided there.

Now you can go forward and make some awesome widgets of your own!

Be sure to subscribe to the newsletter and stay up to date with the latest content!