# certara-table
## Usage
### Data-examples
#### Data and Columns for `certara-table`
Most options can be set with `html` attributes, but to populate `certara-table` in an HTML context, data need to be configured for the `data` and `columns` properties.
```html
```
This can be done with arrays...
```js
const tableExample = document.querySelector('#table-example');
// Columns array
const myColumns = ['Name', 'Email', 'Licenses'];
// Table data array of arrays
const myData = [
['Jean', 'jean@example.com', 12],
['Marc', 'marc@gmail.com', 2],
];
tableExample.columns = myColumns;
tableExample.data = myData;
```
Or with arrays of objects, which offer specific properties for more complex table features, like column header labels using the `name` property, among others.
```js
const myColumnsFormatted = [
{ id: 'name', name: 'First Name' },
{ id: 'email', name: 'E-mail' },
];
const myDataObject = [
{ name: 'John', email: 'john@example.com', licenses: 12, refund: '100' },
{ name: 'Mark', email: 'mark@gmail.com', licenses: 2, refund: '47.16' },
];
tableExample.columns = myColumnsFormatted;
tableExample.data = myDataObject;
```
##### Cell alignment
Cell data alignment defaults to left, but right and center alignment can be had using `data-align: right|center` within the `attributes` object. NOTE: standard CSS modifiers like `text-right`/`text-center` break the `fixedHeader` functionality.
```js
const myColumnsFormatted = [
{
id: 'licenses',
name: 'Licenses',
attributes: { 'data-align': 'right' },
},
];
```
#### Data formatting
Formatted data can be had by using standard JavaScript techniques, like [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) with the `formatter` callback. Below, we're formatting the data to display as `USD`, with localized separators and units (e.g., `10000` returns as `$10,000.000`).
```js
const myColumnsFormatted = [
{
id: 'refund',
name: 'Refund',
formatter: cell => new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(cell),
},
];
```
##### Complex sorting
Simple sorting is available by including the `sort` attribute on ``, but more complex sorting logic can be accomplished using the `sort` property within a `columns` object. In this example, we're sorting a currency data type, so the data need to be converted to an integer first. More details at the GridJS docs.
```js
const myColumnsFormatted = [
{
id: 'refund',
name: 'Refund',
formatter: cell => new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(cell),
sort: {
compare: (a, b) => {
const amt = x => parseInt(x, 10);
if (amt(a) > amt(b)) {
return 1;
} else if (amt(b) > amt(a)) {
return -1;
} else {
return 0;
}
},
},
},
];
```
## Properties
| Property | Attribute | Description | Type | Default |
| ----------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------------------------- |
| `autoRefresh` | `auto-refresh` | Automatically refresh the table when the data prop changes | `boolean` | `true` |
| `bordered` | `bordered` | Puts borders between table data cells | `boolean` | `false` |
| `columns` | -- | Column names (strings) or column config objects. See https://gridjs.io/docs/config/columns. Set with JS when the component is used in an HTML context. \nAdditionally, `copy` and `download` properties on the column object can be set to `true` or a callback function `(cellData) => string` for the `copyTableToClipboard` and `downloadTable` methods. | `(string \| TableColumn)[]` | `undefined` |
| `data` | -- | Can be an array of arrays, or an array of objects. This needs to be set with JS when the component is in an HTML context | `any[]` | `undefined` |
| `fixedHeader` | `fixed-header` | Fixed headers also require a set `height` | `boolean` | `false` |
| `from` | -- | Reference to an existing HTML `` element to use as the data source. GridJS will read the data from this table. Alternatively, place a `` element as a child of `` and it will be auto-detected. See: https://gridjs.io/docs/examples/from | `HTMLTableElement` | `undefined` |
| `fullHeight` | `full-height` | The table container will stretch to the full height of the viewport | `boolean` | `true` |
| `height` | `height` | Set `height` with CSS units (e.g. `400px`) | `string` | `undefined` |
| `offsetY` | `offset-y` | Offset to stretch table to fill available vertical space aside from reserved space for toolbars, etc. (e.g., `230px`) | `string` | `undefined` |
| `pagination` | `pagination` | Set to true to show pagination, configure extended options with the JS object ([Docs](https://gridjs.io/docs/config/pagination)) | `boolean \| object` | `undefined` |
| `paginationPageSizes` | -- | Page-size options for the pagination footer dropdown (e.g. `[50, 100, 'all']`). Applies when `pagination` is enabled. | `TablePageSize[]` | `DEFAULT_TABLE_PAGE_SIZES` |
| `paginationSummaryOnly` | `pagination-summary-only` | When pagination is enabled, show the record count and page-size controls but hide page navigation buttons. | `boolean` | `false` |
| `recordCount` | `record-count` | Show a footer record count without pagination controls. | `boolean` | `false` |
| `resizable` | `resizable` | Allows columns to be resized | `boolean` | `false` |
| `search` | `search` | Shows a built-in table filter search field | `boolean` | `false` |
| `searchPlaceholder` | `search-placeholder` | Placeholder text for built-in table search input | `string` | `'Search'` |
| `sort` | `sort` | Allows simple sorting on columns. More complex data needs to have custom rules in the `columns.sort.compare` object | `boolean` | `false` |
| `tableClassName` | `table-class-name` | Adds a className specifically to the rendered `` element vs. the component wrapper | `string` | `undefined` |
## Methods
### `copyTableToClipboard(options?: { columnDelimiter?: string; rowDelimiter?: string; }) => Promise`
Copies the table's data to the system clipboard as delimited text (via
`navigator.clipboard`). Only columns configured with `copy` are included - together with
a leading header row - and a column's `copy` function, when provided, formats its cell
values.
By default columns are tab-separated and rows newline-separated, so the output pastes
straight into a spreadsheet. Override via `options.columnDelimiter` (default `'\t'`) and
`options.rowDelimiter` (default `'\n'`).
#### Parameters
| Name | Type | Description |
| --------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
| `options` | `{ columnDelimiter?: string; rowDelimiter?: string; }` | Delimiters for the copied text (`columnDelimiter`, `rowDelimiter`). |
#### Returns
Type: `Promise`
### `downloadTable(filename: string) => Promise`
Downloads the table's data as a CSV file. Only columns configured with `download` are
included - together with a leading header row - and a column's `download` function, when
provided, formats its cell values. Triggers a browser download of the generated file.
#### Parameters
| Name | Type | Description |
| ---------- | -------- | --------------------------------------------------------------------- |
| `filename` | `string` | Name for the downloaded file, without extension (`.csv` is appended). |
#### Returns
Type: `Promise`
### `getSelectedRowIds() => Promise`
Returns the Grid.js internal ids of the currently selected rows. Requires a column
using the bundled `RowSelection` plugin (`plugin: { component: RowSelection }`).
#### Returns
Type: `Promise`
### `getSelectedRows() => Promise`
Returns the selected rows as arrays of cell values (in column order, including the
selection column). Selections made on other pages are included. Requires a column
using the bundled `RowSelection` plugin (`plugin: { component: RowSelection }`).
#### Returns
Type: `Promise`
### `printTable(options?: { pageTitle?: string; css?: string; }) => Promise`
Opens the browser's print dialog for the rendered table only. Columns configured with
`print: false` are omitted from the printout.
`options.pageTitle` sets the print document title/header (default `''`); `options.css`
appends extra CSS to the print stylesheet (default `''`).
#### Parameters
| Name | Type | Description |
| --------- | --------------------------------------- | ----------------------------------- |
| `options` | `{ pageTitle?: string; css?: string; }` | Print options (`pageTitle`, `css`). |
#### Returns
Type: `Promise`
### `refresh() => Promise`
Force a re-render of the table
#### Returns
Type: `Promise`
## Slots
| Slot | Description |
| ----------------- | ----------------------------------------------------------------------------- |
| | Default slot for an optional HTML `` element to use as the data source |
| `"filters"` | Slot for center-aligned toolbar content |
| `"left-actions"` | Slot for left-aligned toolbar content |
| `"right-actions"` | Slot for right-aligned toolbar content |
----------------------------------------------