@substrate/table-renderer
v1.0.0
Published
table-renderer
Downloads
4
Readme
table-renderer
This repository provides React components for rendering tables of JSON data from APIs.
Features
- Dynamically-rendered filters according to the API response
- Pagination
- Sorting
- Automatic vertical/horizontal table scrolling and layout
- Persistent URL-based filters
- Data exporting
- Token-based authentication
How to use
import TableRenderer from "table-renderer/src/TableRenderer"
const MyTable = function () {
return (
<TableRenderer
api={{
fetchEndpoint: "http://foo/api",
exportEncoding: "text/csv; charset=utf-8",
exportExtension: "csv",
exportRequestAcceptHeader: "application/csv",
}}
/>
)
}
Protocol
All the types mentioned below are gathered in the types module.
The basic idea is for the client to send a TableRequest
and the API to reply
with
TableResponse
with success status code on pagination requestsExportResponse
with success status code on export requestsErrorResponse
with error status code for error
Success or failure is determined by the status code and not the shape of the response, which means one should not use a success code for an ErrorResponse and so on.
TableRequest
The request's body is always sent as JSON via POST
.
For Pagination Requests, the response body's format should be JSON and comply
with the structure of TableResponse
.
For Export Requests, the response body's can have any arbitrary content. The response's body will be saved as-is straight into a file and not processed through the application.
TableRequest.filters
The API should include any missing filters in TableRequest.filters
and send
them back in the response; each newly-initialized filter might include its
default initial value.
Normally a clean-slate client (one that does not have saved filters from a
previous run) sends the first request with an empty filters
because it does
not yet know which filters are available in the API.
TableRequest.page
TableRequest.page
is the way to differentiate between Pagination Requests and
Export Requests. It is either:
- A page number, 1-indexed, for paginated browsing; this is what we consider a
Pagination Request and therefore the result should be a
TableResponse
. - The word "all", which signals that the API should export all of the data
according to the filters; this is what we consider an Export Request and
therefore the result should be an
ExportResponse
.
TableRequest.pageSize
The number of items which are included in a page. It should not matter for when
TableRequest.page
is "all".
TableRequest.pageCount
This is the number of total records which were matched according to the
filters divided by TableRequest.pageSize
, rounded up. It should not matter
for when TableRequest.page
is "all".
Example scenario
- The client sends the initial request. In this case it has never used this API before, therefore most fields are empty, but that is not always the case.
{
"page": 1,
"pageSize": 4,
"filters": [],
"sort": null
}
- The API responds with the filled default information
By the returned data, we can infer that there are at most (since it's rounded up) 4 (pageSize) * 2 (pageCount) = 8 records matching the filters, which happen to be empty initially, therefore we can assume there are at most 8 records in total. This response also tells us that the API, by default, sorts the records by "Date" in descending order.
{
"page": 1,
"pageCount": 4,
"pageSize": 2,
"filters": [
{ "name": "Date", "value": { "tag": "ISO8601 date", "value": null } },
{ "name": "Item", "value": { "tag": "number", "value": null } },
]
"data": [
{ "item": 6, "date": "2021-06-06" },
{ "item": 5, "date": "2021-06-05" },
{ "item": 4, "date": "2021-06-04" },
{ "item": 3, "date": "2021-06-03" },
],
"sort": {
"column": "date",
"direction": "desc"
"sortedByDefault": true
}
}
- The client sends a request for exporting the data.
{
"page": "all",
"filters": [],
"sort": null
}
- The API sends an arbitrary response, in this case CSV, which the application will download.
"item","date"
6,"2021-06-06"
5,"2021-06-05"
4,"2021-06-04"
3,"2021-06-03"
2,"2021-06-02"
1,"2021-06-01"
Example project
We plan to have a minimal project showcasing how to set up an API and front-end, but it's not done yet.