EditListSelector Component Reference

Related documents

• Component Overview
• Component Reference
• Built-in Components
• Template Markup Language (TML) Reference
• ListPage Component Reference

Table of Contents

• Introduction
• Attributes
• Fixed options
• Instance methods
  • Inherited methods
• Children
• DOM element properties

Introduction

Syntax

tml`
	<EditListSelector />
`

The EditListSelector component is a component that renders a <div> with a list of selectable items. The list has a header with buttons that allow editing the list, including:

• Adding items.
• Deleting items.
• Sorting the list of items.
• Manually rearranging the order of the items.

The EditListSelector component must be passed an sVar attribute specifying a Selector input state variable that contains the options and the selected value. The state variable coordinates most list actions, including item selection, item addition, item deletion, and reordering of the item list.

Attributes

• Standard properties
  The EditListSelector component accepts the standard attributes.
• onAdd
  The header 'Edit' and '+' buttons appear only if both onAdd and onDelete are supplied; otherwise the header has a title but no buttons. The '+' button is shown only while the list is not being edited.
  A callback function to be invoked when a new item is requested to be added to the list. The function has no arguments and should add a new entry to the sVar state variable's options. The function can do this asynchronously. For example, it can first ask the user for item name.
• onDelete
  A callback function to be invoked when a list item is is requested to be deleted. The function has one argument containing the value of the option to be deleted. It should delete the option associated with the value from the sVar state variable and set a new selected option, if required. If no options are left, it should do what's required.
• onSort
  A callback function that will be invoked when the list's 'Sort' button is pressed. The function has no arguments and should sort the sVar state variable's options in a standard order. The 'Done' and 'Sort' buttons are shown only while the list is being edited, and 'Sort' only if onSort is supplied.
• onClick
  A callback function that will be invoked when an item is clicked. The function has a single value argument which is the value associated with the clicked item. The sVar state variable is set to the clicked item's value prior to calling the onClick function.
• onClickThru
  A callback function that will be invoked when an already selected item is clicked. If an onClickThru function is defined, all items will show a &rightChevron; symbol while the list is not being edited to indicate that there is information that will be revealed on a second click. When called, the onClickThru function should reveal any desired information.
• title
  A title string that to be displayed on the header at the top of the list.
• sVar
  a Selector input state variable that contains the options and the selected value. An option may carry a fixed property, which holds it at the head of the list and protects it from deletion. See Fixed options.

Fixed options

An option of the sVar state variable may carry a truthy fixed property:

sVar.options([
	{value:'W&B report', text:'W&B report', fixed:true},
	...namedConfigurations,
]);

A fixed option is one the list always offers and the user cannot get rid of or move. It differs from an ordinary option in three ways:

• It is never given a delete button while the list is being edited, so onDelete is never called for it.
• It is never given a drag handle, so it cannot be dragged to another position.
• No other item can be dragged above it. Items dropped over the fixed options settle immediately below them.

The state variable must list its fixed options first: the component holds the head of the list for them but does not reorder the options itself. An option without the property behaves exactly as before, so a list with no fixed options is unaffected.

Use a fixed option for an entry that belongs to the list but is not one of the user's own items, such as a standard entry the application maintains alongside the items the user adds.

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

The EditListSelector component extends Component directly, not the selector base class, so it has no setValue() or getText() methods; the selection is held in the sVar state variable.

Children

The EditListSelector component ignores any children.

DOM element properties

• The EditListSelector component renders a <div> with CSS class string editList_container (plus any className attribute). It contains a header <div class=editList_header> and a <ul> element containing a <li> element for each option.
• The <ul> has the CSS class editList_list, plus editList_list-edit while the list is being edited. Neither element has the listSelector class.
• An <li> element is rendered for each option. Each <li> element has a CSS class string that contains editList_item.
• The selected <li> element (never while editing) will have a CSS class string that contains editList_item-selected. The others will have editList_item-unselected.
• While editing, each non-fixed <li> has a drag handle (editList_itemMove); otherwise, if onClickThru is defined, it has a editList_itemEdit chevron.
• If the options become empty, edit mode is cleared.
• The <li> element of a fixed option contains neither the editList_itemDelete nor the editList_itemMove element while the list is being edited.