Components of a Dojo application

Index HTML file

HTML pages are the foundation of every web application and Dojo applications are no different. Traditionally a single index.html file serves the role of representing both the entry point to the application, as well as the root container for the application’s overall structure within the DOM.

Dojo applications are typically injected into a single DOM element, by default document.body. This allows a Dojo application to easily coexist with other content on a page - static assets, a legacy application or even another Dojo application.

Widgets

Widgets are Dojo's analogy to DOM elements, and are the central concept of encapsulation within a Dojo application. Just as traditional websites are built up through a hierarchy of DOM elements, a Dojo application is constructed through a hierarchy of widgets.

Widgets represent everything from individual UI elements - such as a label or a textbox - to more complex containers that may represent a form, a page, or an entire application.

Similarly as not all elements within a DOM are visible to users, Dojo widgets are not exclusively focused on providing a user interface, but can also serve any behind-the-scenes requirements to implement the full range of application functionality.

See the Creating Dojo Widgets reference guide for information on how to create widgets within your application.

TypeScript modules

Dojo widgets can be represented either as render function factories or TypeScript classes, and are typically contained within a single TypeScript module. The module encapsulates most of what constitutes the widget, including its behavior and semantic representation within a virtualized DOM.

Widgets provide an API to external consumers via a properties interface. This interface serves as both a list of state fields that can be injected into the widget when it is rendered, as well as any functions that can be called if the widget needs to notify other parts of the application when an event occurs, such as a change in state.

CSS modules

Presentational styling of widgets is handled via CSS, similar to styling of regular HTML elements. CSS modules are used to encapsulate the presentational concerns of a single widget and avoid clashing with other widgets that may use similar CSS class names.

Widgets can import their CSS modules like any other TypeScript import, allowing them to refer to their CSS class names via object properties which can be autocompleted within a developer’s IDE. These property names can be used to specify styling classes when declaring the widget’s semantic element structure. CSS class name mismatches between a widget and its styling can therefore be identified at build time.

While a widget can entirely encapsulate its own styling via its corresponding CSS module, usually some flexibility is required. A widget may be used in different configurations across an application, each with their own unique presentational needs. Dojo supports the ability to override specific styles to meet these needs.

To support consistent presentation across an application, widget styling can be further controlled via theming.

See the Dojo Styling and Theming reference guide reference for more details on how to style individual widgets.