tavuelo

Easy to use but with advanced features a Vue.js table component

Installation

First, install npm package:

npm i --save tavuelo

Demo

Clone this repository to your local hard drive.

Install all dependencies:

npm i

Run the demo:

npm run serve

Enter http://localhost:8080 in your browser and check the example of Tavuelo functionalities. Demo code can be found at /src/App.vue file.

Usage

Global usage:

// main.js file
import tavuelo from 'tavuelo'

Vue.use(tavuelo)

Local usage:

// in your Vue.js component
import Tavuelo from 'tavuelo'

export default {
  name: 'YourComponent',
  components: {
    Tavuelo
  }
}

Template usage example:

Minimal example:

<template>
  <tavuelo
    :columns='tableColumns'
    :data='tableData'
  ></tavuelo>
</template>

Extended example:

<template>
<tavuelo
  :columns='[
    { title: "First name", dataSource: "first_name", minWidth: "250px" },
    { title: "Last name", dataSource: "last_name", width: "150px" },
    { title: "Age", dataSource: "age", width: "60px" },
    { title: "Location", dataSource: "location" },
    { title: "Active", dataSource: "active", type: "bool", tooltip: "Information if user is active", width: "80px" },
    { title: 'Full name', dataSource: 'fullName', type: 'slot', slotName: 'fullName', computedValue: row => `${row.first_name} ${row.last_name}` },
    { title: 'Login', dataSource: 'login', type: 'slot', slotName: 'login', computedValue: row => `${row.first_name}${row.age}${row.last_name}` }
  ]"
  :data='[
    {"first_name":"Anthony","last_name":"Levine","age":52,"location":"Lamorteau","active":0,"joined":"1993-11-25T16:42:12-08:00","email":"[e-mail]","phone":346593579},
    {"first_name":"Warren","last_name":"Mcintyre","age":61,"location":"Zwevegem","active":1,"joined":"2013-02-07T05:05:17-08:00","email":"[e-mail]","phone":349017516}
  ]'
  :customSortRules='{
    fullName: (dataCopy, direction) => {
      dataCopy.sort((a, b) => String(`${a.first_name} ${a.last_name}`).localeCompare(String(`${b.first_name} ${b.last_name}`)));
      if (direction === 'desc') {
        dataCopy.reverse();
      }
      return dataCopy;
    },
  }'
  :perPage='20'
  :hasSearch='true'
  :searchColumns='["first_name", "last_name", "location", "age"]'
  :searchCaseSensitive='true'
  :useFlex='true'
  :wrapContent='true'
  defaultSortDataName='first_name'
  :clickHeaderToSort='true'
  :downloadDataButton='true'
  :useNoDataSlot='true'
  :sortColumns='["first_name", "last_name", "location", "age", "fullName", "login"]'
  @page-update="data => this.currentPage = data"
>
  <template slot='noDataSlot'>There is no data here!</template>
  <template slot='fullName' slot-scope='{entry}'>
    {{ entry.first_name }} {{ entry.last_name }}
  </template>
  <template slot='login' slot-scope='{entry}'>
    {{entry.first_name}}{{entry.age}}{{entry.last_name}}
  </template>
</tavuelo>
</template>

API

Table component

Component props

Component's prop	Default value	Value examples	Description
columns	[]	[{title: 'First name', dataSource: 'first_name'}, {title: 'Last name', dataSource: 'last_name'}]	An array of objects that represents table columns
data	[]	[{id: 1, first_name: 'Lukasz', last_name: 'Kups'}, {id: 2, first_name: 'Joe', last_name: 'Doe'}]	An array of objects that represents table contents data
perPage	0	20	A number that defines how many items should be displayed on each pagination when pagination is enabled (0 disables pagination
hasSearch	false	true	A boolean value which sets if table should have search functionality (it will display a search input above the table
customFiltering	n/a	(data, searchQuery) => {...}	A function that is executed instead of default filtering while search. It takes two parameters: copy of table's data (array) and string that is the search input value
searchColumns	[]	`['first_name, 'last_name', 'location']	`
searchCaseSensitive	false	true	A boolean value to set if search string should be case sensitive or not
sortColumns	[]	`['first_name, 'last_name', 'location']	`
sortAllColumns	false	true	A boolean value which indicates if we want to enable sorting for our table for all columns out of the box or not
useFlex	true	false	A boolean value to set if table columns should behave like flex elements (e.g. columns won't resize on page change)
wrapContent	false	true	A boolean value that adds ellipsis effect to each table cell if content overflows max column width
defaultSortDataName	''	'first_name'	A string value that points on column's data source that should be default sorting based on
defaultSortDirection	'asc'	'desc'	A string asc or desc that set the default sort direction
customSortRules	n/a	{first_name: (dataCopy, sortDirection) => {...}}	An object that keys corresponds to column data sources and values are functions that handle custom sort logic while taking 2 parameters: dataCopy which is exact copy of table's data and sortDirection (which takes asc or desc as its value)
clickHeaderToSort	false	true	A boolean value that binds column sorting with whole table header cell (by default, tavuelo handle sorting by clicking sort arrows only)
rowClick	null	rowclickCallback(row) { ... }	A function that is executed when user clicks on any table body row. This function takes row parameter by default so you can learn on which row user clicked
downloadDataButton	false	true	A boolean value that toggle visibility of button that triggers data download action
downloadDataFileType	json	csv	A string value that determines if data is available to download as json or csv file
noDataLabel	No data	There is no results	A string message that shows when there is no results/data in the table
useNoDataSlot	false	true	A boolean value that toggle usage of slot block that will be visible when there won't be any results/data in the table. If it is set to true then tavuelo will use the template block with noDataSlot slot name instead of displaying text that has been set in noDataLabel property
showAllPages	false	true	A boolean value that toggle how pagination is displayed. By default it shows [First page][Prev page]Page [input which changes page that equals entered value on blur] of TOTAL_PAGES [Next page][Last page]. If set to true, it displays all clickable page numbers as separate buttons, e.g. [First page][Prev page][1][2][3][4][5][Next page][Last page]
selectableRows	false	true	A boolean value that enable or disable row selection feature. Once enabled, an extra column will be added at the beginning of each row with checkbox input
selectedRows.sync	[]	[1, 2, 5]	Array that contains IDs of entries which are selected. On change, tavuelo emits updated array so thanks to .sync modifier you can use this value in your application. Works only if selectableRows prop is true
selectAllRowsButton	false	true	A boolean value that toggle visibility of Select all button in the selection column header. Once clicked, it will select all available records (or if all are already selected, it will deselect it) and update selectedRows prop. Button label can be set via CSS :before content property.
selectRowsOnPageButton	false	true	A boolean value that toggle visibility of Select all on page button in the selection column header. Once clicked, it will select all records that are displayed on current page (or if all are already selected, it will deselect it) and update selectedRows prop. Button label can be set via CSS :before content property.

Component events

Event name	Callback value example	Usage example	Description
page-update	{page: 2, data: [{ "first_name": "Armando", "last_name": "Petty", "age": 39, "location": "Saharanpur", "active": 1, "joined": "1994-05-06T11:42:08-07:00", "email": "[e-mail]", "phone": 394249077, "id": 46 }, { "first_name": "August", "last_name": "Rollins", "age": 66, "location": "Lansing", "active": 1, "joined": "1985-10-24T20:12:52-07:00", "email": "[e-mail]", "phone": 709236404, "id": 53 }]}	@page-update="handlePageUpdateData" or @page-update="data => currentPageDetails = data"	Event that is triggered when active page or its content are being changed (so on page/sort/filter change). It emits the object with given structure: {page: <page-number>, data: <array-containing-data-that-is-being-displayed-on-current-page>}

Table column definition

To create table properly you have to pass an array of columns definitions to :columns component property, e.g.:

[
  {title: 'First name', dataSource: 'first_name'},
  {title: 'Last name', dataSource: 'last_name'},
  {title: 'Active', dataSource: 'is_active', type: 'bool'}, // type 'text' is default
  { title: 'Full name', dataSource: 'fullName', type: 'slot', slotName: 'fullName', computedValue: row => `${row.first_name} ${row.last_name}` }
]

Property name	Available values	Example value	Description
title	Any string	First name	Title of the column that will be displayed in table header
tooltip	Any string	First name of the user	If defined, when user hover on table header cell, it will display additional content as tooltip bubble. Handy when table gets really wide and want to show shorter table headings with extensive descriptions inside tooltips.
dataSource	Any string	first_name	Name of the property that should be displayed in the column.
type	text(default), bool, slot	bool	Defines type of the column contents. By default, text column data type is set. When bool, it displays tick (true) or cross(false) icon instead of plain value. When slot, the slotName prop is required that will tell tavuelo what slot block should be used to display the cell contents
onClick	Any function	cellClickCallback(row, column, event) { ... }	A function that is executed when user clicks on given table column cell. This function takes row, column and event parameters by default so you can use them in your callback.
slotName	Any string	fullName	Name of the slot block that will be used to display contents of the cell. Slot block also needs to have defined slot-scope='{entry}' property. The entry value contains object of current table row.
computedValue	Any function	getFullName(row)	A function that returns computed value of the cell - handy when using slot-based columns and wants to handle filtering/sorting on this column (as the result of this function will be used for filter/sorting).

Roadmap

Roadmap to version 1.0.0. is available at issues tab.

Feel free to add own feature request issues there.

Changelog

You can find the release notes/changelog at lukaszkups website

Troubleshoot & support

You can submit bugs similarly to feature request at github's issues tab with bug label.

For more alike real-time support, feel free to tweet to me.

License

MIT

Author

@lukaszkups