Options Controller

Options Controller is a Stimulus controller for retreiving options data from elsewhere on the page.

Sources

The source data can come from any of the following elements:

Source Data Note
table td by row Use the data-options-colnum attribute to specify a column number.
thead th by column
ul li
ol
select option
datalist
dl label: dt
value: dd
nav a
 The value is the href attribute.
The label is the text content of the link.

Targets

Here is how the controller will output data to different target elements:

Source Data Note
table tr The controller will have the following columns:
  • value
  • label
  • attributes
Note: This output is infomrational only and would ne be expected to be used in production.
ul li
ol
select option
datalist
dl label: dt
value: dd
nav a
 The value is the href attribute.
The label is the text content of the link.

Attributes

HTML Attributes

These are standard HTML attributes (with no prefix) used by the controller.

Attribute Element(s) Default Value(s) Description
aria-busy table
 false true
false
 The controller will set this to true any time it is updating the DOM.
You can use the value in your CSS to indicate that work is in progress.

data- Attributes

All of these attributes are prefixed with "data-" in the attribute name.

Attribute Element(s) Default Value(s) Description
controller (see "Targets" above)
 options This attribute (on either element) provides the controller functionality.

data-options- Attributes

All of these attributes are prefixed with "data-tablesort-" in the attribute name.

Attribute Element(s) Default Value(s) Description
source (root)
 (string) The selector for the parent element holding the source data.
filter (root)
 (string) The selector to apply to each item in the source element.
Only the items that match this selector will be included in the options list.
Example: [data-value] (get only elements with a "data-value" attribute).
attributes (root)
 (string) The attributes to copy from the source elements to the target elements.
Multiple attributes can be separated by a comma.
A value of "*" will copy all attributes.
Example: data-special,style
colnum (root)
 (integer) The column number to use for the source data if the source is a table.
Example: 2
Note: This is a 1-based index, so the first column is 1, not 0.
distinct (root)
 true (boolean) Indicates whether to only include distinct values in the options list.
Example: true
true Only includes distinct values in the options list.
false Includes all values in the options list.
observe (root)
 (selector) The selector for element(s) to observe for changes.
Any time that the element(s) change, the controller will re-fetch the options data.
The controller will respond to changes to the element specified in the "data-options-source" attribute as well as any element(s) specified in this attribute.
selector (root)
 (string) The selector for the individual elements holding the source data.
This should only be used in the event that the "data-options-source" and "data-options-filter" attributes are insufficient.
sort (root)
 (blank) The order in which to sort the options.
(blank) Sorts the options in the order found in the source data.
label Sorts the options by label in ascending order.
label asc
label desc Sorts the options by label in descending order.
value Sorts the options by value in ascending order.
value asc
value desc Sort the options by value in descending order.

Events

options: Events

Event Parameters Description
connected Called any time that the controller is connected.
disconnected Called any time that the controller is disconnected.
fetched Called any time that the controller fetches options data.

Methods

While it is recommended to use the controller via the attributes listed above, the following methods can be called directly if needed.

Method Returns Arguments Event(s) Description
getOptions (array)

Get the options data from the source element.