
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>
Search
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
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. |
paginationShortMode |
data-pagination-short-mode |
true | Pagination display mode. If false, then shows links to all pages in table pagination. |
showActivity |
data-show-activity |
true | Show activity when table sorting. |
muteTable |
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. |
thousandSeparator |
data-thousand-separator |
, |
Thousand separator. |
decimalSeparator |
data-decimal-separator |
. |
Decimal separator. |
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. |
onDrawRow |
data-on-draw-row |
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 tableremoveFilter(filter_index)
- remove filter from tablegetFilters()
- 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>