Theming

    Prerequisites

    You can the demo project and run 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.

    Theming our widgets

    In Dojo, we differentiate between two types of styles:

    • Structural styles: these are the minimum necessary for a widget to function
    • Visual styles: these are themed
      The current CSS in the example app provides the structural styles, we will now review how to create and manage themes.

    In order to theme our widgets, we must ensure that they each apply the ThemedMixin and change the class name of the widget’s top-level node to root. The ThemedMixin provides a this.theme function that returns (or that will return) the correct class for the theme provided to the widget. The top-level class name is changed to root in order to provide a predictable way to target the outer-node of a widget, this is a pattern used throughout widgets provided by @dojo/widgets.

    Replace the contents of Banner.ts with the following

    Reminder
    If you cannot see the application, remember to run dojo build -m dev -w -s to build the application and start the development server.

    This Banner widget will now have access to the classes in banner.m.css and can receive a theme. We use the root class to ensure that the theme we create can easily target the correct node.

    Notice that this file and other css files now have a .m.css file extension. This is to indicate to the that this file is a css-module and should be processed as such.

    CSS Modules
    CSS Modules is a technique to use scoped CSS classnames by default.

    Create a new style sheet for the Banner widget named banner.m.css.

    We will create an empty root class for now as our base theme does not require any styles to be added to the Banner widget.

    1. File: src/styles/banner.m.css
      .root {
    3. }

    Now, let's look at changing the WorkerForm widget

    Fixed Classes
    Fixed classes apply styles that cannot be overridden by a theme, using a suffix is a convention that helps easily differentiate the intention of these classes.

    1. File: src/widgets/WorkerForms.ts
      return v('form', {
    2.     classes: [ this.theme(css.root), css.rootFixed ],
    3.     onsubmit: this._onSubmit
    4. }, [

    Replace all of the selectors containing .workerForm with the following rules in workerForm.m.css.

    1. File: src/styles/workerForm.m.css
      .root {
    2.     margin-bottom: 40px;
    3. }
    5. .rootFixed {
    6.     text-align: center;
    7. }
    9. .rootFixed fieldset,
    10. .rootFixed label {
    11.     display: inline-block;
    12.     text-align: left;
    13. }
    15. .rootFixed label {
    16.     margin-right: 10px;
    17. }

    If you open the application in a browser its appearance and behavior should be unchanged.

    Now update worker.m.css and workerContainer.m.css to use .root and .rootFixed…

    1. File: src/styles/workerContainer.m.css
      .rootFixed {
    2.     display: flex;
    3.     flex-flow: row wrap;
    4.     justify-content: center;
    5.     align-items: stretch;
    6.     margin: 0 auto;
    7.     width: 100%;
    8. }
    10. .root {
    12. }

    …and then update the associated widgets to use the new selectors.

    1. // WorkerContainer.ts
    2. // ...
    3. render() {
    4.     // ...
    5.     return v('div', {
    6.             classes: [ this.theme(css.root), css.rootFixed ]
    7.     }, workers);
    8.     // ...
    9. }
    11. // Worker.ts
    12. // ...
    13. render() {
    14.     // ...
    15.     return v('div', {
    16.         classes: [
    17.             ...this.theme([ css.root, this._isFlipped ? css.reverse : null ]),
    18.             css.rootFixed
    19.         ]
    20.     }, [
    21.     // ...
    22. }

    Next, we will start to create a theme.

    Creating a Theme

    Create a theme directory

    Dojo provides a CLI command for creating a skeleton theme from existing Dojo widgets. To do this the command prompts the user to enter the name of the package that contains Dojo widgets and allows you to select specific widgets to include in the output.

    At the command line run dojo create theme —name dojo

    When prompted for the package to theme enter @dojo/widgets and then type N to indicate their are no more packages. You should now be presented with a list of widgets from @dojo/widgets that can be scaffolded. For this demo we need to select button and text-input using the arrow keys and space to select each one, press enter to complete the process.

    This should have created a themes directory in the project’s src directory, this will be where the custom theme is created.

    Dojo uses the concept of a key to be able to look up and load classnames for a theme, it is a composite of the package name and the widget name joined by . These keys are used as the keys to object that is exported from the main theme.ts.

    Theme the Worker widget

    In order to theme the Worker widget, we need to create worker.m.css within our themes/dojo directory and use it within theme.ts. As mentioned above, the naming of the key of the exported theme must match the name from the project’s package.json and the name of the widget’s style sheet joined by a forward slash (/).

    Let’s start by creating a red Worker and observe our theme being applied correctly.

    1. /* worker.m.css */
    2. .root {
    3.     background: red;

    So for theme.ts, you need to add the import for the worker.m.css and the theme itself to the exported object using the key biz-e-corp/worker.

    1. File: src/themes/dojo/theme.ts
      import * as worker from './worker.m.css';
    2. import * as textInput from './@dojo/widgets/text-input/text-input.m.css';
    3. import * as button from './@dojo/widgets/button/button.m.css';
    5. export default {
    6.     'dojo-theming-tutorial/worker': worker,
    7.     '@dojo/widgets/text-input': textInput,
    8.     '@dojo/widgets/button': button
    9. };

    What is a registry?
    A registry provides a mechanism to inject external payloads into widgets throughout the application tree. To learn more, take a look at the container tutorial and .

    However an application can automatically inject a theme from the registry to every themed widget in an application tree. First, create a themeInjector using the registerThemeInjector function by passing a registry instance and theme. This will return a handle to the themeInjector that can be used to change the theme using themeInjector.set(), which will invalidate all themed widgets in the application tree and re-render using the new theme!

    Update our main.ts file to import our theme and create a themeInjector.

    1. File: src/main.ts
      import renderer from '@dojo/framework/widget-core/vdom';
    2. import { w } from '@dojo/framework/widget-core/d';
    3. import { registerThemeInjector } from '@dojo/framework/widget-core/mixins/Themed';
    4. import { Registry } from '@dojo/framework/widget-core/Registry';
    5. import App from './widgets/App';
    6. import theme from './themes/dojo/theme';
    8. const registry = new Registry();
    9. registerThemeInjector(theme, registry);
    11. const r = renderer(() => w(App, {}));
    12. r.mount({ domNode: document.querySelector('my-app') as HTMLElement, registry });

    Open the application in your web browser and see that the Worker backgrounds are now red.

    Use variables and complete the Worker theme

    The Dojo build system supports new CSS features such as css-custom-properties by using PostCSS to process our .m.css files. We can use these new CSS features to add variables to worker.m.css and complete its theme.Let’s create themes/dojo/variables.css (notice that this file does not have a .m.css extension as it is not a css-module file).

    In the above code you can see that we have created a number of CSS Custom Properties to be used within our theme and wrapped them in a :root selector which makes them available on the global scope within our css-modules.To use them, we can @import the variables.css file and use the var keyword to assign a css-custom-property to a css rule.

    Now we will use these variables in our themes worker.m.css to create our fully themed Worker.

    1. File: src/themes/dojo/worker.m.css
      @import './variables.css';
    3. .root {
    4.     width: 320px;
    5.     height: 370px;
    6.     box-sizing: border-box;
    7.     margin: var(--spacing);
    8.     position: relative;
    9. }
    11. .image {
    12.     background: var(--component-accent);
    13.     border-radius: 50%;
    14.     width: 250px;
    15.     height: 250px;
    16.     margin-bottom: var(--padding);
    17. }
    19. .imageSmall {
    20.     background: var(--component-accent);
    21.     border-radius: 50%;
    22.     width: 72px;
    23.     height: 72px;
    24.     display: inline-block;
    25.     margin-right: 24px;
    26. }
    28. .workerFront, .workerBack {
    29.     position: absolute;
    30.     top: 0;
    31.     bottom: 0;
    32.     left: 0;
    33.     right: 0;
    34.     border: 1px solid var(--component-accent);
    37. .workerFront {
    38.     box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.35);
    39.     padding: var(--padding);
    40.     text-align: center;
    41. }
    43. .workerBack {
    44.     box-shadow: 0 20px 35px 0 rgba(0, 0, 0, 0.15);
    45.     background: var(--card);
    46.     color: var(--body);
    47. }
    49.     background: var(--accent);
    50.     color: var(--card);
    51.     padding: 24px;
    52. }
    54. .generalInfo {
    55.     display: inline-block;
    56.     vertical-align: top;
    57.     line-height: 24px;
    58. }
    60. .generalInfo .label {
    61.     display: none;
    62. }
    64. .tasks strong {
    65.     background: var(--secondary-accent);
    66.     color: var(--card);
    67.     display: block;
    68.     font-size: 14px;
    69.     padding: 14px 24px;
    70.     text-transform: uppercase;
    71.     font-weight: 400;
    72. }
    74. .task {
    75.     padding: 12px 24px;
    76.     border-bottom: 1px solid var(--component-accent);
    77. }

    Thus far in this tutorial, we have themed our custom Worker widget, but we have not targeted Dojo widgets that are contained within our application. To demonstrate the styling of Dojo widgets, we will theme the workerForm widget as it contains both DOM nodes and Dojo widgets.

    Let's create workerForm.m.css

    1. File: src/themes/dojo/workerForm.m.css
      @import './variables.css';
    3. .root {
    4.     font-family: var(--font);
    5.     padding: 30px;
    6.     box-sizing: border-box;
    7.     font-weight: bold;
    8. }
    10. .nameLabel {
    11.     font-size: 14px;
    12. }

    And include it in theme.ts

    1. File: src/themes/dojo/theme.ts
      import * as worker from './worker.m.css';
    2. import * as workerForm from './workerForm.m.css';
    4. export default {
    5.     'dojo-theming-tutorial/worker': worker,
    6.     'dojo-theming-tutorial/workerForm': workerForm,
    7. };

    This should be familiar from theming the Worker in the previous section. To theme the Dojo TextInput within our WorkerForm, we need to add to the skeleton text-input.m.css theme created by @dojo/cli-create-theme, this is already exported from theme.ts.

    1. File: src/themes/dojo/@dojo/widgets/text-input/text-input.m.css
      @import './../../../variables.css';
    3. .root {
    4.     margin-right: 10px;
    5.     display: inline-block;
    6.     composes: nameLabel from './../../../workerForm.m.css';
    7.     text-align: left;
    8. }
    10. .input {
    11.     height: 38px;
    12.     border: 1px solid var(--input-border);
    13.     box-sizing: border-box;
    14.     border-bottom-color: color(var(--input-border) blackness(60%));
    15.     padding: 8px;
    16.     min-width: 230px;
    17. }

    Notice the styling rule for the .root selector? Here we are introducing another powerful part of the Dojo theming system, composes. Composes originates in the , allowing you to apply styles from one class selector to another. Here we are specifying that the root of a TextInput (the label text in this case), should appear the same as the nameLabel class in our WidgetForm. This approach can be very useful when creating multiple themes from a baseTheme and avoids repetitive redefinition of style rules.

    In your web browser you will see the TextInput widgets at the top of the form have been styled.

    Add the following theme styles to the button.m.css theme resource

    Summary

    • How to create a theme
    • How to apply a theme to both Dojo and custom widgets using the themeInjector.
    • How to leverage functionality from the Dojo theming system to apply variables
    • How to use to share styles between components
      You can download the completed from this tutorial.