Creating a new Widget and Styles

[kitsonk]

User Story

As a developer, when I create a new class of widget, I want it to be easily themeable. What considerations and conventions should I include in the styles for the widget to ensure it is themeable downstream?

[smhigley]

The most basic way to answer this is just that all VNodes should get passed a className in this.classes() even if they receive no styles in the current theme, and all WNodes should get passed the theme property. This will at minimum give any authors using the widget the ability to theme it any way they wish.

There are a couple other patterns that will make the experience of theming a widget a little nicer: fixed classes, and making it easy to extend the widget and add to state classes (although the second may be more a widget extension pattern than a theming one).

First, fixed classes: any styles that are necessary for the basic function of the widget should be split out into fixed classes so widget authors don’t need to worry about breaking functionality while trying to modify visual style. A good example of this is the Slider widget, which relies on an invisible native slider input overlaid on the styled interface. There are a number of styles necessary to correctly make the native input invisible and correctly positioned, all of which would be a pain to re-create every time an author wished to thumb size, for example.

The second point, isolating and returning “state”-type classes in their own overridable method is something we don’t do yet in any existing widgets. For example: a Button already has classes for disabled, popup, and pressed states. If we returned those classes in a getStateClasses() or getModifierClasses() function, it would be easy to override and add something like a loading class. This ties in to #274, in that I think we need to accept that we will never be able to account for all the visual states a widget may need to be able to handle. In the above case, creating an extended Button that includes a loading state might look like this:

export interface CustomButtonProperties extends ButtonProperties {
  loading: boolean;
}

@theme(css)
export class CustomButton extends Button<CustomButtonProperties> {
  getStateClasses() {
    const { disabled, popup, pressed, loading } = this.properties;
    return this.classes(
      disabled ? css.disabled : null,
      popup ? css.popup : null,
      pressed ? css.pressed : null,
      loading ? css.loading : null
    );
  }
}

Summary

• All nodes have a class applied, even if not currently used
• Pass theme to any child widgets
• Styles necessary for the basic function of the widget are separated into fixed classes
• [proposed] Widgets that support different visual states return those classes in an overridable function

[bitpshr]

@smhigley summarized this pretty perfectly. #316 covers returning “state”-type classes in their own method and our current theme tutorial covers the other three points listed.

Action items:

• Create a ticket to add a tutorial for this content Tutorial for widget extensibility dojo.io#290
• Close this ticket