WFigure
WFigure is a component for adding a section of content, usually graphical, which is able to be associated with a labelling element.
- When to use
- Creating WFigure
- Accessibility
- Appearance
- HTML output
- Hiding
- Performance optimisation
- Further information
The most common use of WFigure is to contain a piece of content, often non-text content, which is referred to by a caption or description so that it may be referenced on another part of the document or so that an extended description may be provided to non-visual UAs.
According to the HTML specification:
The figure element represents some flow content, optionally with a caption, that is self-contained (like a complete sentence) and is typically referenced as a single unit from the main flow of the document.
The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc.
Some (non-exhaustive) sample use cases could include:
- a captioned image;
- an interactive or code-generated chart with a caption or description;
- to provide a caption or description to a piece of content which is rendered as text when part of the description is moved out of the viewport for design reasons but must still be available for non-visual UAs.
From the specification again:
When a figure is referred to from the main content of the document by identifying it by its caption (e.g. by figure number), it enables such content to be easily moved away from that primary content, e.g. to the side of the page, to dedicated pages, or to an appendix, without affecting the flow of the document.
If a figure element is referenced by its relative position, e.g. "in the photograph above" or "as the next figure shows", then moving the figure would disrupt the page's meaning. Authors are encouraged to consider using labels to refer to figures, rather than using such relative references, so that the page can easily be restyled without affecting the page's meaning.
WFigure has two constructors both of which require the content component and a label.
The first constructor uses a String to create a text caption for the content.
// Assume some content, perhaps a graph, in a WContainer `container`
WFigure figure = new WFigure(container,
"Description of the graph");The other constructor accepts a WDecoratedLabel as the labelling component which allows more complex captioning.
// Assume some content, perhaps a graph, in a WContainer `container` and
// WDecoratedLabel `graphLabel` containing the caption content.
WFigure figure = new WFigure(container, graphLabel);A primary purpose of WFigure is to ensure content is accessible, especially non-text content. WFigure was created to make it easier to include graphical and image based content in an application in an accessible way.
To ensure this accessibility it is important that the WFigure's captioning component does indeed provide an adequate palpable caption for the content of the WFigure. It is preferable that much of this caption be text. Some of the caption may be moved out of viewport if the purpose and intent of the content is adequately provided to graphical user agents by context or within the content itself.
WFigure is a generic container, though with a slightly specialised purpose, therefore it is difficult to provide a typical use case screen shot. This image shows a simple WFigure containing an image and a caption which can then be referenced from outside the figure.
WFigure is a marginable component.
WFigure outputs a HTML figure element. The WFigure's labelling element outputs a HTML figcaption element.
The WFigure's labelling element must comply with the following requirements:
- the content must comply with all restrictions and requirements of the HTML figcaption element;
- the content must provide an adequate caption for the WFigure's content.
A WFigure may be hidden on page load. When hidden the WFigure is not available to any compliant user agent. It is present in the source and is not obscured in any way. This property is determined by a WSubordinateControl. When a WFigure is hidden all of its content is hidden.
WFigure has a Mode property which indicates how the WFigure's content is loaded. This is important in ensuring optimal performance of your applications and the mode should be explicitly specified for every WFigure. Details of the various modes are in [Ajax modes]].
The following [Ajax modes]] are supported:
-
CLIENT(the default); -
LAZY; and -
EAGER.
For more information about Modes, performance implications, and determining the correct mode to specify see Ajax modes.
// set EAGER mode on WFigure `figure`
figure.setMode(FigureMode.EAGER);