WHeading
WHeading is a component for creating headings.
- Why use WHeading
- When not to use
- Creating a WHeading
- Accessibility
- Appearance
- HTML output
- WComponents which are not headings
- Theme developers notes
- Related components
- Further information
WHeading creates heading elements h1 to h6. If the UI requires an application to be broken up by heading then WHeading will allow this. Note, however, that there are other ways to apply headings. Section content with in-built headings can be created using WSection, WPanel Type.CHROME and WPanel Type.ACTION. WCollapsible can also create a heading from its labelling content.
WHeading must not be used within a piece of sectioning content if the section has no need for sub-headings or if the entire section has a single heading.
It may be more appropriate to use WFieldSet to break a form into semantic sections than to rely on headings.
A WHeading may be constructed using one of two constructors. Each accepts a HeadingLevel argument. One takes a String; the other a WDecoratedLabel.
// build with a String
WHeading simpleHeading = new WHeading(HeadingLevel.H2, "Your details");
// build with a String i18n token `I18N_HEADING`
WHeading internationalisableHeading = new WHeading(HeadingLevel.H2, I18N_HEADING);
// or, give a WDecoratedLabel headingLabel:
WHeading containerHeading = new WHeading(HeadingLevel.H2, headingLabel);The HeadingLevel is used to indicate the level of the heading within the section hierarchy. This is a required property and has no default. You must explicitly specify the HeadingLevel of all WHeadings used in an application. For more information see specifying the HeadingLevel.
The heading level can be set in a constructor or using a setter.
// Set a HeadingLevel in a constructor
WHeading mainHeading = new WHeading(HeadingLevel.H1, HEADING_TEXT);
// ...
// It may be necessary to reset the heading level dependent on context
mainHeading.setHeadingLevel(HeadingLevel.H2);The content of a WHeading must be appropriate for a heading and must describe the content to which the heading forms the header. For more information see HTML specification, WCAG 2 SC 2.4.6 and WCAG G130.
A WHeading may contain simple text (which may be unescaped) or a WDecoratedLabel. When using unescaped text or WDecoratedLabel the content must still be appropriate for a heading and be phrase content only (see WComponent content models).
WHeading supports unescaped content. This means it is possible to have raw HTML in a WComponent. This is best avoided, for example the following option for creating a coloured heading is usually a very bad idea:
WHeading unescapedHeading = new WHeading(HeadingLevel.H3,
"<span style='color:red'>Red H3 (unescaped text)</span>");
unescapedHeading.setEncodeText(false);If a heading contains punctuation unescaped content may be appropriate:
WHeading unescapedHeading = new WHeading(HeadingLevel.H3, "The User‘s Details");
// if not unescaped would output "The User"s Details"
unescapedHeading.setEncodeText(false);
// will now output "The User’s Details"All WHeadings must have palpable content and should preferably have text content. The content of the heading should be appropriate for a section heading and not usually contain meta-data. Headings should be brief but descriptive. Within any given section (actual or virtual) heading should be unique. It is preferred that all headings in any screen be unique.
All WHeadings must have an appropriate HeadingLevel which conforms with the HTML specification and its semantics of headings and sections.
WHeading outputs non-phrasing content and must not be placed in WComponents which must only contain phrasing content. The content model of WHeading is phrase content and so must only contain text or components which outputs phrasing content. It could be deemed inappropriate to add form controls or similar interactive components since it is difficult to argue that a control forms part of a heading. This construct is not enforced, however, so long as the components are of the correct content category.
The default wcomponents-theme applies a very simple appearance to headings which is designed to be easily overrideable and easy to add on to in an implementation. The screen shot below shows WHeadings at each HeadingLevel.
WHeading is a marginable component. If a Margin is not defined for a WHeading then the margin is determined by the theme or the client user agent.
WHeading may have one or more values to be added to the component's root element. This can be used for fine-grain styling of specific components but should be used with care.
For more information see WComponents HTML class property.
WHeading outputs an element dependent upon its HeadingLevel property. These are h1, h2, h3, h4, h5 or h6 elements.
Some WComponents contain labeling elements which may appear similar to headings. No WComponent outputs a h2...h6 element other than WHeading. Only those components which output a default heading output a h1 element. The components which are most commonly confused with WHeadings are:
- the summary element of a WCollapsible (unless the HeadingLevel property is set);
- the legend of a WFieldSet; and
- a WLabel associated with a WComponent which outputs a compound form control.
Most headings are structured and styled on the element not on the WComponent default className for WHeading (wc-heading). This allows us to keep the same styles across all headings, however they arise (including, for example, the heading generated from WCollapsible with HeadingLevel set.)
- HeadingLevel
-
WSection will output a
h1element as part of its header -
WPanel of
Type.CHROMEorType.ACTIONwill output a h1 element as its header - WCollapsible may use a heading element as part of its labelling content if it has a HeadingLevel set