Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mattiash/angular-tablesort
Sort angularjs tables easily
https://github.com/mattiash/angular-tablesort
Last synced: about 1 month ago
JSON representation
Sort angularjs tables easily
- Host: GitHub
- URL: https://github.com/mattiash/angular-tablesort
- Owner: mattiash
- License: mit
- Created: 2013-08-21T18:32:33.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2023-07-14T18:26:51.000Z (over 1 year ago)
- Last Synced: 2024-10-18T15:25:39.295Z (about 2 months ago)
- Language: HTML
- Size: 216 KB
- Stars: 184
- Watchers: 7
- Forks: 66
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
AngularJS Tablesort
===================
Allow tables to be sorted by clicking their headings.
Web site: [http://mattiash.github.io/angular-tablesort](http://mattiash.github.io/angular-tablesort)
Background
----------
When you use jquery to build your web-pages, it is very easy to add sorting functionality to your tables - include [tablesorter](http://tablesorter.com) and annotate your column headings slightly to tell it what type of data your table contains.
The goal with this module is to make it just as easy to add sorting to AngularJS tables, but with proper use of angular features and not jQuery.
Click once on a heading to sort ascending, twice for descending. Use shift-click to sort on more than one column.
Additionally, these directives also make it easy to add a default row that is shown in empty tables to make
it explicit that the table is intentionally empty and not just broken.
Installation
------------
bower install angular-tablesort
or
npm install angular-tablesort
Usage
-----
Include the script in your markup
```html
```
Include the module in your app
```js
angular.module('myApp', ['tableSort']);
```
The following code generates a table that can be sorted by clicking on the table headings:
```html
Id
Name
Price
Quantity
Date Ordered
#{{item.Id}}
{{item.Name}}
{{item.Price | currency}}
{{item.Quantity}}
{{item.OrderDate | date:"medium"}}
```
The `ts-wrapper` attribute must be set on element that surrounds both the headings and the ng-repeat statement.
The `ts-criteria` attribute tells tablesort which expression it should sort on when that element is clicked. Normally, the ts-criteria is the same as the expression that is shown in the column, but it doesn't have to be. The ts-criteria can also be filtered using the normal AngularJS filter syntax. Tablesort includes three filters `parseInt`, `parseFloat`, and `parseDate`, but any filter can be used.
The `ts-name` attribute can be set to declare a unique name for an expression which will be used in the event fired when sorting has changed.
The `ts-default` attribute can be set on one or more columns to sort on them in ascending order by default.
To sort in descending order, set ts-default to "descending"
The `ts-repeat` attribute must be set on the element with ng-repeat.
```html
```
Alternatively, `ts-repeat-start` and `ts-repeat-end` may be used to compliment the `ng-repeat-start` and `ng-repeat-end` directives.
```html
{{ item.Name }}
{{ item.Description }}
```
By default, the sorting will be done as the last operation in the ng-repeat expression. To override this behavior, use an explicit `tablesort` directive as part of your ng-repeat expression. E.g.
```html
```
This will first select the first 10 items in `items` and then sort them. Alternatively, you can insert an explicit tablesort in the pipe:
```html
```
This will first sort the rows according to your specification and then only show the first 10 rows.
If the `ng-repeat` expression contains a `track by` statement (which is generally a good idea), that expression will
be used to provide a [stable](http://en.wikipedia.org/wiki/Sorting_algorithm#Stability) sort result.
Events
------
When changing sorting in the table, an event named `tablesort:sortOrder` will be emitted which contains an array of all current sorting definitions.
These sorting definitions could be used to set up sorted data retrieval when using other directives that handle things like pagination or filtering.
```js
$scope.$on('tablesort:sortOrder', (event, sortOrder) => {
self.sortOrder = sortOrder.map(o => {
return `${o.name} ${o.order ? 'ASC' : 'DESC'}`;
});
});
```
CSS
---
All table headings that can be sorted on is styled with the css class `tablesort-sortable`. The table headings that the table is currently sorted on is styled with `tablesort-asc` or `tablesort-desc` classes depending on the sort-direction. A stylesheet is included to show that it works, but you probably want to build your own.
Empty Tables
---
By default, the content for the empty table cell is set to `"No Items"`, however it can be changed via the `noDataText` configuration option (see below). It is inserted as one `` spanning
all columns and placed inside a ``, which is placed at the top of each table.
The message can be customized for each table by specifying the `ts-no-data-text` attribute on the same element as the `ts-wrapper`.
```html
```
To disable this feature, add the attribute `ts-hide-no-data` to the `ts-repeat` row:
```html
```
Configuring Global Options
---
Several options may be configured globally per-app.
| Property | Type | Default | Description |
|----------------------|-------------------|------------------------|-------------|
|`filterTemplate` |`string` |`""` |HTML string template for filtering the table. _This will be included **before** the element with `ts-wrapper` specified on it._ See example above.|
|`filterFunction` |`function` |`undefined` |A function that will be called for every item being iterated over in the table. This function will be passed the object being iterated over as the first parameter. It should return a `boolean` value as to include the item or not. _(This can be overridden per-table)_|
|`itemNameSingular` |`string` |`"item"` |The default singular version of the name for the items being iterated over. _(This can be overridden per-table)_|
|`itemNamePlural` |`string` |`itemNameSingular + "s"`|The default plural version of the name for the items being iterated over. This just appends `"s"` to the singular name, which should work for most words in English. _(This can be overridden per-table)_|
|`noDataText` |`string` |`"No " + itemNamePlural`|The text that displays in the `.showIfLast` cell shown when a table is empty. _(This can be overridden per-table)_|
|`wrappingElementClass`|`string` |`""` |Wrap the `` element in a div with this class. If left blank, no element will wrap the table. _(This can be overridden per-table)_|
|`paginationTemplate` |`string` |`""` |HTML string template for paging the table. _This will be included **after** the element with `ts-wrapper` specified on it._ See example above.|
|`perPageOptions` |`array` of `number`|`[10, 25, 50, 100]` |The options for how many items to show on each page of results. _(This can be overridden per-table)_|
|`perPageDefault` |`number` |`perPageOptions[0]` |The default number of items for show on each page of results. By default, it picks the first item in the `perPageOptions` array. _(This can be overridden per-table)_|
Here's an example of how to change an option
```js
angular
.module('myApp')
.config(['tableSortConfigProvider', function(tableSortConfigProvider){
tableSortConfigProvider.noDataText = "This table has nothing to show!";
tableSortConfigProvider.wrappingElementClass = "table-reponsive";
}
]);
```
### Filtering & Pagination Templates
By default, table filtering & pagination are supported, but not enabled so that you may use any UI and any 3rd party angular code to do these types of things.
To set up these features, you must provide some configuration HTML string templates. These will be the default templates for filtering & pagination for all tables use in the same app unless that feature is specifically disabled on a per-table basis.
Here is an example of one way to set up the templates for an app that uses bootstrap and the [Angular-UI Bootstrap pagination directive](http://angular-ui.github.io/bootstrap/#/pagination)
```js
angular
.module('myApp')
.config(['tableSortConfigProvider', function(tableSortConfigProvider){
var filterString = "
";
filterString += "";
filterString += "";
filterString += "";
filterString += "";
filterString += "";
filterString += "";
filterString += "";
tableSortConfigProvider.filterTemplate = filterString;
var pagerString = "
";
pagerString += "Showing {{CURRENT_PAGE_RANGE}} {{FILTERED_COUNT === 0 ? '' : 'of'}} ";
pagerString += "{{TOTAL_COUNT | number}} {{TOTAL_COUNT === 1 ? ITEM_NAME_SINGULAR : ITEM_NAME_PLURAL}}";
pagerString += "{{FILTERED_COUNT | number}} {{FILTERED_COUNT === 1 ? ITEM_NAME_SINGULAR : ITEM_NAME_PLURAL}} (filtered from {{TOTAL_COUNT | number}})";
pagerString += " ";
pagerString += " ";
pagerString += "";
pagerString += "";
pagerString += "";
pagerString += "";
tableSortConfigProvider.paginationTemplate = pagerString;
}
]);
```
There are several tokens that can be used in the templates which will be replaced with the proper Angular expressions.
| Token | Description |
|-----------------------|-------------------------------------------------------------------------------------------------------------|
| `TOTAL_COUNT` | The number for the total count of items in the table |
| `FILTERED_COUNT` | The number for the total count of items in the table after the filter has been applied |
| `FILTER_STRING` | The string used for the `ng-model` of the text filter |
| `PER_PAGE_OPTIONS` | The array of numbers for the various page size options |
| `ITEMS_PER_PAGE` | The number for the selected number of items to display per page (the selected item from `PER_PAGE_OPTIONS`) |
| `CURRENT_PAGE_NUMBER` | The number for the page that is currently being viewed |
| `CURRENT_PAGE_RANGE` | The number for the current viewable range of pages |
| `ITEM_NAME_SINGULAR` | The singular version of the name of the items being iterated over |
| `ITEM_NAME_PLURAL` | The plural version of the name of the items being iterated over |
### Item Names
The name of the things listed in the table can be displayed in the filtering and pagination templates. They are named `"items"` collectively and `"item"` individually by default, but this can be customized in the global config, and per-table to be more specific as to what is being listed.
On a table just set the `ts-item-name` attribute on the same element as `ts-wrapper`. Set this as the singular version of the word, not the plural.
```html
```
The plural version of the word will be automatically generated by adding `"s"` to the end of the singular word. The above example would produce `"product"` and `"products"` This should be fine for many words in English, but in the rare instances where it is not, a `ts-item-name-plural` attribute may also be specified.
```html
```
Changing the item name will also update the "no data" display to be `"No " + ITEM_NAME_PLURAL` _unless_ the globally configured `noDataText` option is in a format other than the default.
Note that expressions can be used for these properties as well. In the below example a translation filter is applied to localize text.
```html
```
### Table Filtering & Pagination Usage
There are a couple of ways to mark a column as filterable.
One approach is to add the `ts-filter` attribute to the `` element. The property specified in the `ts-criteria` attribute will be used to filter.
```html
Id
Name
Price
Quantity
Date Ordered
```
**NOTE** that the `ts-filter` attribute is not needed if custom filtering using the `ts-filter-function` attribute.
Another approach is to add the `ts-filter-fields` attribute to the same element as the `ts-wrapper`. This attribute takes a comma separated list of all the fields to which the filter should be applied.
```html
```
#### Customized Pagination Options
Set the `ts-per-page-options` attribute on the same element that `ts-wrapper` is set on to override the options for the number of items available per page.
Set the `ts-per-page-default` attribute on the same element that `ts-wrapper` is set on to override the default number of items available per page.
```html
```
If filtering or pagination has been configured globally, but you wish to disable either of these features per table you can set `ts-display-filtering="false"` and/or `ts-display-pagination="false"` on the same element as `ts-wrapper`
```html
```
#### Customized Filtering
To have a custom UI for filtering, build the UI around the table however you want and simply provide the `ts-filter-function` attribute with a function that will return a `boolean` for the item being iterated over. This attribute must be set on the same element as `ts-wrapper`
If filtering has been globally configured it is probably a good idea to also set `ts-display-filtering="false"`
**NOTE** that the `ts-filter` attribute is not needed for custom filtering.
```js
$scope.data = [
{id:1, name:"Product A", enabled: false},
{id:2, name:"Product B", enabled: true},
{id:3, name:"Product C", enabled: true}
];
$scope.customFilterValue = "";
$scope.customFilterFn = function(item){
if($scope.customFilterValue == ""){
return true;
} else if($scope.customFilterValue === "false"){
return !item.enabled
} else {
return item.enabled
}
};
```
```html
Enabled
Show All
Only Enabled Products
Only Disabled Products
Id
Name
enabled
{{item.id}}
{{item.name}}
{{item.enabled}}
```
## Wrapping The Table Element
Certain libraries like Bootstrap allow for tables to become responsive when at a smaller screen size by wrapping it in a `table-reponsive` class. If this is desired on a table using angular-tablesort this can become and issue if the filtering or pagination are used since they will also be inside of this wrapping element, which will cause some display issues.
This can be configured globally with the `wrappingElementClass` configuration option, or per-table with the `ts-wrapping-element-class` attribute
```html
```
## Getting Data Out of the Table
To get the current view of the data in the table, pass something to the `ts-get-table-data-function` attribute. Whatever is passed in will be converted into a function.
That function can then be passed as a parameter to a click event function, or anything else. Within the controller, just run that function and it will return the data in the table.
```html
Get the table data
```
In the above example, the click function `ng-click="getTableData(getDataFn)"` would be handled like this:
```js
$scope.getTableData = function (getDataFn) {
var results = getDataFn(true, true, false);
console.log("data from table", results)
};
```
When running the `getDataFn` function, it accepts 3 boolean parameters
1. When `true` the data will come back in the same sort order as the table is currently displaying. When `false` the data will come back in the original sort order (pre-tablesort)
2. When `true` the data will only include items that match the current filters, which will match the current table display. When `false` all items in the table are included regardless of what is currently being filtered.
3. When `true` **and pagination is enabled**, the data will only return the currently viewed page of data. When `false` data from all pages will be returned.
### Customized Sorting
It may be useful to customize how a particular column is sorted. For example, if a column can contain
numbers and strings, you may want the numbers to be sorted numerically and the strings to be sorted
lexicographically. To specify a custom sorting function, add a `ts-order-by` attribute to your
header element:
```html
Name
```
The function specified in the `ts-order-by` attibute should behave in the same way as a custom comparison
function passed to `Array.prototype.sort`. See
[MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort)
for more details.