WPanel ListLayout

ListLayout is a content layout model for WPanel. It produces a list where each WComponent added to the ListLayout forms one list item. Ordered and unordered lists are able to be made using ListLayout. Lists may be vertical or horizontal and unordered lists have a choice of item dividers.

• WList
  • Repeated Component
• Layout configuration
  • Type
  • Alignment
  • Separator
  • Ordered lists
    • Ordered Lists
  • Spacing
• Empty Cells and hidden components
• HTML output
  • Example HTML
• Related Components
• Further information

WList

WList is a special purpose WComponent for making lists from a repeated component. For all design purposes it is identical to ListLayout and the XML output is identical. WList is a specific form of WRepeater and each item in the list is an instance of the WRepeater's repeated component.

Repeated Component

A WList repeated component may be any WComponent with a UI artefact. It must never consist solely of one or any combination of WComponents without UI artefacts.

Layout configuration

The properties of a ListLayout which effect the rendering are the Type, gap, separator and alignment.

The ordered property is used to create an ordered list. This is a semantic rather than stylistic property: an ordered list should be used only (and whenever) the order of items in a list is meaningful and incremental.

Type

The type property determines the overall display model for a list. Available settings for this property are:

• VERTICAL in which the list is displayed vertically with each item in the list occupying the full width of the parent container

  

• FLAT in which the list items are arranged horizontally and each item occupies only as much space as it needs. The item will compress down to its largest non-wrappable element

  

• STRIPED in which the list is vertical and every second item has a background highlight

  

Alignment

List alignment determines how the items in the list will be aligned in the UI relative to the containing WPanel. Available settings for this property are:

• LEFT in which the list is left aligned relative to the parent container;

  

  

• RIGHT in which the list is right aligned relative to the parent container;

  

  

• CENTER in which the list is center aligned relative to the parent container.

  

  

Separator

The separator property is used to indicate the type of separator (if any) to be used between items in a horizontal list or as markers for each item in a vertical list. The default for this property is to have no separator. If the ordered property is set to make an ordered list then the list markers are fixed in the theme but may be switched off by not setting the separator property.

The default for this setting is to have no marker even for a normal bullet list. Therefore if your design requires item markers for any list this must be explicitly indicated in the UI specification.

• No Separators

  

  

• Dot Separators

  

  

• Bar Separators

  

  

Ordered lists

Lists are, by default, not ordered. To make an ordered list the ordered property is used. If the list is ordered then the separator property will be ignored unless it is NONE and all lists will be numbered as per the user agent default ordering system.

When the list is ordered and the Type is FLAT and the separator is not NONE then the list will be ordered using a generic counter consisting of the incremental count integer followed immediately by a FULL STOP (".") character.

Ordered Lists

• A normal ordered list

  

• A STRIPED ordered list

  

• A FLAT ordered list:

  

Spacing

ListLayout supports a gap property which is used to put space between components in the list. To place space around the ListLayout use its containing WPanel Margin.

The default space between list items depends upon the list type and alignment and is determined by the user agent for vertical lists and the theme for FLAT lists. Any alteration to the default spaces must be specified in the UI specification. When the layout is FLAT the gap is applied to the left of each component cell in the list excluding the first. If the ListLayout components wrap the left gap is still applied. No attempt is made to calculate wrap points and allow for this.

If the layout is not FLAT the gap is applied as a margin to the top of each component cell in the list excluding the first.

See Theme intra component spacing for details of how gaps are applied.

Empty Cells and hidden components

A ListLayout may contain empty cells. These cells are produced when a WComponent is added to a ListLayout but that WComponent has no output into the XML. This may be because the WComponent has no UI consequence or because it is or yet available to the UI.

If the WComponent is not yet available to the UI then the cell is not output into the list and has no UI consequence.

If the WComponent is present in the XML but does not have a UI consequence (such as an WAjaxControl or WSubordinateControl) or is in a hidden state then the item for that component will be present in the list. The cell will be empty but will have a marker (unless separator is NONE) and any gap will be applied. In this case the the empty list items:

• may cause unusual or erroneous layout issues; and
• will have a marker unless Separator.NONE is specified; and
• will cause a significant accessibility issue.

If you specify a ListLayout or WList you should check the markers and spacing between components to ensure that the this has not occurred.

HTML output

ListLayout is always a child of WPanel and WList outputs the same XML so they will exist within the root element of a WPanel. The ListLayout root is an ol element if the list is ordered otherwise a ul element. This element will not have an id attribute but will have the class attribute with value wc-listlayout (same for WList).

When the ListLayout has a gap the root element will have a class value indicating the expected gap type as described in Theme intra component spacing. This will be applied as either a vertical or horizontal gap depending on the layout.

Each cell in the list is a li element. This element will not have an id but will have a class value wc-cell.

Example HTML

The following is typical output for a ListLayout. In this example the list os not oredered, has type FLAT, separator BAR 3 items and a large hgap.

<ul class='wc-listlayout wc-layout-flat wc-hgap-lg wc-listlayout-separator-bar'>
    <li class='wc-cell'>
        <!-- CONTENT HERE -->
    </li>
    <li class='wc-cell'>
        <!-- CONTENT HERE -->
    </li>
    <li class='wc-cell'>
        <!-- CONTENT HERE -->
    </li>
</ul>

Related Components

• WPanel
• BorderLayout
• ColumnLayout
• FlowLayout
• GridLayout
• WRepeater

Further information

• JavaDoc for ListLayout;
• JavaDoc for WList;
• List of WComponents.