WDefinitionList
WDefinitionList is a component for creating a read-only list of key:value(s) pairs. This is a one-to-one match with a HTML dl element in which the terms become the HTML dt elements and the data becomes the HTML dd elements.
- Using WDefinitionList
- Creating WDefinitionList
- Terms
- HTML output
- Appearance
- Hiding
- Related components
- Further information
A WDefinitionList is only appropriate for laying out none-interactive content which consists of one or more terms to be defined along with one or more definitions of each term.
If an application design includes editable and read-only versions of input components these should be specified using the interactive versions of the relevant WComponents within a WFieldLayout. The read-only version of this form segment can then be indicated by setting the read-only state of each interactive WComponent in the WFieldLayout.
WDefinitionList may be used to create a naming context rather than using a separate WNamingContext. Obviously one should not use a WDefinitionList as a naming context unless one needs a definition list - it is not a replacement for a generic naming context.
WDefinitionList has two simple constructors. The default constructor creates a WDefinitionList with the default layout. There is an alternate constructor used to specify a layout.
// a default WDefinitionList
WDefinitionList defaultList = new WDefinitionList();
// a stacked list
WDefinitionList stackedList =
new WDefinitionList(WDefinitionList.Type.STACKED);Content is added to a WDefinitionList as a sequence of term:data pairs where data may be plural and a term is a String. The data may be any WComponent(s) (except, of course, WApplication).
// With WDefinitionList `dl` and WComponent `definition`
dl.addTerm("Thing to define", definition);
// a term may have more than one data definition
dl.addTerm("Teapot",
new WText("A vessel for making tea."),
new WText("Something that respond with a 418 to a HTCPCP request."),
new WText("May be in orbit between Mars and Jupiter."));A term:data pair may be removed based on its term.
// With WDefinitionList dl containing a "Teapot" term:
dl.removeTerm("Teapot");A data point for a term may be removed using remove(WComponent). If the last data definition for a term is removed then the term will also be removed.
// Given WDefinitionList dl which contains at least one term
// and there is a handle to a data component`termComponentN`
// within that term:
dl.remove(termComponentN);
// if `termComponentN` was the last data point in its term
// then the term is no longer present in the definition list.Each term may be accessed from a List of Duplets. Ugly but functional. This may be the worst part of WDefinitionLlist. The list is an ArrayList, for what it is worth, so may be iterated to access a particular term. I would like to point you to the JavaDoc at this point but it is pretty poor.
A WDefinitionList outputs a HTML dl element. A definition list is non-phrasing content and must not be used in any context which forbids this content category.
The terms create the HTML dt elements and are restricted to plain text. This is a restriction on the HTML content model for dt but one which provides improved accessibility and usability compared to a rigorous application of the content model and is slightly closer to the HTML4.01/XHTML1.0 content model of a dt element.
We are aware that this restriction on a WDefinitionList term is extremely restrictive compared with the allowed HTML. This content restriction was determined from the original use-cases provided when creating WDefinitionList. As with all WComponents we are open to requests to modify this. Go open an issue and let's discuss your requirements!
The data elements of each term form the list's HTML dd elements and may contain any WComponent. There may be layout implications if large or complex component sets are added to data elements with some layouts. A data component should not consist solely of one or any combination of WComponents without UI artefacts and any term must never have all of its data components be any one or combination of WComponents without UI artefacts.
If your definition list contains WComponents which output interactive form components you may be better served using a WFieldLayout rather than a WDefinitionList.
The layout of the WDefinitionList may be altered using the component's Type property which is a value from the WDefinitionList.Type enum. Available settings are:
-
NORMAL(default): the output will be a default definition list as determined by the user agent. -
FLAT: the terms and data are arranged horizontally. Each term is moved away from the preceding term's data elements by a larger space than that which separates a term from its data. If aFLATWDefinitionList's content reaches the right edge of its contain it will wrap at an element break which may result in data appearing to be orphaned from its term. -
COLUMN: the definition list is arranged in two columns, the first containing the terms and the second the data. Each data element associated with a term occupies a unique block in the data column. The widths of each column are currently fixed in the theme but can be manipulated through custom CSS. -
STACKED: The terms and data are arranged in a single stack. Each data element associated with a term occupies a unique block in the column.
The type may be set using the appropriate constructor or using a setter.
// a default WDefinitionList
WDefinitionList defaultList = new WDefinitionList();
// a stacked list
WDefinitionList stackedList =
new WDefinitionList(WDefinitionList.Type.STACKED);
// Setting the type after instantiation.
// Given WDefinitionList 'list':
// to make it FLAT:
list.setType(WDefinitionList.Type.FLAT);
// to make it STACKED:
list.setType(WDefinitionList.Type.STACKED);
// to make it have COLUMN layout:
list.setType(WDefinitionList.Type.COLUMN);
// to restore the default layout after setting a layout:
list.setType(WDefinitionList.Type.NORMAL);-
WDefinitionList with default layout (as seen in Google Chrome on OS X)
-
WDefinitionList with
FLATlayout
-
WDefinitionList with
COLUMNlayout
-
WDefinitionList with
STACKEDlayout
WDefinitionList is a marginable component.
WDefinitionList may be modified using custom CSS and accepts additional values in the HTML class attribute of the dl element. This should be used with caution, especially if a layout other than Type.NORMAL is used. See WComponents HTML class property.
A WDefinitionList may be hidden on page load. When hidden the WDefinitionList 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 WDefinitionList is hidden all of its content is hidden.