Skip to content

WStyledText

Jump to bottom
Mark Reeves edited this page Jan 3, 2018 · 10 revisions

WStyledText is a component used to output text to which one of a small set of styles may be applied. The supported styles are those which were requested to solve particular use-cases and which have a semantic rather than merely decorative meaning.

Why use WStyledText

WStyledText is a bit of an old legacy component left over from the time when it is reputed that Java framework developers thought Java application developers should not be trusted with HTML.

For most purposes WStyledText is not necessary and could easily be replaced with any combination of unescaped WText and WTemplate. What WStyledText does provide is a relatively simple way to add some basic styled content to an application in a way which retains theme-driven corporate design standards and attempts to ensure reasonable accessibility.

Use WStyledText to add paragraphs, pre-formatted text content or small amounts of:

  • strongly emphasised text;
  • emphasised text;
  • inserted text;
  • (soft) deleted text;
  • content which can be used to indicate some sort of tri-level priority.

Use as an icon holder

WStyledText is a useful light-weight component for adding an icon (such as from the Font Awesome set) to a UI. WStyledText with no Type or space set outputs a HTML span element and may be "empty". Using HtmlIconUtil and addHtmlClass makes it a reasonably simple process to make the WStyledText contain an icon.

// create an element to show a "cog" icon.
WStyledText icon = hew WStyledText("\u200b");
icon.setHtmlClass(HtmlIconUtil.getIconClasses("fa-cog"));

Note: there is a limitation in WComponents up to and including 1.2.x that WStyledText will only render itself if it is not empty, therefore the WStyledText component in the above example needs some content and "\u200b" is a zero-width space.

When not to use

WStyledText should not be used as a read-only replacement for WComponent form controls such as WTextField. It would be considered a significant usability issue to do this and use Type EMPHASISED or HIGH_PRIORITY.

Accessibility and usability

There are several well known usability and accessibility issues surrounding styling text. These are circumvented by careful determination of styles and restriction on certain combinations of properties. For further discussion of usability suggestions regarding text formatting see US Department of Health & Human Services guidelines on text appearance.

Emphasised Text

Emphasised text is created using Type EMPHASISED and is rendered in a strong element which for most common browsers is represented in bold face. An application should avoid using emphasised text for any output which may be more than a few words or in conjunction with white space mode as it may reduce readability of large blocks of text.

Mandatory indicator

The Type MANDATORY_INDICATOR has a very specific use. It should only be used to:

  • provide a key on a view which contains mandatory inputs to indicate to users that a label marked by a mandatory indicator indicates that the control associated with that label is required; or

  • as part of a WTable column (or row) header if (and only if)

    • the column (or row for row header) consists of input controls where every input control is mandatory and
    • each individual control has been made mandatory in its own right and
    • the control does not have a visible label with its own mandatory indicator.

    In this case the WStyledText takes the place of the secondary indication of the mandatory state of the controls in the column which would normally be taken by a WLabel.

Priority indicators

WStyledText supports Type values for adding high, medium and low priority indicator text. This sort of indicator is commonly output using coloured text which may pose significant accessibility issues and could be deemed to be in contravention of WCAG 2.0 level A guidelines such as G14: Ensuring that information conveyed by color differences is also available in text or G138: Using semantic markup whenever color cues are used. Therefore the default is to output un-styled but semantically correct elements (though the LOW_PRIORITY element has no semantic meaning other than not being an element with text-level semantics). This makes adding style to these components at a theme or application level relatively simple.

Paragraphs

If a potentially large block of text is to be output then specifying WhitespaceMode.PARAGRAPHS will convert line breaks in the text to p elements. This could improve the readability of the text.

Creating WStyledText

WStyledText has three constructors: the default constructor, a constructor which accepts a single String argument and a constructor which accepts a String and a Type argument.

// simple instantiation of a WStyledText
WStyledText noTypeNoContentText = new WStyledText();
// note that noTypeNoContentText will not render unless it
// subsequently gets some text content.

// Using a default piece of text
WStyledText noTypeText = new WStyledText("Content");

// Using default text and setting a type
WStyledText text = new WStyledText("Content", WStyledText.Type.INSERT);

HTML output

The HTML element output by WStyledText is determined by a combination of the Type and white space mode properties. To determine the output element:

In the cases where the white space mode is set and the Type property is set (and is not Type.PLAIN) then the wrapper will contain one or more inner element(s) determined by the Type:

  • if the white space mode is PARAGRAPHS one inner element per paragraph;
  • if the white space mode is PRESERVE one inner element wrapping all of the text content;

The elements based on the Type property are:

  • if a White space mode is set and the Type is PLAIN or not specified the content is output as plain text (and is a text node);
  • if the Type is HIGH_PRIORITY the output will be a strong element;
  • if the Type is MEDIUM_PRIORITY the output will be an em element;
  • if the Type is EMPHASISED the output will be a strong element;
  • if the Type is INSERT the output will be an ins element;
  • if the Type is DELETE the output will be a del element;
  • in all other cases the output will be a span element.

Determining the content category

If the output element is a p element or a pre element then the WStyledText has non-phrasing content and may not be placed in any WComponents which must only contain phrasing content. In all other cases the content category is phrasing content and the WStyledText may be placed in the content of any other WComponent.

Type

The WStyledText Type effects the output element as described above, the decorative style and semantics (if any) of the text. Available settings for the Type property are:

  • PLAIN - no style is applied and this is the default (used in conjunction with the white space mode but does not need to be specified);

    WStyledText Type PLAIN

  • HIGH_PRIORITY - for indicating high priority content;

    WStyledText Type HIGH_PRIORITY

  • MEDIUM_PRIORITY - for indicating medium priority content;

    WStyledText Type MEDIUM_PRIORITY

  • LOW_PRIORITY - for indicating low priority content;

    WStyledText Type LOW_PRIORITY

  • EMPHASISED - for providing emphasized text;

    WStyledText Type EMPHASISED

  • INSERT - for marking inserted text;

    WStyledText Type INSERT

  • DELETE - for marking deleted (or soft-deleted) text;

    WStyledText Type DELETE

  • MANDATORY_INDICATOR - for use as described above;

    WStyledText Type MANDATORY_INDICATOR

  • ACTIVE_INDICATOR - deprecated and not defined;

  • MATCH_INDICATOR - deprecated and not defined.

// with WStyledText text
// set Type INSERT
text.setType(WStyledText.Type.INSERT);

White space modes

The WhitespaceMode is used to set whitespace features in WStyledText. The supported values are:

  • PRESERVE - all whitespace is preserved and the text is monospaced;

    WStyledText WhitespaceMode.PRESERVE

  • PARAGRAPHS - The content of the WStyledText is broken up into one or more paragraphs which are then styled according to the Type. Paragraphs are created at each new line character in the text.

    WStyledText WhitespaceMode.PARAGRAPHS

// with WStyledText text
// set PRESERVE
text.setWhitespaceMode(WStyledText.WhitespaceMode.PRESERVE);

WhitespaceMode is able to be used along with Type but doing so may create usability or accessibility problems. It is strongly recommended that WhitespaceMode should never be used along with Types HIGH_PRIORITY, MEDIUM_PRIORITY or EMPHASISED as this can result in significant usability problems stemming from causing a user to have to read what could be significant blocks of bold or italic text; and may cause accessibility issues for users with audio output as the voice output may be adjusted to highlight strong and/or em elements.

Using WhitespaceMode with any Type other than Type.PLAIN may result in unexpected results. Using WhitespaceMode with Type.MANDATORY_INDICATOR and multi-line content is not guaranteed to work at all (but it might if one is really keen to test it).

Related Components

Further information

Some start pages

Clone this wiki locally