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.

...These paragraphs will be sorted

Oslo

Stockholm

Helsinki

Berlin

Rome

Madrid

...The blocks below will not participate in sorting
3
1
2

                    <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>