
Sorter
Use Sorter component to sort an HTML element by content.
About
New in 4.2.8
Sometimes you need to sort the HTML elements by content.
For example, you have a list of <ul>
and you need to sort its elements.
For these purposes in Metro 4 implemented a special component Sorter
, which just solves this problem.
Unsorted list
- Oslo
- Stockholm
- Helsinki
- Berlin
- Rome
- Madrid
Sorted asc
- Oslo
- Stockholm
- Helsinki
- Berlin
- Rome
- Madrid
Sorted desc
- Oslo
- Stockholm
- Helsinki
- Berlin
- Rome
- Madrid
Create sortable element
To create sortable element, you must add role data-role="sorter"
to element and define which elements will be sorted and by what content.
To set sorted elements use attribute data-sort-target="..."
and to set content use attribute data-sort-source="..."
.
By default, sorter
sort elements by asc
. You can setup sort direction with attribute data-sort-dir="asc|desc"
.
Role sorter
For simple ascending sort, add role defining attribute data-role="sorter"
to the element:
<ul data-role="sorter">
<li>Oslo</li>
<li>Stockholm</li>
<li>Helsinki</li>
<li>Berlin</li>
<li>Rome</li>
<li>Madrid</li>
</ul>
Sorter start
By default, sorter start sort immediate after create sorter instance.
If you need starting sort manually, set attribute data-sort-start="false"
.
You can start sorting later using a special method.
- Oslo
- Stockholm
- Helsinki
- Berlin
- Rome
- Madrid
Sort targets
Attribute data-sort-target="..."
defined sub elements who will ben sorted.
This should be the correct element selector: tagName
or className
.
If no attribute is specified, the tagName
property of the first child element will be used as the value.
Oslo
Stockholm
Helsinki
Berlin
Rome
Madrid
...The blocks below will not participate in sorting
<div data-role="sorter" data-sort-target="p">
...These paragraphs will be sorted
<p>Oslo</p>
<p>Stockholm</p>
<p>Helsinki</p>
<p>Berlin</p>
<p>Rome</p>
<p>Madrid</p>
...The blocks below will not participate in sorting
<div>3</div>
<div>1</div>
<div>2</div>
</div>
Sort content
By default for sorting component Sorter
use textContent
property of the sortable elements.
To change it use attribute data-sort-source="..."
.
This should be the correct element selector className
.
- Rome 2
- Oslo 6
- Berlin 3
- Helsinki 4
- Madrid 1
- Stockholm 5
<ul data-role="sorter" data-sort-content="sort">
<li>Rome <span class="sort">2</span></li>
<li>Oslo <span class="sort">6</span> </li>
<li>Berlin <span class="sort">3</span></li>
<li>Helsinki <span class="sort">4</span></li>
<li>Madrid <span class="sort">1</span></li>
<li>Stockholm <span class="sort">5</span></li>
</ul>
Sort direction
By default, sorter
sorts element be ascending
.
To change it, use attribute data-sort-dir="..."
.
Value for this attribute must be asc
or desc
.
- Oslo
- Stockholm
- Helsinki
- Berlin
- Rome
- Madrid
<ul data-role="sorter" data-sort-dir="desc">
<li>Oslo</li>
<li>Stockholm</li>
<li>Helsinki</li>
<li>Berlin</li>
<li>Rome</li>
<li>Madrid</li>
</ul>
Events
When sorter works, it generated the numbers of events. You can use callback for this event to behavior with it.
Event | Data-* | Desc |
---|---|---|
onSorterCreate(el) | data-on-sorter-create |
Fired when sorter was created |
onSortStart(el) | data-on-sort-start |
Fired when sort started |
onSortStop(el) | data-on-sort-stop |
Fired when sort finished |
onSortItemSwitch(i1, i2) | data-on-sort-item-switch |
Fired when sorter switch items |
Methods
You can use Sorter methods ti interact with the sorter component.
- sort(dir) - Sort in specified direction
- reset() - Reset element to initial state before sorting
var sorter = $(el).data('sorter');
sorter.sort('asc');
sorter.sort('desc');
Sorter object
Metro 4 contains special object Metro.sorter
.
This object contains next methods:
- create(el, options) - create Sorter
- isSorter(el) - Check if element is Sorter instance
- sort(el, dir) - Sorting data in specified sorter and direction
...html
<ul id="sortable-list">
<li>Oslo</li>
<li>Stockholm</li>
<li>Helsinki</li>
<li>Berlin</li>
<li>Rome</li>
<li>Madrid</li>
</ul>
...javascript
var sorter = Metro.sorter.create("#sortable-list");
...html
<ul id="sortable-list" data-role="sorter">
<li>Oslo</li>
<li>Stockholm</li>
<li>Helsinki</li>
<li>Berlin</li>
<li>Rome</li>
<li>Madrid</li>
</ul>
...javascript
Metro.sorter.sort("#sortable-list", "asc");
Metro.sorter.sort("#sortable-list", "desc");
Observe sorter attributes
You can change attributes data-sort-dir
and data-sort-content
in runtime to change content sorting.
- Oslo
- Stockholm
- Helsinki
- Berlin
- Rome
- Madrid
<div>
<button class="button"
onclick="$('#sorter-attr').attr('data-sort-dir', 'asc')">
Sort Asc
</button>
<button class="button"
onclick="$('#sorter-attr').attr('data-sort-dir', 'desc')">
Sort Desc
</button>
</div>
<ul data-role="sorter"
data-sort-start="false"
id="sorter-attr">
<li>Oslo</li>
<li>Stockholm</li>
<li>Helsinki</li>
<li>Berlin</li>
<li>Rome</li>
<li>Madrid</li>
</ul>