# Table

Table of Contents

###### Examples

Basic Usage
Custom Fields
Top and Bottom Controls
Row Controls
Pagination
Record Selection
Record Editing
Record Hiding
Record Filtering
Record Searching
Sorting
Field Sorting and Hiding
Fetching Records

###### JavaScript Reference

Constructor
Requirements
Properties
Methods

### Description

The `<k-table>` component is used to render data into a `<table>` using JavaScript.

### Basic Usage

In HTML create a `<k-table>`, and then in JavaScript call the `setData` method passing in an options object containing your data.

    <k-table id="basicUsageExample"></k-table>
    <script type="module">
      document.getElementById('basicUsageExample').setData({
        records: [
          {
            name: "Dustin",
            phoneNumber: "(111) 111-1111",
            emailAddress: "dustin@mailserver.com",
            gender: "Male"
          },
          {
            name: "Kayla",
            phoneNumber: "(222) 222-2222",
            emailAddress: "kayla@mailserver.com",
            gender: "Female"
          },
          {
            name: "Alexander",
            phoneNumber: "(333) 333-33333",
            emailAddress: "alex@mailserver.com",
            gender: "Male"
          },
          {
            name: "Amelia",
            phoneNumber: "(444) 444-44444",
            emailAddress: "amelia@mailserver.com",
            gender: "Female"
          },
        ]
      });
    </script>

### Examples

- Custom Fields Example
- Top and Bottom Controls
- Row Controls
- Pagination
- Record Selection
- Record Editing
- Record Hiding
- Record Filtering
- Record Searching
- Sorting
- Field Sorting and Hiding
- Fetching Records

## JavaScript Reference

### Constructor

###### Extends Component

##### `new Table()`
`new Table(<Array>object options)`

#### Parameters

##### `object options`

An object containing the initial configuration for the table. The options object can contain the following properties:

- `records`: An array of objects representing the records to be shown in the table.
- `fields`: An array of objects representing the fields of the table, each object must contain a `name` and a `label`. If this property is omitted, the fields will be automatically generated from the first 100 records.
- `controls`: An object containing optional arrays of controls to be displayed before and/or after each row. Each control is defined by an icon name, a callback function, and optionally an HTML string or a render function. The `controls` object can contain the optional `before` and `after` properties, which are arrays of objects containing the `icon` (string), `action` (function), `html` (string), and `render` (function). If `html` is present, it overrides the icon and is rendered in its place. If `render` is present, it is used to render the control.
- `pageSize`: The number of records to display per page.
- `pageSizeOptions`: An array of numbers representing the available page size options.

### Requirements

- `toTitleCase` from string.js

### Properties

##### `fields: <Array>object`

An array of objects containing a `name`, `label`, `renderer` function, and `calculator` function that represent the fields to be displayed. The `renderer` function can be used to customize the display of the field, and the `calculator` function can be used to calculate the value of the field based on other fields in the record.

##### `records: <Array>object`

An array of objects containing the data that will be the records of the table, where the object keys match the field names.

##### `controls: object`

An object containing optional arrays of controls to be displayed before and/or after each row, or above and below the table. Each control is defined by an icon name, a callback function, and optionally an HTML string or a render function. The `controls` object can contain the optional `before`, `after`, `top`, and `bottom` properties, which are arrays of objects containing the `icon` (string), `action` (function), `html` (string), and `render` (function). If `html` is present, it overrides the icon and is rendered in its place. If `render` is present, it is used to render the control. Controls in the `before` or `after` arrays receive the record and index as the 2nd and 3rd parameters in the action function and the renderer function.

##### `pageSize: number`

The number of records to display per page.

##### `pageSizeOptions: <Array>number`

An array of numbers representing the available page size options.

### Methods

##### `setData(object options): undefined`

Sets the records and the fields and renders the table. If no fields are provided, they will be automatically generated from the keys of the first 100 records. The options object can contain the following properties:

- `records`: An array of objects representing the records to be shown in the table.
- `fields`: An array of objects representing the fields of the table, each object must contain a `name` and a `label`. If this property is omitted, the fields will be automatically generated from the first 100 records.
- `filters`: An array of filter objects to apply to the records.
- `pageSize`: The number of records to display per page.
- `pageSizeOptions`: An array of numbers representing the available page size options.
- `currentPage`: The current page to display.
- `enableSelection`: A boolean to enable or disable record selection.
- `enablePages`: A boolean to enable or disable pagination.

##### `renderFields(): undefined`

Renders the fields as table headers. This is called automatically by setData, you should never have to call it.

##### `renderRecords(): undefined`

Renders the records as table rows. This is called automatically by setData, you should never have to call it.

##### `addRecord(object record): undefined`

Adds a new record to the table.

##### `updateRecord(object record, object newData): undefined`

Updates an existing record with new data.

##### `deleteRecord(object record): undefined`

Deletes a record from the table.

##### `setRecords(Array records): undefined`

Sets the records for the table and re-renders the rows.

##### `setPageSize(number pageSize): undefined`

Sets the number of records to display per page.

##### `setPage(number page): undefined`

Sets the current page to display.

##### `nextPage(): undefined`

Moves to the next page.

##### `prevPage(): undefined`

Moves to the previous page.

##### `getCurrentPage(): number`

Returns the current page number.

##### `getTotalPages(): number`

Returns the total number of pages.

##### `getSelectedRecords(): Array`

Returns an array of the currently selected records.

##### `deleteSelected(): undefined`

Deletes all currently selected records from the table.

##### `selectAllOnPage(): undefined`

Selects all the records on the current page.

##### `deselectAllOnPage(): undefined`

Deselects all the records on the current page.

##### `allOnPageSelected(): boolean`

Returns `true` if all the records on the current page are selected, and `false` if they are not.

##### `editRecord(object record): undefined`

Enables editing mode for a record.

##### `saveEditedRecord(object record): undefined`

Saves the changes made to an edited record.

##### `cancelEditedRecord(object record): undefined`

Cancels the editing mode for a record.

##### `recordIsEditing(object record): boolean`

Returns `true` if the record is in editing mode, and `false` if it is not.

##### `hideRecord(object record): undefined`

Hides a record from the table.

##### `showRecord(object record): undefined`

Shows a hidden record in the table.

##### `showAllRecords(): undefined`

Shows all hidden records in the table.

##### `addFilter(string field, string condition, any value): undefined`

Adds a filter to the table.

##### `removeFilter(string field, string condition, any value): undefined`

Removes a filter from the table.

##### `removeAllFilters(): undefined`

Removes all filters from the table.

##### `search(string term): undefined`

Searches the records for the specified term.

##### `getDisplayedRecords(): Array`

Returns an array of the records currently displayed in the table.

##### `getHiddenRecords(): Array`

Returns an array of the hidden records in the table.

##### `setupFetchRecords(number totalRecords, function callback): undefined`

Sets up the table to fetch records dynamically.

##### `sortBy(string field, boolean asc): undefined`

Sorts the records by the specified field in ascending or descending order.

##### `setFieldHiddenState(string fieldName, boolean hidden): undefined`

Sets the hidden state of a field.

##### `hideField(string fieldName): undefined`

Hides a field in the table.

##### `showField(string fieldName): undefined`

Shows a hidden field in the table.

##### `reorderFields(Array newOrder): undefined`

Reorders the fields in the table based on the new order array.