Vuetable-2: Vue 2.x Datatable Component

Common errors

• [Vue warn]: Unknown custom element: <vuetable>

  cause The Vuetable component has not been correctly registered with your Vue application.
  fix Ensure `Vuetable` is imported and added to the `components` option in your Vue instance or component definition: `components: { Vuetable }`.

• Cannot read property 'data' of undefined (when fetching API data)

  cause The API response structure does not match `vuetable-2`'s expected format, particularly the `data` and `pagination` keys, or the `pagination-path` is incorrect.
  fix Configure the `data-path` and `pagination-path` props to match your API response structure, or transform your API response to fit the default `data` and `pagination` top-level keys.

• Sorting does not work when clicking table headers

  cause Sorting is either not enabled for the field, or the `sort-order` prop is not correctly configured for client-side sorting, or the API is not handling the sort parameters.
  fix Ensure `sortable: true` is set in the `fields` definition. If using API mode, verify the `api-url` correctly receives and processes `sort` parameters (e.g., `sort=id|desc`). For client-side sorting (`api-mode='false'`), ensure `sort-order` is properly defined.

Warnings

• breaking Major internal refactor for `v2.0.0` converts 'special fields' into customizable 'Field components'. While backward compatibility is attempted, custom field implementations or advanced usage of internal field mechanisms might require migration.
  Fix: Review the new documentation for v2.0.0 (when stable) regarding custom field components. Convert any existing special field logic to the new `Field component` pattern or verify existing usage for compatibility.
• gotcha The `query-params` prop, which was typically an object, can also be a `Function` since `v1.7.2`. This function receives `sortOrder`, `currentPage`, and `perPage` as parameters and should return the query parameters object.
  Fix: If experiencing unexpected behavior with `query-params`, ensure it's either an object or a function that correctly returns the desired query parameters. If using a function, verify its signature and return value.
• gotcha In `v2.0.0-beta.2` and later, the internal `__sequence` field, used for row numbering, now starts from `1` instead of `0` when pagination is active. This can affect custom calculations or displays relying on zero-based indexing for row sequence.
  Fix: Adjust any logic that relies on the `__sequence` field to account for its new 1-based indexing in `v2.0.0-beta` versions. Consider implementing a custom sequence if specific indexing is critical.
• gotcha The `data-manager` prop in `v2.0.0-beta.2` onwards now supports Promises. While this is an enhancement, it might introduce subtle timing issues or require adjustments if your `data-manager` implementation was strictly synchronous or had different asynchronous handling expectations.
  Fix: Ensure your `data-manager` implementation correctly handles both synchronous and asynchronous (Promise-based) data retrieval if targeting `v2.0.0-beta`. Test thoroughly to avoid race conditions or unhandled promise rejections.

Install

• npm install vuetable-2 npm
• yarn add vuetable-2 yarn
• pnpm add vuetable-2 pnpm

Imports

• Vuetable
  wrong:

  const Vuetable = require('vuetable-2');

  correct:

  import Vuetable from 'vuetable-2';

  Main component for rendering the datatable. Designed for Vue 2 applications.
• VuetablePagination
  wrong:

  import { VuetablePagination } from 'vuetable-2';

  correct:

  import VuetablePagination from 'vuetable-2/src/components/VuetablePagination';

  The default pagination component. Path might vary in future major versions. Always verify sub-component paths.
• VuetablePaginationMixin
  wrong:

  import { VuetablePaginationMixin } from 'vuetable-2';

  correct:

  import VuetablePaginationMixin from 'vuetable-2/src/components/VuetablePaginationMixin';

  Provides common logic for pagination components. Useful for creating custom pagination UIs.

Quickstart

This example demonstrates basic setup of `vuetable-2` with API-driven data, including a standard pagination component. It defines fields, connects to a mock API endpoint, and handles pagination data and page changes through events. This snippet assumes a basic Vue 2 setup and a compatible CSS framework.

import Vue from 'vue';
import Vuetable from 'vuetable-2';
import VuetablePagination from 'vuetable-2/src/components/VuetablePagination';

new Vue({
  el: '#app',
  components: { Vuetable, VuetablePagination },
  data: {
    fields: [
      { name: 'id', title: 'ID' },
      { name: 'name', title: 'Name' },
      { name: 'email', title: 'Email' },
    ],
    apiUrl: 'https://example.com/api/users',
    css: {
      table: 'table table-striped table-bordered',
      // ... other css classes as per documentation
    },
  },
  template: `
    <div>
      <vuetable ref="vuetable"
        :api-url="apiUrl"
        :fields="fields"
        pagination-path="pagination"
        @vuetable:pagination-data="onPaginationData"
      ></vuetable>
      <vuetable-pagination ref="pagination"
        @vuetable:change-page="onChangePage"
      ></vuetable-pagination>
    </div>
  `,
  methods: {
    onPaginationData(paginationData) {
      this.$refs.pagination.setPaginationData(paginationData);
    },
    onChangePage(page) {
      this.$refs.vuetable.changePage(page);
    },
  },
});