Your first Dojo application

Overview

In this tutorial, you will learn how to the create your first Dojo application and use it to print a simple message in the browser.

Prerequisites

You can open the tutorial on codesandbox.io or download the demo project and run npm install to get started.

The @dojo/cli command line tool should be installed globally. Refer to the Dojo local installation article for more information.

You also need to be familiar with TypeScript as Dojo uses it extensively.

Starting the development server

Build and run the application.

Before we start making changes, let’s start the application with the development server so that we can observe the impact of our changes. Run the following command in the application’s root directory:

dojo build —mode dev —watch —serve

or using the abbreviated parameters:

dojo build -m dev -w -s

Now, open up a web browser to http://localhost:9999 to view the current application.

In the next step, we will start to customize the application.

Page content

Change what is rendered to the page.

To start customizing the application, let’s remove the existing content. There are two places we need to go to do this. The first line, “Welcome to biz-e-corp” is being generated from index.html.

Open index.html file in the src directory and remove the <p> tag and its content, "Welcome to biz-e-corp".

Notice that the page has automatically updated for us. That means that we can immediately see the impact of the change without having to stop our work and refresh or rebuild the application.

Now, let’s remove the “Hello, Dojo World!” message.

Open main.ts, located in /src.

You should see something like this:

import renderer from '@dojo/framework/widget-core/vdom';
import { v } from '@dojo/framework/widget-core/d';
const r = renderer(() =>
    v('div', [ 'Hello, Dojo World!' ])
);
r.mount({ domNode: document.querySelector('my-app') as HTMLElement });

Some of this code may not make sense now, but over the next few tutorials, you will find out what all of it means. For now, let’s focus on this line:

v('div', [ 'Hello, Dojo World!' ])

The v function simply instructs Dojo to create an HTML element, in this case a <div> element with the text “Hello, Dojo World!” inside of it. We will build a view that allows the user to view Biz-E Corp’s workers, so let’s update the tag and message to something more appropriate.

Replace the <div> tag with an <h1> tag, and replace "Hello, Dojo World!" with "Biz-E-Bodies"

const r = renderer(() =>
    v('h1', [ 'Biz-E-Bodies' ])
);

Now, let’s look at the v function again. We are intentionally avoiding something like document.createElement to create DOM (Document Object Model) elements. This is because we are not directly creating a DOM element. Instead, we are creating a representation of the view in TypeScript and letting Dojo efficiently determine how to convert it into DOM elements that are rendered onto the page. This rendering technique is called using a virtual DOM.

In traditional web applications, keeping the DOM and JavaScript application logic in sync led to significant complexity and inefficiency for non-trivial applications. When building applications with numerous changes to state and data, the virtual DOM approach can greatly simplify your application logic and improve performance. A virtual DOM serves as an intermediary between your application logic and what is rendered in the real DOM on the page.

Dojo leverages its own virtual DOM library, to determine the most efficient way to interact with the DOM elements in your view. An additional benefit of the virtual DOM is that it facilitates a reactive programming style which simplifies your application. In the final part of this tutorial, we will learn how to set properties on virtual DOM nodes.

Virtual DOM properties

Set properties on virtual DOM nodes.

Now we will add some additional attributes to the <h1> element we created earlier in HelloWorld.ts. These attributes can be passed in the second argument to the v function.

Update the v function call, with a title attribute like this.

v('h1', { title: 'I am a title!' }, [ 'Biz-E-Bodies' ])

Virtual Dom Properties and Attributes
The vdom system will automatically add properties with a type of string as an attribute and other values as properties on the DOM node.

Notice that we have added a parameter between the tag and content parameters. The object used as the second parameter can set any attributes or properties on the element being created. This method of using JavaScript or TypeScript to create DOM elements is called HyperScript and is shared by many virtual DOM implementations.

Summary

Congratulations! You are off to a good start on your journey to master Dojo. In Components of a Dojo application, we will start to get familiar with the major components of a Dojo application.

If you would like, you can open the completed demo application on codesandbox.io or alternatively download the project.