Skip to content

Theme class name conventions

Jump to bottom
Mark Reeves edited this page Jan 4, 2018 · 39 revisions

tl;dr

This is a very long page outlining some of the HTML class attribute values used in wcomponents-theme. It is here for theme developers and those who need to build application-level CSS.

Default class names

This is a map of WComponents to html class attribute values where a particular component is expected to have the class attribute on its outermost element and that attribute will include the associated class name. Unless otherwise indicated none of this applies to version 1.0.4 or before.

UI components

Most UI components have an XML schema which defines the output element for that component. The transformed HTML outer element will then contain a class attribute which will contain the value as indicated in the table below. NOTE that this is recommended but may be over-ridden and changed completely in any given theme. For some elements we recommend not using the XML element generated class name even if it exists as this may result in inconsistencies in the UI. These are marked in the third column of the following table.

WComponent Class value
WAbbrText n/a use abbr element
WApplication n/a use form element
WAudio wc-audio
WButton wc-button
WCheckBox wc-checkbox
WCheckBoxSelect wc-checkboxselect
WCollapsible wc-collapsible
WCollapsibleToggle wc-collapsibletoggle
WColumn wc-column
WDateField wc-datefield
WDecoratedLabel wc-decoratedlabel
WDefinitionList wc-definitionlist
WDialog wc-dialog
WDropdown wc-dropdown
WEmailField wc-emailfield
WField wc-field
WFieldLayout wc-fieldlayout
WFigure wc-figure
WFileWidget wc-fileupload
WHeading wc-heading
WHorizontalRule n/a use hr element
WImage n/a use img element
WLabel wc-label
WLink wc-link
WMenu wc-menu
WMenuItem wc-menuitem
WMessageBox wc-messagebox
WMultiDropdown wc-multidropdown
WMultiFileWidget wc-fileupload
WMultiSelect wc-listbox
WMultiSelectPair wc-multiselectpair
WMultiTextField wc-multitextfield
WNumberField wc-numberfield
WPanel wc-panel
WPartialDateField wc-datefield
WPasswordField wc-passwordfield
WPhoneNumberField wc-phonenumberfield
WPrintButton wc-printbutton
WProgressBar wc-progressbar
WRadioButton wc-radiobutton
WRadioButtonSelect wc-radiobuttonselect
WRow wc-row
WSection wc-section
WSelectToggle wc-selecttoggle
WSeparator wc-separator
WShuffler wc-shuffler
WSingleSelect wc-listbox
WSkipLinks wc-skiplinks
WStyledText wc-text
WSubMenu wc-submenu
WTab wc-tab
WTable wc-table
WTabSet wc-tabset
WTextArea wc-textarea
WTextField wc-textfield
WValidationErrors wc-validationerrors
WVideo wc-video

Classes based on properties

Some UI components have an value in the HTML class attribute of the outer element based on the value of a component property. This is in addition to the class value based on the component as outlined above. The possible values values of this class are provided by the XML schema for the component. The property will have a token restriction in the schema and each enumeration value of that restriction will be a possible value. These values are prefixed.

If the schema property has a default value then that value is not guaranteed to form part of the class attribute's value as it may not appear in the XML.

Note that in the table below the Java property is a private member of the WComponent's class unless prefixed by the type; for example renderAsLink is private on WButton but WPanel.Type is public on WPanel.

WComponent / sub-component property schema attribute Prefix Exceptions
WButton renderAsLink @type wc-button-type- if false @type not set 1
WCheckBoxSelect WCheckBoxSelect.Layout @layout wc-layout- none
WColumn WColumn.Alignment @align wc-align- none
WDefinitionList WDefinitionList.Type @type wc-definitionlist-type- WDefinitionList.Type.NORMAL
WFieldLayout layoutType @layout wc-layout- none
WLink renderAsButton @type wc-link-type- if false @type not set 3
WList (see WPanel ListLayout) WList.Alignment @align wc-align- WList.Alignment.LEFT 2
WList (see WPanel ListLayout) WList.Type @type wc-listlayout-type- none
WList (see WPanel ListLayout) WList.Separator @separator wc-listlayout-separator- WList.Separator.NONE @separator not set but has class name wc_list_nb (see Utility classes)
WMenu WMenu.Type @type wc-menu-type none
WPanel ColumnLayout ColumnLayout.Alignment @align 4 wc-align- ColumnLayout.Alignment.LEFT 2
WPanel ListLayout ListLayout.Alignment @align wc-align- ListLayout.Alignment.LEFT 2
WPanel ListLayout ListLayout.Type @type wc-listlayout-type- none
WPanel ListLayout ListLayout.Separator @separator wc-listlayout-separator- ListLayout.Separator.NONE has class name wc_list_nb (see Utility classes)
WMessageBox WMessageBox.Type @type wc-messagebox-type- none
WPanel WPanel.Type @type wc-panel-type- WPanel.Type.PLAIN
WProgressBar WProgressBar.ProgressBarType @type wc-progressbar-type- WProgressBar.ProgressBarType.NORMAL
WRadioButtonSelect WRadioButtonSelect.Layout @layout wc-layout- none
WStyledText WStyledText.Type @type wc-text-type- none
WTable WTable.Type @type wc-table-type- WTable.Type.TABLE
WTabSet WTabSet.TabSetType @type wc-tabset-type none

Example using properties

An example of this is WPanel which has a Type property. If the Type is set to WPanel.Type.CHROME then the WPanel's outer element will have a class attribute which contains at least wc-panel wc-panel-type-chrome; if, however, the Type is WPanel.Type.PLAIN the schema does not provide a token for that type and the panel's class attribute will be at least wc-panel.

Sub-components

These are parts of a WComponent UI component which are not directly addressable in the Java API but which have a consistent output in the Java renderers. This includes such constructs as the layouts of WPanel (such as FlowLayout).

Sub-component Class value
WPanel BorderLayout wc-borderlayout
The WPanel BorderLayout NORTH container wc-north
The WPanel BorderLayout SOUTH container wc-south
The WPanel BorderLayout EAST container wc-east
The WPanel BorderLayout WEST container wc-west
The WPanel BorderLayout CENTER container wc-center
WPanel ColumnLayout wc-columnlayout
WPanel FlowLayout wc-flowlayout
WPanel GridLayout wc-gridlayout
WPanel ListLayout wc-listlayout
Wrapper for components added to WPanel ColumnLayout, WPanel FlowLayout and WPanel GridLayout wc-cell

Margins

If a Margin is applied to a WComponent it is exposed as a class value with the prefix as listed in the documentation of Margin.

Class names not based on the XML schema

There are class values which are not based on element or attribute names from the XML schema. These class values will be prefixed with either wc_ or wc-.

When prefixed wc_ these should be considered the equivalent of private members and are generally not reliable as they do not derive from a part of the WComponents public API. It is intended to form a "public" CSS API by exposing utility classes prefixed wc- which will not change after WComponents 1.2 unless the major version increments in which case any changes will form part of the API changes in the CHANGELOG.

Common classes

A very small number of class values are applied in certain contexts where there is a known XML element with a particular name-based class value and other HTML artefacts which are not necessarily part of the XML input stream, and which in all cases have a different element name, but which do the same job. It should be reasonably safe to use these classes in your selectors but their support is not fixed in stone.

Types of component Base WComponent Additional WComponents HTML class attribute value
Rows WRow each 'row' in any WPanel ColumnLayout, WCheckBoxSelect with WCheckBoxSelect.Layout.COLUMN, WRadioButtonSelect with WRadioButtonSelect.Layout.COLUMN. wc-row
Columns WColumn each 'column' in the components listed above. wc-column

Utility classes

The following lists the first cut of the "public" CSS API. These classes are expected to remain constant. Any of the classes used in HtmlClassProperties can be relied upon to remain constant. Refer to HtmlClassProperties for information regarding the utility class values it exposes.

Types of component HTML class attribute value
Buttons without a button appearance wc-nobutton
Buttons with a link appearance13 wc-linkbutton
Containers/layouts with gap see Theme intra component spacing
Containers/layouts with hgap see Theme intra component spacing
Containers/layouts with vgap see Theme intra component spacing

The following lists utility classes which may be applied to any component which supports setHtmlClass or used in a WTemplate. Some of these are exposed in the Java API in HtmlClassProperties and HtmlIconUtil.

Class value Description
wc-align-center Center align the content of the element.
wc-align-left Left align the content of the element.
wc-align-right Right align the content of the element.
wc-hscroll Make the component scroll horizontally if it is wider than its container.
wc-brkall Allow text content of a component to wrap/break at non-word boundaries.
wc-border Apply a theme-defined standard border to a component.
wc-icon Use a theme icon as the component's content. Must be used with an other classname from Font Awesome to describe the icon.
wc-icon wc-icon-before Use a theme icon before the component's content. Must be used with an other classname from Font Awesome to describe the icon.
wc-icon wc-icon-after Use a theme icon after the component's content. Must be used with an other classname from Font Awesome to describe the icon.
wc-invite Turn on hover/focus effects for an interactive component. Components will have this class if required but it may be added to WButton under some controlled circumstances - see [[WButton styles
wc-off Move the element out of viewport. Commonly used for headings for a11y purposes.
wc-respond Turn on very basic responsive design for a WTable, WRow or [[ColumnLayout

The classes in the following table are used to set vertical alignment. Some or all be turned off for a theme by setting a Sass variable.

Class value Description
wc-valign-baseline Explicitly set the vertical alignment to baseline (note for many uses this is the default).
wc-valign-bottom Set the vertical alignment to bottom.
wc-valign-inherit Set the vertical alignment to inherit.
wc-valign-initial Set the vertical alignment to initial (note: may have unfortunate effects in Internet Explorer).
wc-valign-middle Set the vertical alignment to middle.
wc-valign-sub Set the vertical alignment to sub.
wc-valign-super Set the vertical alignment to super.
wc-valign-text-bottom Set the vertical alignment to text-bottom.
wc-valign-text-top Set the vertical alignment to text-top.
wc-valign-top Set the vertical alignment to top.

Special use utility classes

Some utility classes are provided which may only apply to certain components or components in certain states.

to be continued

Icon colours

The following classes are available to set the colour of an icon set on a component. Note that these class names act on the ::before pseudo-element only and will not also change the colour of text in a component.

  • wc-c-error will set the icon glyph to the theme's error colour (default to red);
  • wc-cwarning will set the icon glyph to the theme warning colour;
  • wc-cwinfo will set the icon glyph to the theme information message colour;
  • wc-csuccess will set the icon glyph to the theme success message colour;

Included libraries

WComponents version 1.1.0 and later will ship with Font Awesome compatibility. Therefore all classes exposed by Font Awesome may be used. We recommend using WStyledText with setHtmlClass("wc-icon fa-icon-name") as a simple means to add icons. These class values may also be used in WTemplate code. There is an example of this in the wcomponents-examples project.

We will add any other libraries here as support is added. Of course one can add any other library using WApplication.setCssUrl(String url). So to use a CDN version of Unsemantic grid system (for example) one could:

// with WApplication application
application.addCssUrl("https://cdnjs.cloudflare.com/ajax/libs/unsemantic/1.0.3/unsemantic-grid-responsive.min.css");

Then use a WTemplate to set up your screen architecture and plonk WComponents' accessible UI controls into that layout.

Other classes

There are a large number of class values we make up as we go along which constitute a more-or-less 'private' member equivalence. These all start wc_ and should not be relied upon as part of application level customisations of CSS or JavaScript unless you have absolutely no other option.

Use in CSS

You should note that WComponents only uses classes in CSS where a WAI-ARIA attribute is not available or leads to ambiguity or excessive nesting. Therefore a simple class selector may not be sufficient to override some inbuilt CSS.

Where custom CSS is being used to add new rules then a simple class selector will suffice.

/* This rule probably won't work as the menu item color is usually set in
   theme based on nested attribute selectors. */
.wc-menuitem {
  color: red;
}
/* whereas ... */
/* This probably will work because font-size is not generally set at this
   level. */
.wc-menuitem {
  font-size: 2em;
}

Use in JavaScript

WComponents UI control JavaScript is based on WAI-ARIA attributes where available. In the unlikely case that theme functionality is to be overridden in a specific application the control in question should, where possible, be obtained by requiring the theme controller class and using its getWidget() method. The custom behaviour may then be applied by using this Widget directly or, where the new functionality is only to be applied to a specific instance of the component, by extending this Widget with the custom class attribute value. A rather empty example of this is shown below:

define(["wc/ui/controller"],
  function (controller) {
    "use strict";

    function MyNewController () {
      var ctrlWidget = controller.getWidget(),
      myNewWidget = ctrlWidget.extend("my-custom-class-name");

      this.somePublicMethod = function(args) {
        // do stuff
      };

      function somePrivateMethod(args) {
        //do stuff
      }

      // etc
    }
    // etc
    return new MyNewController();
  }
);

Related topics

Notes

  1. When WButton has renderAsLink == true then the class value output includes wc-linkbutton. Back to WButton properties.
  2. When a container supports an Alignment and the @align attribute is not set in the XML then the default alignment of the theme locale is used. In wcomponents-theme this is left and the value wc-align-left is included in the container's outer element's class attribute.
  1. When WLink has renderAsButton == true the output element is a button and no additional class is used. When WLink has renderAsButton == false but the output element is a button element for other reasons then the class value output includes wc-linkbutton. Back to WLink properties.
  2. The WPanel ColumnLayout @align attribute is attached to the column sub-components. Back to ColumnLayout properties.

Some start pages

Clone this wiki locally