@sensetence/vue-quintable v2.3.25

VueQuintable

VueQuintable is a table wrapper for Vue.js 2.x. It is build with bootstrap 5.x. High configurable, easy to use, flexible and responsive.

Demo

Getting Started

These instructions will get you running VueQuintable for your project for development purposes.

Prerequisites

VueQuintable is a vue.js package and uses bootstrap by default. Please install both before using the package. If you want to use ajax functionalities please install axios as it is used by VueQuintable.

npm:

npm install --save axios

yarn:

yarn add axios

Installing

npm:

npm install --save bootstrap
npm install --save @popperjs/core
npm install --save @sensetence/vue-quintable

yarn:

yarn add bootstrap
yarn add @popperjs/core
yarn add @sensetence/vue-quintable

Integration

import Vue from 'vue'

//use bootstrap
import 'bootstrap/dist/css/bootstrap.css'

import "@sensetence/vue-quintable/dist/vue-quintable.css"
import VueTable from '@sensetence/vue-quintable'
Vue.use(VueTable);

Use directly in browser

You can either install VueQuintable via bower

bower install --save https://github.com/sensetence/vue-quintable

or just download the source and include the scripts and styles in dist folder to use VueQuintable for your browser page.

<script type="text/javascript" src="/path/to/vue/dist/vue.min.js"></script>

<script type="text/javascript" src="/path/to/project/dist/vue-quintable.umd.min.js"></script>

<link rel="stylesheet" href="/path/to/project/dist/vue-quintable.css"></link>

Vue.use(window["vue-quintable"]);

Features

These points will convince you that VueQuintable is the last table plugin you will ever need

• Responsive columns which will be rendered as additional rows
• Pagination
• Sort/Multi-sort
• Search
• Custom Filters
• Recursive filter groups with relations
• Select rows
• Custom search keywords and filter values for rows
• Vue-binded values for columns and rows
• Nested VueQuintables
• Vue components inside tables
• Custom cell formatters

Slots

You can define some slots to customize the table as you want to.

• header | used for content above the table
• before-search | used for content before the search bar
• after-search | used for content after the search bar
• after-search-container | used for content before the search bar container
• footer | used for content below the table
• no-results | used for placeholder if there are no table entries due to filtering etc.
• loading | custom loader
• cell-complete | deprecated
• cell-content | custom content for cells, cell is delivered as slot scope. Used also for generated and sticky cells
• generated-cell-complete | deprecated
• generated-cell-content | custom content for generated cells
• sticky-cell-complete | deprecated
• sticky-cell-content | custom content for sticky cells

<template v-slot:header>Your HTML-Code</template>

//for content of regular table cells
<template v-slot:cell-content="{cell}">
    <button v-if="cell.any_property ==='any_value'" class="cell-content-button">
        {{cell.any_property}}
    </button>
</template>

//for content of responsive generated table cells
<template v-slot:generated-cell-content="{cell}">
    <button v-if="cell.any_property ==='any_value'" class="generated-cell-content--button">
        {{cell.any_property}}
    </button>
</template>

//for content of sticky table cells
<template v-slot:sticky-cell-content="{cell}">
    <button v-if="cell.any_property ==='any_value'" class="sticky-cell-content-button">
        {{cell.any_property}}
    </button>
</template>

//for same content of regular, responsive generated and sticky table cells
<template v-for="slotName in ['cell-content','generated-cell-content','sticky-cell-content']" #[slotName]="{cell}">
    <button v-if="cell.any_property ==='any_value'" :key="`button-${slotName}`" :class="`${slotName}`-cell-button">
        {{cell.any_property}}
    </button>
</template>

Events

Add listeners for the following events to handle them as you want to.

• click:row | passes row as first parameter, triggered when row is clicked

• click:cell | passes cell as first parameter, triggered when cell is clicked

• expand:row | passes row as first parameter, triggered when row is expanded

• collapse:row | passes row as first parameter, triggered when row is collapsed

• filtered:rows | passes filtered rows as first parameter, triggered when filter or search query affect rows

• ajax:rows | passes an object with ajax rows and total count as first parameter, triggered when rows are updated from server

• ajax:error | passes an error as first parameter, triggered when an server error occurs while loading rows via ajax

• update:perPage | passes integer as first parameter, triggered when per page parameter changes

• update:page | passes integer as first parameter, triggered when page is changed

• update:search | passes string as first parameter, triggered when search query is entered

• update:sort | passes object of sort group as first parameter, triggered when sort order is active/changes

• component:event | generic event for passing data from child component

• active:row | fires if active row is updated, the config property enableRowTabIndex has to be set to true

Configuration

The following will give you an overview how to configure the VueQuintable for your needs.

Table Properties

Property config properties

Property columns for property config properties

Property rows properties

Property cells for property rows properties

Lets have a look on an example for rows and cells

//Table with columns "Name","Age","Birth Place","Job"

[
    //simple row as array
    [ 
        {
            text:"John Doe"
        },
        {
            text:50
        },
        {
            text:"Trainee"
        },
    ],
    //advances row as object
    {
    	cells:[
            {
                html:"<b>Max</b> Mustermann",
                classes:"special-td",
                align:"end",
             },
            {
                component:{
                    name:"age-component",
                    props:{
                        age:20,
                    }
                },
            },
            {
                text:"Trainee"
            },
		]
    }
]

Component Definition

To use a custom component inside a VueQuintable you have to define it as the following:

<template>
    <div @click="check">
      Age: {{age}}
    </div>
</template>


<script>

    export default {
        props:["age"],
        methods: {
            check() {
                //emit the pre-defined event for component actions
                //handled from VueQuintable by "component:event"
                this.$emit("action",
                    {
                        age:this.age,
                    }
                )
            }
        }
    }

</script>

Import and use the Component in your Code:

import TestComponent from "./components/TestComponent.vue"

Vue.component(
    "test-component",
    TestComponent.default || TestComponent
);

Property filters properties

This example shows selected values for active, printable, first_name, middle_name, and last_name filters. Operators can be:

{
   active:true,
   printable:false,
   first_name:
    {
        operator:"contains",
        values:["Jo","ja"],   
    },
    middle_name:
    {
        compare:"matches",
        values:new RegExp("r.+a","g"),   
    },
    last_name:
    {
        compare:(value,rowValue)=>{
        	return rowValue.indexOf(value) === 2;
        },
        values:"a",   
    }
   
}

Property filter-groups properties

This filter groups example will cause to show rows that have filter matching filter values for selected name OR active filter AND selected printable filter. This groups are infinitely nestable.

[
    {
        items:[
            {
                items:[
                    {
                        name:"name"
                    },
                    {
                        name:"active"
                    }
                ],
                relation:"OR",
            },
            {
                items:[
                    {
                        name:"printable"
                    }
                ],
            }
        ],
        relation:"AND"
    }
],

Property sort-order properties

These examples depict a sorting ordered second column (index=1) before first column (index=0). You can use Objects to set the ascending or descending order optionally. The Default will be asc=true, column index starts on zero.

//simple
[
   1,0
]

//advanced
[
    {
        index:1,
        asc:false
    },
    {
        index:0,
        asc:true
    },
]

Basic Example

A simple basic example to show the usage of VueQuintable. More examples are included in the project and can be started with:

npm run start

<template>
	<VueQuintable :config="config" :rows="rows"></VueQuintable>
</template>

<script>

    import VueQuintable from './components/VueQuintable.vue

    ...
 
  	data() {
        return {
            config: {
                columns: [
                    {
                        headline: "Name",
                    }, {
                        headline: "Age",
                    }, {
                        headline: "Birth Place",
                        breakpoint: "md"
                    }, {
                        headline: "Job",
                        sticky: true,
                    }
                ],
            },

            rows: [
                [
                    {
                        text: "Mia Wong"
                    },
                    {
                        text: 50
                    },
                    {
                        text: "Beijing"
                    },
                    {
                        text: "Trainee"
                    },
                ],
                [
                    {
                        text: "Peter Stanbridge"
                    },
                    {
                        text: 18
                    },
                    {
                        text: "London"
                    },
                    {
                        text: "Trainee"
                    },
                ],
                [
                    {
                        text: "Natalie Lee-Walsh"
                    },
                    {
                        text: 25
                    },
                    {
                        text: "Dublin"
                    },
                    {
                        text: "Trainee"
                    },
                ],
            ],
        }
    }
          
  ...
</script>

AJAX data example

<template>

...

<VueQuintable :loading="loading" :config="remoteConfig" :rows="remoteRows" />

...

</template>

<script>
	import axios from 'axios'

	...

  	data(){
        return {
            loading:false,
            remoteConfig:null,
            remoteRows:null
  		
 	...
 
    mounted(){
        this.loading = true;
        axios.get("http://your.server.url/api/endpoint").then((response)=>{
            this.remoteRows = response.data.rows;
            this.remoteConfig = response.data.config;
            this.loading = false;
        });
    }
...

</script>

The request for the ajax handling on server has got the following structure:

{
    //String search query
    search:"some query",
    //Object Filters, see above
    filters:{},
    //Number etries per page
    perPage:12,
    //Number current page, starting at 1
    page:2,
    //Object sorting columns and 
    sort:{
        //Array of sorting column indexes
        indexes:this.currentSortIndexes,
        //Object of column definitions keyed by column index
        columns:this.sortingColumns,
    },
};

The response has to be the following structure:

{
	//Array of all rows, structure see above
	rows:[]
    //Number of all matching rows, without paging
    all:240
}

Good to know

• Links won't trigger expanded rows to collapse. Also you can prevent collapse parent row by define an element with the class "prevent-toggle"
• VueQuintable uses v-model for selected rows, its also possible to use selected.sync (best practice)
• If you use the storeState property, filters have to be updated vie filters.sync

License

VueQuintable is free for everyone to use in any project (MIT License).

Authors

Sensetence UG - Samuel Zeitler