ListPage Component Reference

Related documents

• Component Overview
• Component Reference
• Built-in Components
• Template Markup Language (TML) Reference
• ListSelector Component Reference
• Page Component Reference
• EditListPage Component Reference

Table of Contents

• Introduction
• Attributes
• Instance methods
  • Inherited methods
  • setValue()
• Children
• DOM element properties
• Styling

Introduction

Syntax

tml`
	<ListPage options=${...}>
		...
	</ListPage>
`

On wide devices or windows, the ListPage component displays a scrollable list that can group items into accordion segments (an ListSelector component) on the left and an area for the list item content on the right. The selection in the list controls the values displayed in the content area. On narrow devices (Nav style: slide), the list and content are two separate pages with navigation elements to move back and forth.

The ListPage component renders a Page. On wide devices, the Page contains an ListSelector component and a separate <div> the ListPage children that form the content area. On narrow devices, Page contains either the ListSelector component or the content area depending on which is currently being displayed.

The ListPage component is similar to the EditListPage component but it uses an ListSelector component instead of a EditListSelector component. This provides a non-editable single or two-level accordion list instead of a user-editable single-level list.

Attributes

• Standard properties (optional)
  The ListPage component accepts the standard attributes.
• listTitle
  The string that will be displayed in the button that exposes the list on narrow devices.
• onClick
  A function to call when an item is selected. The function has the signature fn(value) where value is the value associated with the selected option. The displayed list reflects the newly selected option. The function may subsequently override the selection by setting calling the setValue() method if required.
• options (required)
  An array of options. The options are presented to the user in the same order. Each element can contain a string, a number, or an object. If an element is an object, it contains the following properties:
  • options
    If the element object has an options property, it must contain an array containing strings, numbers, or objects containing both a text property and a value property.
  • text
    The text to display for the option. If text is omitted, then value coerced to a string is used.
  • value

    The value of the state variable if this option is selected.
  

  If an element is a number, the displayed text is the number coerced to a string, and the value is the element. If an element is a string, it is used for both the displayed text and value.

• value
  The value of the selected option in the options array.
• showClickThru
  A Boolean that controls the behavior on narrow devices where either the item list or data is shown, but not both. If true, the selected list item shows a '>' at the end, and a second click will be required to show the data. If false, selecting a list item will show the data immediately. Setting showClickThru to true allows the user to browse and click before editing the data.
• showSelection
  A Boolean that controls whether the currently selected item is highlighted.
• timeout
  A positive numeric value. If valid, then the display of second-level options will be closed if no selection has been made within timeout milliseconds.
• value
  The value of the current selection.
• title
  The string that will be displayed in content bar as the page title.

Instance methods

These methods are intended to be used by parent components to dynamically change the properties of the rendered components without re-rendering.

Inherited methods

• Component methods

setValue()

Syntax

setValue(value)

Sets the rendered element's value.

Parameters

• value
  A Number.

Children

All template children are included as the Page component children. If any child is a PageCol component, then all children must be PageCol components.

DOM element properties

• On wide devices, the ListPage component will render a Page component containing an ListSelector component and a <div> for the content area.
• On narrow devices, the ListPage component will render a Page component containing either an ListSelector component or a <div> for the content area with a header bar <div> for navigation back to the list.
• A device is considered to be narrow when the value of sv.nav_style is 'slide'. Otherwise, it is considered to be wide.
• The content area <div> contain the ListPage component's children.
• The content area <div> will have a CSS class name with the string listPage_contents.

Styling

By default:

• On wide devices the ListSelector component will appear to the left of the content area.
• The content area will be transparent and vertically scrollable.