foundation-selections¶
foundation-selections
is a vocabulary about the concept of selection, which is built on top of foundation-collection.
Markup¶
.foundation-selections-item¶
Indicates the element is selected. It MUST be applied to .foundation-collection-item
element. foundation-selections-change
event MUST be triggered after modifying the selection status. See foundation-selections-change
event section for details.
Selector Rule:
.foundation-collection-item.foundation-selections-item
[data-foundation-selections-mode]¶
Indicates the selection mode of the collection. It MUST be applied to .foundation-collection
element. The valid values are:
- single
- Only maximum single selection allowed
- multiple (default)
- Zero or more selection allowed
Selector Rule:
.foundation-collection[data-foundation-selections-mode]
[data-foundation-selections-selectall-mode]¶
Indicates whether the collection is in “Select All” mode or not. If the mode is enabled, then the items that are not loaded yet into the collection (e.g. in the pagination scenario) are considered as selected. Once enabled, deselecting some items doesn’t turn off the mode. It can be turned off by clearing all selections.
The valid values are:
- true
- When “Select All” mode is enabled.
- false (default)
- When “Select All” mode is disabled.
Selector Rule:
.foundation-collection[data-foundation-selections-selectall-mode]
Event¶
foundation-selections-change¶
This event MUST be triggered after modifying the selection status of .foundation-selections-item
element(s) at .foundation-collection
element. The event MAY be triggered once after all the items are finished modified (i.e. modifying by batch).
AdaptTo Interface¶
- type
foundation-selections
- condition
.foundation-collection
- returned type
FoundationSelections
interface FoundationSelections {
/**
* Returns the count of selected items. In Select All mode, the method will return the <code>FoundationCollectionPagination.guessTotal</code> number, if available.
*/
count(): number;
/**
* Selects all the elements from the corresponding collection. This method will trigger <code>foundation-selections-change</code> event.
*
* @param suppressEvent Suppress <code>foundation-selections-change</code> event. Note that if you suppress the event, you are still required to trigger the event yourself as mandated by the vocabulary.
*/
selectAll(suppressEvent = false): void;
/**
* Clears the selections. This method will trigger <code>foundation-selections-change</code> event.
*
* @param suppressEvent Suppress <code>foundation-selections-change</code> event. Note that if you suppress the event, you are still required to trigger the event yourself as mandated by the vocabulary.
*/
clear(suppressEvent = false): void;
/**
* Selects the given element. This method will trigger <code>foundation-selections-change</code> event.
* The element MUST be a <code>.foundation-collection-item</code>.
*/
select(el: Element): void;
/**
* Deselects the given element. This method will trigger <code>foundation-selections-change</code> event.
* The element MUST be a <code>.foundation-collection-item</code>.
*/
deselect(el: Element): void;
/**
* Returns <code>true</code> if all the items of the collection, including the ones yet to be loaded (due to pagination), are selected; <code>false</code> otherwise.
*
* ========================= ================== ============== ============
* All Loaded Items Selected Pagination#hasNext SelectAll Mode Return Value
* ========================= ================== ============== ============
* Yes ``true`` ``true`` ``true``
* Yes ``true`` ``false`` ``false``
* Yes ``false`` n/a ``true``
* No n/a n/a ``false``
*/
isAllSelected(): boolean;
}
ARIA¶
When the .foundation-collection
element is also [role=listbox]
—i.e. the element is satisfying .foundation-collection[role=listbox]
selector—during foundation-selections-change
event, the [aria-selected]
of .foundation-collection-item
is set according to the selected state of the item (based on .foundation-selections-item
).
Also the validation of .foundation-collection
element is also performed during that event.
Note for the above features, since they can be implemented generically to only depend on foundation-selections
vocabulary, they are provided OOTB. Implementor doesn’t need to implement them.