Creating Custom Elements

Prerequisites

You can open the 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 article for more information. You must also have the @dojo/cli-build-widget command installed (npm install @dojo/cli-build-widget).

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

Before we can generate a Custom Element, we must first create the Dojo Widget we wish to use. Here we will create a small widget with some properties and an event, and then show how we can use the @customElement decorator to allow the CLI to turn compile it to a Custom Element.

Examine the initial WorkerProfile widget in WorkerProfile.ts:

Here you can see a relatively simple widget that we will use to augment with the necessary code to allow the CLI to compile it to a Custom Element. In particular take a look at the properties that we are passing in, as we will need to reference these in when we go to state the properties and attributes of the Custom Element.

Applying the Custom Element Decorator

Append the customElement decorator like so:

Here we have to give a tag property to the object passed to the decotrator. The tag is the HTML Element name we will use for the Custom Element. In this case the tag would be used like <worker-profile></worker-profile>. We have also let the CLI know how to map our properties and attributes correctly, as well as our events, using the respective properties in the decorator argument.

Here we ommit a couple of potential arguments from the above decorator demonstration for simplicity. However we will explain the other two for completeness. Firstly, there is childType. This property is relevant if you are interested in having children in the Custom Element. The property takes one of three arguments, namely DOJO (default), NODE or TEXT, each corresponding to what children the Custom Element accepts. DOJO will allow a Custom Element to render other Custom Elements created from Dojo Widgets. NODE means it will accept regular DOM Nodes, and TEXT means the element will accept plain text as a child. The next property is which accepts a given Registry chosen by the developer. Explaining registries in detail is outside the scope of this tutorial, but you can see the .

Now to compile the Widget to a Custom Element. We do this via the command line, using the installed @dojo/cli-build-widget command.

Run the build custom element command like so:

dojo build widget —elements=src/widgets/WorkerProfile

Using the Created Custom Element

Now we have generated a the worker profile Custom Element, we can use it in other projects. As a basic example, lets show how that could be used in a blank web page. There are two ways to use a Custom Element, either declaratively (via HTML markup) or imperatively via JavaScript. Let’s take a look at both approaches.

The declarative approach can be done in the following manner:

This works well, we can see that we import the JavaScript and CSS files for the Custom Element and then use it like we would any other HTML Element. However using the declarative approach means we can’t access Custom Element properties or events. If we go down the imperative route, we can set these accordingly.

You can use the outputted worker profile element in the following manner` like so:

Once the JavaScript is imported, we use Custom Elements just like we would use other HTML Elements using standard DOM APIs like document.createElement, setAttribute and addEventListener (which is one of their strengths!).

In this tutorial we have shown how we can create a Dojo Widget, and then use the @customElement decorator to allow us to generate a Custom Element using . We have then demonstrated how you can use that Custom Element in another seperate page. Here, the ability to provide Custom Elements as an output from your widgets provides the benefit of having the ability to share code between different teams, projects and even companies that may be using other frameworks.