- Introduction
- Attributes
- As a stand-alone HTML web component
- Instantiated/data injected via Javascript
- Filter data types
- Data types
filter-sort-table
is a web component that adds filter & sort
functionality to a table.
It's written in TypeScript using Lit HTML & Lit Element.
- Type: {
Array<IHeadConfig>
} - Default: [
empty array
]
When instantiated by Javascript, headConfig
is used to pass column
configuration to the component via an array of
IheadConfig objects.
When <filter-sort-table>
tirggers a change
event, headConfig
can used to provide the current state of the filter/sort controls
to the client application (e.g. Redux).
- Type: {
Array<IObjectScalar>
} - Default: [
empty array
]
When instantiated by Javascript, tableData
is used to pass all the
actual data rendered in the table list via an array of
IObjScalarX objects
- Type: {
boolean
} - Default: [
false
]
When rendering all of the content of the <filter-sort-table>
component in static HTML the html
attribute tells the component
to parse its inner HTML to extract the data that would normally
come from headConfig & tableData
- Type: *{
string
} - Default: [
""
] - (empty string)
Contents of the table's caption
attribute
- Type: {
string
} - Default: [
""
] - (empty string)
Provides infomation (to the client application) of whicht field was last change in the list of filter/sort controls or export controls
Options are:
- name of field - when details of a field are modified
column-sep
- When column separator character for export is changedrow-sep
- When row separator character for export is changed
- Type: {
string
} - Default: [
""
(empty string)]
What was the primary target for the last changed
Options are:
filter
- something in the filter changedmove-column
- table column/filter was moved either left or rightis-column
- Toggle table column visibilitymove-export
- Export column was moved either left or rightin-export
- Toggle field's inclusion in export data
- Type: {
string
} - Default: [
""
(empty string)]
The filter control property that was last changed
- Type: {
boolean
} - Default: [
false
]
Whether or not to allow users to toggle visibility of columns
- Type: {
boolean
} - Default: [
false
]
Whether or not user can change the order of columns
- Type: {
boolean
} - Default: [
false
]
Whether or not to allow users to download the contents of the table as a delimited text file.
- Type: {
string
} - Default: [
"file.tsv"
]
If users are allowed to download the filtered & sorted contents of the table as a file, this provides the default file name for the file.
- Type: {
string
} - Default: [
"\t"
]
Character(s) used to separate column values in export file
- Type: {
string
} - Default: [
"\n"
]
Character(s) used to separate rows in export file
- Type: {
boolean
} - Default: [
false
]
Whether or not to omit the column header row from export file
- Type: {
boolean
} - Default: [
false
]
If data is injected into the component after the HTML for the component is rendered, this tells the component to rerun all the initialisation code.
- Type: {
callback function
|undefined
} - Default: [
undefined
]
If links are rendered by the component but need to have custom handling by the client application, this allows the client application to provide a custom link handler for all links.
Just wrap your table in <filter-sort-table id="foo" html>
e.g.
<filter-sort-table id="foo" html>
<table>
<thead>
<tr>...</tr>
</thead>
<tbody>
...
</tbody>
</table>
</filter-sort-table>
- The table must be a simple two dimensional table.
- It requires the table to have both
<THEAD>
&<TBODY>
elements. <THEAD>
elements should only contain a single<TR>
(NOTE: Only the last
<TR>
in the<THEAD>
is parsed)- For columns to be filterable, each column header must have a
type
data attrubte (e.g.data-type
) see data types for allowed values - Each filterable column must have either a
data-field
orid
attribute so data can be matched up - If defining preset filter states for a column, data attributes can be applied for each IListCtrlItem property
Note: the
html
boolean attribute. This is required for filter-sort-table to know it has to parse its inner HTML to get the data need for filtering & sorting
<filter-sort-table id="users" html>
<table>
<thead>
<tr>
<th data-type="number" id="id">ID</th>
<th data-type="text" id="user-name">User name</th>
<th data-type="date" id="last-login">Last login</th>
<th data-type="bool" id="logged-in">Is logged in</th>
<th data-type="option" id="type" data-optionlist="1:Basic;2:Admin;3:Super">
User type
</th>
<th data-type="date" id="created">Created</th>
</tr>
</thead>
<tbody>
<tr>
<th>1</th>
<td>Ada Lovelace</td>
<td>1852-11-27</td>
<td>No</td>
<td>Super</td>
<td>1815-12-10</td>
</tr>
<tr>
<th>2</th>
<td>Carles Babbage</td>
<td>1871-10-18</td>
<td>No</td>
<td>Admin</td>
<td>1791-12-26</td>
</tr>
<tr>
<th>3</th>
<td>Alan Turing</td>
<td>1954-06-07</td>
<td>No</td>
<td>Admin</td>
<td>1912-06-23</td>
</tr>
<tr>
<th>4</th>
<td>Evan Wills</td>
<td>2022-07-09</td>
<td>Yes</td>
<td>Basic</td>
<td>2021-09-12</td>
</tr>
</tbody>
</table>
</filter-sort-table>
If instantiated via lit html, only two properties need to be set:
headConfig
- A list of columns & filter controls for every field you want to be filterable and column you wish to be visible to the user.tableData
- A list of Data for each row in the table
<filter-sort-table id="foo" .headconfig=${columnData} .tabledata=${tableData}></filter-sort-table>
If <filter-sort-table id="foo">
is already in the HTML and you just need to inject data, as well as setting both headConfig
& tableData
, you also need to set doInit
to true to force FilterSortTable
to do all the initialisation. This is because, by the time the HTML is rendered, all the initialisation should have already been done &doInit
has been set to FALSE
.
text
- field data is simple textnumber
- field data is numeric (can be filtered on either single value or between min & max)date
- field data is a date only value (can be filtered on either single value or between min & max)datetime
- field data is a date/time only value (can be filtered on either single value or between min & max)bool
- TRUE/FALSE, YES/NO type fieldoption
- field data can only be one of a limited number of optionscount
- Works likenumber
type (only used when field data contains a child array and you want to filter on the number of items in the array)
(Also called UDataType
)
List Control Items are used to control filtering & sorting for individual columns or hidden fields in the table.
interface IListCtrlItem {
/**
* Whether or not this control item is currently active
*/
skip: boolean,
/**
* Property name of the field being filtered/sorted
*/
field: string,
/**
* Type of data the control applies to
*
* * text
* * number
* * date
* * datetime
* * bool
* * option
* * count
*/
type: UDataType,
/**
* Normally, empty values are ignored. This causes only items with
* empty values to be included in the list
*/
filterOnEmpty: boolean,
/**
* Value on which to filter
*/
filter: string|number,
/**
* For date & number fields this sets the lower limit of values
*/
min: number,
/**
* For date & number fields this sets the upper limit of values
*/
max: number,
/**
* Control how to filter boolean values
*/
bool: UBoolState,
/**
* For fields that represent a fixed set of options, this allows
* users to filter on multiple options
*/
options: IListCtrlOptionItem[],
/**
* Field sort state
* * 1 - Descending
* * 0 - ignore
* * -1 - ascending
*/
order: UBoolState,
/**
* for fixed option fields, whether or not to order option label
* or value
*/
orderByValue: boolean,
/**
* The order in which sorting occurs
* The lower the priority the earlier it gets sorted
*
* -1 = no sorting
*/
orderPriority: number
}
UBoolState
is used for filtering boolean values (and sorting direction)
0
- Ignore1
- TRUE (or Decending, when used for sorting)-1
- FALSE (or Ascending, when used for sorting)
Option filters allow you to include multiple values in the filtered list (i.e. options can be combined in an OR
filter)
interface IListCtrlOptionItem {
/**
* ID of the option being filtered on
*/
id: number,
/**
* Whether the option should be
* * ignored or
* * Included if selected or
* * Excluded if selected
*/
mode: UBoolState
}
IHeadConfig
represents configuration for one field (column) in an object that is to be rendered in a table row.
NOTE: Because tables can hold more columns than can be rendered conveniently. It's possible to hide columns but still filter & sort on those columns.
interface IHeadConfig extends IListCtrlItem {
/**
* Column header text
*/
label: string,
/**
* Whether or not this field should be included as a column in the
* table
*/
isColumn: boolean,
/**
* Whether or not this field should be included as a column in the
* table
*/
isFilter: boolean,
/**
* If this is not empty, the value of the cell will be linked to
* the URL held in the field this references
*/
urlField ? : string,
/**
* List of option IDs and labels
*/
enumList ? : Array<IDbEnum>,
/**
* Whether or not this control item is currently active
*/
skip: boolean,
/**
* Property name of the field being filtered/sorted
*/
field: string,
/**
* Type of data the control applies to
*
* * text
* * number
* * date
* * datetime
* * bool
* * option
* * count
*/
type: UDataType,
/**
* Normally, empty values are ignored. This causes only items with
* empty values to be included in the list
*/
filterOnEmpty: boolean,
/**
* Value on which to filter
*/
filter: string|number,
/**
* For date & number fields this sets the lower limit of values
*/
min: number,
/**
* For date & number fields this sets the upper limit of values
*/
max: number,
/**
* Control how to filter boolean values
*/
bool: UBoolState,
/**
* For fields that represent a fixed set of options, this allows
* users to filter on multiple options
*/
options: IListCtrlOptionItem[],
/**
* Field sort state
* * 1 - Descending
* * 0 - ignore
* * -1 - ascending
*/
order: UBoolState,
/**
* for fixed option fields, whether or not to order option label
* or value
*/
orderByValue: boolean,
/**
* The order in which sorting occurs
* The lower the priority the earlier it gets sorted
*
* -1 = no sorting
*/
orderPriority: number
}
Client specified list of properties & values for each row in the table
interface IObjScalarX {
/**
* Column/Filter name & data
*/
[index: string]: UScalarX
}
type UScalarX = string | number | boolean | IObjScalarX | Array<string> | Array<any>;
`