Frappe Datatable

Frappe Datatable provides high-performance rendering for large datasets with the following core capabilities:

Cell Features

• Inline editing and custom formatters.
• Mouse selection and keyboard navigation.
• Ability to copy cell content.

Column Features

• Reordering, resizing, and sorting.
• Hiding/removing columns.
• Adding custom actions.

Row Features

• Row selection.
• Tree-structured organization.
• Inline filters.
• Support for dynamic row heights to handle large datasets efficiently.

You can install frappe-datatable using npm or yarn.

Important: You must also install sortablejs as a dependency for the library to function correctly.

yarn add frappe-datatable
# or
npm install frappe-datatable

To render a datatable, create a new DataTable instance by passing a CSS selector for the container element and an options object. The options object requires columns (an array of column names) and data (an array of arrays representing the rows).

const datatable = new DataTable('#datatable', {
  columns: [ 'First Name', 'Last Name', 'Position' ],
  data: [
    [ 'Don', 'Joe', 'Designer' ],
    [ 'Mary', 'Jane', 'Software Developer' ]
  ]
});

You can customize the language and specific text strings used in the DataTable via the constructor options.

Options:

• language: A string representing the language code (defaults to 'en').
• translations: An object containing key-value pairs for custom translations.

Example:

const table = new DataTable('#container', {
    language: 'fr',
    translations: {
        'Save Sorting': 'Sauvegarder le tri'
    }
});

The DataTable class provides methods to modify the table structure and sorting state:

• sortColumn(colIndex, sortOrder): Manually trigger sorting on a specific column.
• removeColumn(colIndex): Removes a column from the table.
• setColumnSticky(colIndex, sticky): Sets whether a column is sticky (fixed).
• saveSorting(colIndex, nextSortOrder): Saves the current sorting state for a column (useful when options.saveSorting is enabled).

The DataTable supports both user-defined events and internal event listeners.

User Events

User events are defined in the options.events object during initialization. When an event is triggered via fireEvent(eventName, ...args), the corresponding handler in your options object is executed.

Internal Event Listeners

You can register custom listeners for specific events using the .on(event, handler) method. This is useful for intercepting internal lifecycle events or custom events triggered by the table.

Example:

// Registering an internal listener
table.on('onSortColumn', (column) => {
    console.log('Column sorted:', column);
});

Use the following methods to retrieve data and structural information from the table:

• getColumns(): Returns the current column definitions.
• getRows(): Returns the current row data.
• getColumn(colIndex): Returns the column definition at the specified index.
• getCell(colIndex, rowIndex): Returns the cell data at the specified column and row index.

To create a new DataTable, instantiate the DataTable class by passing a DOM element or a CSS selector as the first argument, and an options object as the second. The constructor handles DOM preparation, component initialization, and initial data rendering if data is provided in the options.

Arguments:

• wrapper: An HTMLElement or a string (CSS selector) representing the container for the table.
• options: An object containing configuration such as data, columns, language, translations, and events.

Note: If options.data is present during initialization, the table will automatically call refresh() and apply default or saved sorting.

Use the refresh(data, columns) method to update the DataTable with a new set of data and column definitions. This method initializes the DataManager, re-renders the table, and recalculates dimensions.

Arguments:

• data: The new array of row data.
• columns: The new array of column definitions.