muonw-powertable

Muonw Powertable

▦ PowerTable is a Svelte component that turns JSON data into an interactive HTML table. Inspired by DataTables. Powered by Svelte.

MuonW PowerTable

PowerTable

PowerTable is a Svelte component that turns JSON data into an interactive HTML table. This facilitates manual inspection, sorting, filtering, searching, and editing of the data. PowerTable is inspired by DataTables and powered by Svelte.

✨ Features

  • No runtime dependencies
  • Sorting (single- and multi-column + custom sorting)
  • Filtering (per column and global + RegEx + custom filtering)
  • Inline editing
  • Re-arrangeable layout segments
  • Optional styling
  • Custom parsing
  • Local and remote data source

⚡️ Quick start

First, set the correct node package registry for @muonw packages:

npm config set @muonw:registry https://node.pkgreg.com/ -L project

Then, install the package:

npm i -D @muonw/powertable

Now, you can import the component in your svelte files (e.g. src/routes/+page.svelte). Here is an example of a basic implementation in an SvelteKit project without any styling (styles can be added by uncommenting the import lines):

<script>
import { PowerTable } from '@muonw/powertable';
let ptData = [{"id": 1, "name": "Fay"}, {"id": 2, "name": "Luca"}];

// Uncomment to add basic styling. Requires installing saas (i.e. npm install -D sass)
// import '@muonw/powertable/styles/power-table.scss';

// Uncomment if using @muonw/mascara (https://github.com/muonw/muonw-mascara)
// import '@muonw/powertable/styles/power-table-mascara.scss';
</script>

<PowerTable {ptData} />

👀 Examples

To see the demos, visit https://muonw.github.io/muonw-powertable/examples/example1

📖 Manual

Props

The PowerTable component accepts three optional props: ptInstructs, ptOptions, and ptData.

<PowerTable {ptInstructs} {ptOptions} {ptData} />

❶ The prop ptInstructs is an array of objects that sets the column attributes. All properties except for key are optional.

Example:

let ptInstructs = [
    {key: 'id'},
    {key: 'name', title: 'Full Name'},
    {key: 'gender', title: 'Gender', sortable: false},
];
Property Type Default Description
key string A unique string representing the column
title string [value of key] Text displayed on column's header
sortable boolean true Whether the column is sortable
sortCaseSensitive boolean false Whether sorting should be case sensitive
filterable boolean true Whether the column can be filtered
filterPhrase string "" The column's default filter phrase
filterIsRegex boolean false Whether the default filterPhrase is Regex (for remote data)
parseAs 'text' | 'html' | 'unsafe-html' | 'component' 'text' 'html' allows rendering of <div>, <span>, <code>, <strong>, <b>, <p>, <ul>, <ol>, <li>, <u>, <i>, <em>, <sup>, and <sub> tags with an optional class attribute. If a tag doesn't match this criteria, only its content will be displayed. If set to 'unsafe-html', all HTML tags will be rendered without any sanitization. When set to 'component', a Svelte component should be provided via the dataComponent property
userFunctions object [See Below]
dataComponent SvelteComponent [See Below]

The userFunctions property in ptInstructs prop is an object that can contain the following user-defined function(s).

Property Type Default Description
customSort function Overrides the sorting process
customFilter function A user-defined function to override the filtering process

The value of customSort should be a function that receives two string values (v1 and v2) and returns a number indicating the order of those values: -1 if v1 < v2, 1 if v1 > v2, 0 if v1 == v2

The value of customFilter should be a function that returns a slice of ptData after applying a filter. The function will receive the ptData.

The dataComponent property in ptInstructs prop is a Svelte component that can receive, modify, and output the content of a cell. The following variables will be accessible in the component:

Variable Type Default Description
value string '' The content of the cell
rowIndex number The position of the row relative to the page
rowId number The position of the row relative to the dataset
instructKey string The instruct key of the column

❗ Special instructs: There are two special instructs that will be added to the underlying instructs and data objects for internal use (e.g. keeping track of the id and checkbox value of each row). In many cases, when accessing or altering a row data in a user-defined function, you should exclude these instructs from the process. To do so, import the variables dataIdKey and checkboxKey and exclude any instruct whose key matches the value of those variables.

❷ The prop ptOptions is an object that allows adjusting various features of the table. All properties are optional.

Example:

let ptOptions = {
    uniquePrefix: 'myTable1',
    rowsPerPageOptions: [10, 100, 200],
    footerText: false,
    footerFilters: false,
}
Property Type Default Description
uniquePrefix string "" A unique string representing a table instance
rowsPerPageOptions number[] [5, 10, 20, 50, 100] Possible number of displayed rows per page
rowsPerPage number 10 Default number of displayed rows per page
paginationBlock 3|5|7|9|11| 13|15|17|19 3 Pagination length excluding the first and last page
headerText boolean true Whether to show header titles
footerText boolean true Whether to show footer titles
headerFilters boolean true Whether to show header filter text fields
footerFilters boolean true Whether to show footer filter text fields
headerLoadingBar boolean true Whether to show header loading bar for remote data
footerLoadingBar boolean true Whether to show footer loading bar for remote data
defaultRegexFlags string 'gimsu' The default RegEx flags
nestedSorting boolean false Whether the nested/multi-column sorting is enabled
isDataRemote boolean false Whether the data is fetched from a URL
totalRows number | null null Total number of rows (when displaying remote data)
filteredRows number | null Number of filtered rows (when displaying remote data)
currentPage number 1 The number of the displayed page
searchPhrase string "" The default search phrase
searchIsRegex boolean false Whether the default search phrase is RegEx
checkboxColumn boolean false Whether to show checkbox selection column
translations object [See Below]
userFunctions object [See Below]
segments object [See Below]
sortOrder object [See Below]

The translations property in ptOptions prop is an object that can contain language-specific number format as well as the translations of various parts of the table. See the available options in the source code of Example 3: Custom Options.

The userFunctions property in ptOptions prop is an object that can contain the following user-defined functions.

Property Type Default Description
dataFeed function async () => ({}) When isDataRemote is true, the output of this function will be used as ptData prop
customParse function A user-defined function to intercept and modify the content of the current page
customSearch function A user-defined function to override the search process
deleteActionCallback function A user-defined function that receives an array of deleted rows
editSubmissionCallback function A user-defined function that receives the updated row data

❗ When retrieving data in a user-defined function, pay attention to the special instructs!

The value of dataFeed should be a function that returns remote data (e.g. from and API). The function will receive an object (defined below) containing the information required to generate the props.

The function received the following object:

{
    options = ➤ current options (same structure as `ptOptions`),
    search: {
        isRegex: ➤ true or false (boolean),
        value: ➤ the search phrase (string)
    },
    filters: {
        [➤ `ptInstruct` key]: {
            isRegex: ➤ true or false (boolean),
            value: ➤ the filter phrase
        },
        ...
    },
    sorting: {
        [➤ `ptInstruct` key]: ➤ the sorting direction (a value of `sortOrder`),
        ...
    }
}

and should return the following object:

{
    instructs: ➤ Instructs to be used (same structure as ptInstructs),
    options: ➤ Options to be used (same structure as ptOptions),
    data: ➤ Data of the current page. Should be already searched, filtered, and sorted (same structure as ptData)
}

The value of customParse should be a function that returns the modified content of the current page. The function will receive a slice of the ptData that contains the current page's data.

The value of customSearch should be a function that returns a slice of ptData after performing search. The function will receive the ptData.

The segments property in ptOptions is an object that defines the top to bottom order of various HTML parts of PowerTable to facilitate theming and styling. Each property in this object will render a container DIV element with a data-name attribute equal to the property's arbitrary name and data-type equal to "segment". The value of each property is an array of HTML parts to be included in the container DIV element. Consider the following example:

segments: {
    'myTopContainer': ['search', 'pagination'],
    'myTableContainer': ['table'],
}

That will translate to...

<div data-name="myTopContainer" data-type="segment">
    [search bar HTML]
    [pagination HTML]
</div>

<div data-name="myTableContainer" data-type="segment">
    [table HTML]
</div>

The property names are arbitrary strings. The property values are as follows.

value Description
"search" Search bar
"pagination" Pagination
"table" The table block
"dropdown" Dropdown menu for selecting the number of rows per page
"stats" Representation of the displayed, filtered, and total number of rows
"settings" Settings button

The default value of segments:

{
    'topBar': ['search', 'pagination'],
    'pTable': ['table'],
    'bottomBar': ['dropdown', 'stats', 'pagination'],
}

The sortOrder property in ptOptions prop is an object that specifies how the sorting direction will change. The property names represent the sorting direction before the click and their values represent the sorting direction after the click. When the value is an empty string, no sorting will be applied.

name/value Description
"asc" Ascending (small to large)
"desc" Descending (large to small)
"" No sorting

The default value of sortOrder:

{
    '': 'asc',
    'asc': 'desc',
    'desc': '',
}

❸ The prop ptData is an array of objects containing the data to be displayed in the table. The property names must match the value of the key properties in ptInstructs. All property values including boolean, number, object, and array values will be converted to string.

Example:

let ptData = [
    {"id": 1, "name": "Fay"},
    {"id": 2, "name": "Luca"}
];

Events

The events rowClicked or rowDblClicked will be dispatched when a row is clicked or double clicked, respectively. Both return an object with a property named event containing the mouse event, and data containing the row data from ptData.

<PowerTable
    {ptData}
    on:rowClicked="{(d) => console.log('click', d)}"
    on:rowDblClicked="{(d) => console.log('dblclick', d)}"
/>

Slots

Named slots can be used to override some default HTML elements.

Example:

<PowerTable {ptData}>
    <div slot="noResults">There is no records to show!</div>
    <div slot="rendering">Please wait while table is being rendered...</div>
    <div slot="settings">
        <div data-name="item">Toggle control column</div>
    </div>
</PowerTable>
Slot name Description
noResults Content to be shown when there are no rows in the table
rendering Content to be shown when table is loading remote data
settings Content to be shown in the setting menu

Functions

getData: once the component is mounted, getData can be called to retrieve the props as well as search and filter data. This function accepts two parameters. The first parameter is a boolean value that determines whether Special Instructs should be removed before returning data (default is true). The second parameter is an array that determines what properties should be returned (default is ['options','instructs','data','search','filters']). This function returns the following object:

{
    options: ➤ current options (same structure as `ptOptions`),
    instructs: ➤ the instructs (same structure as `ptInstructs`),
    data: ➤ current contents (same structure as `ptData`),
    matchedData: ➤ data after applying search and filters,
    sortedData: ➤ data after applying sorting,
    pageData: ➤ data of the current page before applying custom parsing,
    formattedPageData: ➤ data of the current page after applying custom parsing,
    search: {
        isRegex: ➤ true or false (boolean),
        value: ➤ the search phrase (string)
    },
    filters: {
        [➤ `ptInstruct` key]: {
            isRegex: ➤ true or false (boolean),
            value: ➤ the filter phrase
        },
        ...
    }
}

getRegexParts receives a string RegEx and returns an object containing the RegEx delimiter, pattern, and flags as shown below. If the string is not a valid RegEx, false will be returned.

{
    delimiter: ➤ string,
    pattern: ➤ string,
    flags: ➤ string
}

🎯 Objectives

This repository exists to develop and maintain a tool that fulfills the following requirements:

  • Displays structured JSON data in an HTML table that...
    • is easy to navigate with mouse and/or keyboard.
    • is easy to interact with on a desktop monitor.
    • renders 1000+ rows without noticeable delay.
    • can display and modify remote data.
  • Is based on Svelte.
  • Is easy to learn and use.
  • Runs in latest versions of Firefox ESR, Chromium, and Safari.
  • Does not impose a theme.
  • Does not include a web server.
  • Does not include third party runtime dependencies.

🌟 Spotlight

svelte-jsoneditor - A web-based tool to view, edit, format, repair, query, transform, and validate JSON

📝 To-do

  • Fetch remote data
  • Inline editing
  • Improve search

💻 Contribution

Areas of high priority:

  • Accessibility
  • Code quality
  • Tests

License:

This software is protected by the Unenforceable license:

https://dev.muonw.com/license/unenforceable

Top categories

svelte logo

Need a Svelte website built?

Hire a professional Svelte developer today.
Loading Svelte Themes