Table component

Create interactive table with sorting, filtering and pagination features.

About

New in 4.2.8

If you need to create interactive table with filtering, searching and pagination features, you can use Metro 4 table component. To create its table, add attribute data-role="table" to your HTML table element and setup, if need, additional options with special attributes. An important condition is the creation of sections thead and tbody.

Name Office Age Start date Salary
Tiger Nixon Edinburgh 61 2011/04/25 $320,800
Garrett Winters Tokyo 63 2011/07/25 $170,750
Ashton Cox San Francisco 66 2009/01/12 $86,000
Cedric Kelly Edinburgh 22 2012/03/29 $433,060
Airi Satou Tokyo 33 2008/11/28 $162,700
Brielle Williamson New York 61 2012/12/02 $372,000
Herrod Chandler San Francisco 59 2012/08/06 $137,500
Rhona Davidson Tokyo 55 2010/10/14 $327,900
Colleen Hurst San Francisco 39 2009/09/15 $205,500
Sonya Frost Edinburgh 23 2008/12/13 $103,600
Name Office Age Start date Salary

                    <table class="table striped table-border mt-4"
                           data-role="table"
                           data-cls-table-top="row flex-nowrap"
                           data-cls-search="cell-md-8"
                           data-cls-rows-count="cell-md-4"
                           data-rows="5"
                           data-rows-steps="5, 10">
                        <thead>
                        <tr>
                            <th class="sortable-column sort-asc">Name</th>
                            <th class="sortable-column">Office</th>
                            <th class="sortable-column" data-format="number">Age</th>
                            <th class="sortable-column" data-format="date">Start date</th>
                            <th class="sortable-column" data-format="money">Salary</th>
                        </tr>
                        </thead>
                        <tbody>
                        <tr>
                            <td>Tiger Nixon</td>
                            <td>Edinburgh</td>
                            <td>61</td>
                            <td>2011/04/25</td>
                            <td>$320,800</td>
                        </tr>
                        ...
                        </tbody>
                        <tfoot>
                        <tr>
                            <th>Name</th>
                            <th>Office</th>
                            <th>Age</th>
                            <th>Start date</th>
                            <th>Salary</th>
                        </tr>
                        </tfoot>
                    </table>
                

Sorting

To be able to sort the table, you need to create the correct header for this table. To create header use tags <thead>, <tr> and <th>. To make the column sortable, you must add the .sortable-column class to the header cell. If you want to immediately sort the table by one of the fields, add the sorting direction to the desired cell using the sort-asc or sort-desc classes.


                    <table ...>
                        <thead>
                        <tr>
                            <th class="sortable-column sort-asc">Name</th>
                            <th>Office</th>
                            <th>Age</th>
                            <th>Start date</th>
                            <th>Salary</th>
                        </tr>
                        </thead>
                        ...
                    </table>
                

For right sorting specified fields (ex: formatted money, date), you can add attribute data-format to header cell. You can use next formats to a field: number, int, float, date and money.


                    <table ...>
                        <thead>
                        <tr>
                            <th class="sortable-column sort-asc">Name</th>
                            <th class="sortable-column">Office</th>
                            <th class="sortable-column" data-format="number">Age</th>
                            <th class="sortable-column" data-format="date">Start date</th>
                            <th class="sortable-column" data-format="money">Salary</th>
                        </tr>
                        </thead>
                        ...
                    </table>
                

When component works, it creates special search block before a table. This block is created automatically, but you can control its visibility using special component attributes. To hide this block, set attribute data-show-search to false or define custom wrapper.


                    <table data-role="table" data-show-search="false">
                        ...
                    </table>
                

You can specify your own search field with attribute data-search-wrapper="...". Value for this attribute must be a valid element selector - className or ID.

Rows counter

When component works, it creates special select block before a table to set displayed table rows count. You can change default rows counter steps with attribute data-rows-steps="...". This is a comma delimiter value. To set a default rows count, use attribute data-rows="..." To hide this block, set attribute data-show-rows-steps to false or define custom wrapper.


                    <table data-role="table"
                        data-rows-steps="10, 20, 30, 100"
                        data-rows="20">
                        ...
                    </table>
                

You can specify your own rows counter with attribute data-rows-wrapper="...". Value for this attribute must be a valid element selector - className or ID.

Table info

When component works, it creates special block after a table to display table info. You can set custom text for this block with attribute data-table-info-title="...". By default displayed Showing $1 to $2 of $3 entries. To hide this block, set attribute data-show-table-info to false or define custom wrapper.


                    <table data-role="table"
                        data-table-info-title="$1 to $2 from $3">
                        ...
                    </table>
                

Paging block

When component works, his create special paging block after a table. This block contains pagination section. This block is created automatically, but you can control its visibility using special component attributes. To hide this block, set attribute data-show-pagination to false or define custom wrapper.


                    <table data-role="table" data-show-pagination="false">
                        ...
                    </table>
                

External data

Metro 4 table component supports loading data from external resource. The external resource must return a valid JSON object in specific format. To load external table data, use attribute data-source="...".


                    <table data-role="table"
                        data-source="https://domain.com/data.json">
                        ...
                    </table>
                

Data format

The external resource must return a valid JSON object in specific format:


                    {
                        "header": [...],
                        "data": [...],
                        "footer": [...]
                    }
                

Header section

The header section defines table head columns and additional classes for a related cells in table body. Header section has next format:


                    "header": [
                        {
                          "name": ..., // string
                          "title": ..., // string
                          "sortable": ..., // true or false
                          "sortDir": ..., // string - "asc" or "desc"
                          "size": ..., // int, column width
                          "cls": ..., // additional class for header cell
                          "clsColumn": ...,  // additional class for related cells in table body
                          "format": ... // string define column format for right sorting
                        },
                        ...
                    ]
                
Example

                    {
                      "header": [
                        {
                          "name": "name",
                          "title": "Name",
                          "sortable": true,
                          "sortDir": "asc",
                          "size": 200
                        },
                        {
                          "name": "company",
                          "title": "Company",
                          "sortable": true,
                          "clsColumn": "d-none d-table-cell-md"
                        },
                        ...
                      ],
                      ...
                    }
                

Data section

Data section defines a table rows. Each row represent as array of values.


                    {
                      "header": [...],

                      "data": [
                        [
                          "Merrill Hartman",
                          "Placerat Cras Dictum Foundation",
                          "Barasat",
                          21,
                          "2009/07/05",
                          "$8,969"
                        ],
                        [
                          "Hayes Christian",
                          "Vehicula Et Rutrum Corp.",
                          "Canela",
                          24,
                          "2006/08/27",
                          "$9,726"
                        ],
                        ...
                      ],

                      "footer": [...]
                    }
                

Footer section defines a table footer cells.


                    "footer": [
                        {
                          "name": ..., // string
                          "title": ..., // string
                          "cls": ..., // additional class for header cell
                        },
                        ...
                    ]
                

Options

You can change behavior of your table with any options. To these options you can use special attributes.

Option Data-* Default Desc
source data-source Define external data for table.
searchInput data-search-input Define a element selector for custom search input.
search data-search true Show/hide table search block.
pagination data-pagination true Show/hide table paging block.
showRowsSteps data-show-rows-steps true Show/hide rows steps select.
showSearch data-show-search true Show/hide search input.
showTableInfo data-show-table-info true Show/hide table info.
showPagination data-show-pagination true Show/hide table pagination.
showAllPages data-show-all-pages true Show all pages in table pagination.
showActivity data-show-activity true Show activity when table sorting.
mute-table data-mute-table true Mute table body when table sorting.
rows data-rows 10 Default value for rows counter.
rowsSteps data-rows-steps 10,25,50,100 Values for rows counter.
sortDir data-sort-dir asc Default sort direction.
tableRowsCountTitle data-table-rows-count-title Show entries: Title for rows counter.
tableSearchTitle data-table-search-title Search: Title for search input.
tableInfoTitle data-table-info-title Showing $1 to $2 of $3 entries Title for table info block.
paginationPrevTitle data-pagination-prev-title Prev Title for table pagination prev button.
paginationNextTitle data-pagination-next-title Prev Title for table pagination next button.
activityType data-activity-type cycle Set activity type.
activityStyle data-activity-style color Set activity style.

Events

When table works, it generates a series of events that you can use to interact with the component.

Option Data-* Desc
onDraw data-on-draw Event fired when the table was drawn.
onDrawItem data-on-draw-item Event fired when row added to the table.
onSortStart data-on-sort-start Event fired when sorting process stated.
onSortStop data-on-sort-stop Event fired when sorting process stopped.
onSortItemSwitch data-on-sort-item-switch Event fired when table rows switched on sorting process.
onSearch(filter, items) data-on-search Event fired on search.
onRowsCountChange(val) data-on-rows-count-change Event fired when user change rows count to display.
onDataLoad(source) data-on-data-load Event fired before data will be loaded.
onDataLoaded(source, response) data-on-data-loaded Event fired after data loaded.
onTableCreate(el) data-on-table-create Event fired after the table created.

Methods

You can use table methods to interact with it.

  • sorting(dir)
  • filter(val)
  • loadData(source)
  • next()
  • prev()
  • first()
  • last()
  • page(num)
  • draw()
  • addFilter(func)
  • removeFilter(func_index)
  • getFilters()

Filters

You can add custom filters to your table component with a special attributes and methods. To set custom filters, use attributes data-filter and data-filters.

Attribute data-filter set one filter, attribute data-filters set the number of filters. Value for data-filter must be valid function name, and for data-filters - comma separated functions name list.


                    <table data-role="table" data-filter="myFilterFunc">...</table>

                    <table data-role="table" data-filters="myFilters.Func1, myFilters.Func2">...</table>

                    ...javascript
                    function myFilterFunc(row){...}

                    var myFilters = {
                        Func1: function(row){...},
                        Func2: function(row){...}
                    }

                

Component contains next methods to work with custom filters: addFilter(func), removeFilter(func) and getFilters().

...html


                    <div>
                        <button class="button" onclick="addFilter()">Add filter</button>
                        <button class="button" onclick="removeFilter()">Remove filter</button>
                    </div>
                    <table id="filtersExample" class="table table-border mt-2"
                           data-role="table" data-source="data/table.json"
                           data-rows="5" data-rows-steps="5">
                    </table>
                

...JavaScript


                    var customFilterTable = $('#filtersExample').data('table');
                    var filterIndex;

                    function addFilter(){
                        filterIndex = customFilterTable.addFilter(function(row){
                            return Metro.utils.between(row[3], 20, 30);
                        });
                        customFilterTable.draw();
                    }
                    function removeFilter(){
                        customFilterTable.removeFilter(filterIndex);
                        customFilterTable.draw();
                    }
                

The methods have the following purpose:

  • addFilter(func) - add filter to table
  • removeFilter(filter_index) - remove filter from table
  • getFilters() - get filters as array

Customize

You can customize style of table and its elements with next options:

Option Data-* Desc
clsComponent data-cls-component Additional class for component
clsTable data-cls-table Additional class for table
clsHead data-cls-head Additional class for table head
clsHeadRow data-cls-head-row Additional class for table head row
clsHeadCell data-cls-head-cell Additional class for table head cell
clsBody data-cls-body Additional class for table body
clsBodyRow data-cls-body-row Additional class for table body row
clsBodyCell data-cls-body-cell Additional class for table body cell
clsFooter data-cls-footer Additional class for table footer
clsFooterRow data-cls-footer-row Additional class for table footer row
clsFooterCell data-cls-footer-cell Additional class for table footer cell
clsPagination data-cls-pagination Additional class for table pagination
clsTableTop data-cls-table-top Additional class for table top block
clsTableBottom data-cls-table-bottom Additional class for table bottom block
clsTableInfo data-cls-table-info Additional class for table info block
clsTablePagination data-cls-table-pagination Additional class for table pagination block
clsRowsCount data-cls-rows-count Additional class for rows count block
clsSearch data-cls-search Additional class for search block

Custom elements wrappers

You can set custom wrappers for search, rows counter, table info and pagination elements. To set it, use special named attributes: data-search-wrapper, data-rows-wrapper, data-info-wrapper, data-pagination-wrapper.


                    <div class="row mb-2">
                        <div class="cell-md-8 my-search-wrapper"></div>
                        <div class="cell-md-4 my-rows-wrapper"></div>
                    </div>
                    <p class="h3 text-center my-info-wrapper"></p>
                    <div class="d-flex flex-justify-center my-pagination-wrapper"></div>
                    <table class="table table-border striped"
                           data-role="table"
                           data-rows-steps="5, 10"
                           data-rows="5"
                           data-info-wrapper=".my-info-wrapper"
                           data-pagination-wrapper=".my-pagination-wrapper"
                           data-search-wrapper=".my-search-wrapper"
                           data-rows-wrapper=".my-rows-wrapper"
                           data-source="data/table.json">
                    </table>
                    <div class="d-flex flex-justify-center my-pagination-wrapper"></div>