{"id":15067497,"url":"https://github.com/niiknow/vue-datatables-net","last_synced_at":"2025-04-05T04:11:21.661Z","repository":{"id":33528729,"uuid":"155775307","full_name":"niiknow/vue-datatables-net","owner":"niiknow","description":"Vue jQuery DataTables.net wrapper component","archived":false,"fork":false,"pushed_at":"2023-03-15T00:15:29.000Z","size":7915,"stargazers_count":171,"open_issues_count":13,"forks_count":58,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-29T03:09:18.394Z","etag":null,"topics":["component","datatable","datatables","jquery","vue","vue2"],"latest_commit_sha":null,"homepage":"https://niiknow.github.io/vue-datatables-net/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niiknow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-01T21:01:29.000Z","updated_at":"2024-01-17T19:34:39.000Z","dependencies_parsed_at":"2024-10-30T10:05:22.651Z","dependency_job_id":null,"html_url":"https://github.com/niiknow/vue-datatables-net","commit_stats":{"total_commits":169,"total_committers":10,"mean_commits":16.9,"dds":0.09467455621301779,"last_synced_commit":"b402ba4a5fcc45d381247cdccfefed0643146694"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Fvue-datatables-net","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Fvue-datatables-net/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Fvue-datatables-net/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Fvue-datatables-net/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niiknow","download_url":"https://codeload.github.com/niiknow/vue-datatables-net/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284950,"owners_count":20913704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component","datatable","datatables","jquery","vue","vue2"],"created_at":"2024-09-25T01:24:25.776Z","updated_at":"2025-04-05T04:11:21.643Z","avatar_url":"https://github.com/niiknow.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vue-datatables-net\n\u003e Vue jQuery DataTables.net wrapper component\n\nThis library is a Vue 3 wrapper for [jQuery DataTables](https://datatables.net/).  It's a tiny wrapper that doesn't include anything, not even the datatables.net core library.\n\n**Note:**\n* You've found this library because you want to use jQuery datatables.net client-side with your application.  Alternatively, if you simply want to integrate with server-side datatables.net compatible endpoint, then I'd like to suggest looking at bootstrap-vue b-table and this component - https://github.com/niiknow/bvtnet-items-provider\n* For Vue 2 support, see vue2 branch or npm install vue-datatables-net@^1.6.1\n\nWe use `laravel-mix` to simplify build and packaging.\n\nRequirement: Install NodeJS, NPM\n\nThen:\n```\ngit clone https://github.com/niiknow/vue-datatables-net\ncd vue-datatables-net\nnpm install\n```\n\nor in one command:\n```\nnpm install git+https://github.com/niiknow/vue-datatables-net.git\n```\n\nTo run locally (automatically launch firefox):\n```\nnpm run watch\n```\n\nTo build library for npm publish:\n```\nnpm run production\n```\n\nThis library is available on NPM, to install:\n```\nnpm install vue-datatables-net\n```\n\n## Usage\nDefault configuration and provide example for `bootstrap5` styling.  Though, it allow for complete flexibility of customization with any other jQuery DataTables supported theme.\n\n\u003e Example of imports for Bootstrap 5:\n\n```html\n\u003clink rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css\"\u003e\n\u003clink rel=\"stylesheet\" href=\"https://cdn.datatables.net/1.11.5/css/dataTables.bootstrap5.min.css\"\u003e\n\n\u003cscript src=\"https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/vue@next/dist/vue.global.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\nimport VdtnetTable from 'vue-datatables-net'\n\nimport 'datatables.net-bs5'\n\n// below you should only import what you need\n// Example: import buttons and plugins\nimport 'datatables.net-buttons/js/dataTables.buttons.js'\nimport 'datatables.net-buttons/js/buttons.html5.js'\nimport 'datatables.net-buttons/js/buttons.print.js'\n\n// import the rest for your specific theme\nimport 'datatables.net-buttons-bs5'\nimport 'datatables.net-select-bs5'\n\nimport 'datatables.net-select-bs5/css/select.bootstrap5.min.css'\nimport 'datatables.net-buttons-bs5/css/buttons.bootstrap5.min.css'\n\u003c/script\u003e\n```\n\n\u003e See example [App](https://niiknow.github.io/vue-datatables-net/)\n\nExample App demonstrate how to pass overrides for our [jQuery DataTable](https://datatables.net/manual/options) default options - https://github.com/niiknow/vue-datatables-net/blob/master/example/app.vue\n\n**NOTE:**\nOur example use a free API endpoint from [typicode](https://jsonplaceholder.typicode.com), which is simply a JSON endpoint.  As a result, we needed to define a `dataSrc` wrapper like so:\n```\najax: {\n  url: 'https://jsonplaceholder.typicode.com/users',\n  dataSrc: (json) =\u003e {\n    return json\n  }\n}\n```\n\nOf course, for your implementation, simply use a server-side compatible parser.  Below are some jQuery DataTables server-side parsers:\n* PHP - https://github.com/lampjunkie/php-datatables\n* PHP Symphony - https://github.com/stwe/DatatablesBundle\n* PHP Laravel - https://github.com/yajra/laravel-datatables\n* dotNET - https://github.com/ALMMa/datatables.aspnet, https://github.com/garvincasimir/csharp-datatables-parser\n* NodeJS - https://github.com/jpravetz/node-datatable\n* Rails - https://github.com/jbox-web/ajax-datatables-rails\n* Python - https://github.com/Pegase745/sqlalchemy-datatables\n\n## Documentation\nSince it's a wrapper, all/most features are provided by the [jQuery DataTables](https://datatables.net/manual/) library.\n\n## Parameters\nOur component parameters:\n```javascript\n  props: {\n    /**\n     * The table id - useful for saveState\n     *\n     * @type String\n     */\n    id: {\n      type: String\n    },\n    /**\n     * Set the container classes.\n     *\n     * @type String\n     */\n    containerClassName: {\n      type: String,\n      default: 'table-responsive d-print-inline'\n    },\n    /**\n     * Set the input column search classes.\n     *\n     * @type String\n     */\n    columnSearchClassName: {\n      type: String,\n    default: 'form-control form-control-sm'\n    },\n    /**\n     * Set the tfoot classes.\n     *\n     * @type String\n     */\n    tfootClassName: {\n      type: String,\n    },\n    /**\n     * Set the thead classes.\n     *\n     * @type String\n     */\n    theadClassName: {\n      type: String,\n    },\n    /**\n     * Set the table classes you wish to use, default with bootstrap5\n     * but you can override with: themeforest, foundation, etc..\n     *\n     * @type String\n     */\n    className: {\n      type: String,\n      default: 'table table-striped table-bordered nowrap w-100'\n    },\n    /**\n     * the options object: https://datatables.net/manual/options\n     *\n     * @type Object\n     */\n    opts: {\n      type: Object\n    },\n    /**\n     * List all fields to be converted to opts columns\n     *\n     * @type Object\n     */\n    fields: {\n      type: Object\n    },\n    /**\n     * Pass in DataTables.Net jQuery to resolve any conflict from\n     * multiple jQuery loaded in the browser\n     *\n     * @type Object\n     */\n    jquery: {\n      type: Object\n    },\n    /**\n     * The select-checkbox column index (start at 1)\n     * Current implementation require datatables.net-select\n     *\n     * @type Number\n     */\n    selectCheckbox: {\n      type: Number\n    },\n    /**\n     * Provide custom local data loading.  Warning: this option has not been\n     * thoroughly tested.  Please use ajax and serverSide instead.\n     *\n     * @type Function\n     */\n    dataLoader: {\n      type: Function\n    },\n    /**\n     * true to hide the footer of the table\n     *\n     * @type Boolean\n     */\n    hideFooter: {\n      type: Boolean\n    },\n    /**\n     * true to hide the tfoot of the table\n     *\n     * @type Boolean\n     */\n    hideTfoot: {\n      type: Boolean,\n      default: true\n    },\n    /**\n     * true to hide the individual column search of the table\n     *\n     * @type Boolean\n     */\n    columnSearch: {\n      type: Boolean,\n    default: false\n    },\n    /**\n     * The details column configuration of master/details.\n     *\n     * @type {Object}\n     */\n    details: {\n      type: Object\n    }\n  }\n```\n\n`fields` is an schema object that identify all datatables.net columns, example:\n\nExample:\n```javascript\nfields: {\n  _id: { label: \"ID\" },\n  title: { label: \"Title\", searchable: true, sortable: true },\n  type: { label: \"Type\" }\n}\n```\n\n### Field properties\n- `label` Title for display\n- `searchable` true to enable search of field\n- `sortable` false to disable sorting\n- `name` to override the name\n- `data` differentiate server-side sorting field - optional default to `name`\n- `visible` false to hide\n- `width` to provide custom width\n- `className` set column class names\n- `classHeaderName` set header class names\n- `classFooterName` set footer class names\n- `defaultContent` provide default html when no data available\n- `render` custom cell rendering function https://datatables.net/reference/option/columns.render\n- `template` simple vue template for the field.  See example App.\n- `defaultOrder` null, asc/desc - the default/initial sort order\n- `isLocal` same as setting both searchable and sortable to false\n- `index` allow for column positioning\n\n\u003e It is important to understand why it is better to use `fields` and not `opts.columns`.  Though, `fields` is optional if one wish to use the raw `opts.columns` definition.\n\nOne `Purpose` of this component is to extend jQuery DataTables function and features, example:\n* Simplification of features configuration, such as `select-checkbox` column, custom `action` buttons, and/or future Vue specific features.\n* Allow for customizable table heading on a per-column basis; thereby, not having to define all html for each column header.\n* Ability to have simple `template` field so you can pass schema JSON from static file or some API, instead of requiring to define a javascript `render` function.  Though, the `render` function would provide best performance.\n* Having schema also allow for future features, such as editable column/cell.\n\n### events\nCustom events for this component.\n```html\n\u003cvdtnet-table ...\n  @table-creating=\"doSomethingBeforeDataTableCreate\"\n  @table-created=\"doSomethingImmediatelyAfterTableCreatedAndInitialized\"\n  @reloaded=\"doSomethingAfterDataLoadOrReloaded\"\n/\u003e\n```\n\n```js\n   doSomethingImmediatelyAfterTableCreatedAndInitialized(vdtnet) {\n    // use vdtnet.dataTable to access the jQuery DataTables object, example:\n     vdtnet.dataTable.on( 'order.dt',  function () { eventFired( 'Order' ); } )\n   }\n```\n- `table-creating` this is right before jQuery(el).DataTable(component.options) is called allowing you to modify component options.\n- `table-created` this is after we called jQuery(el).DataTable and initialized all the columns.\n- `reloaded` this is after data has been load/reloaded\n\n## Additional Headers\nMany server-side usage require CSRF and/or API token headers.  Since jQuery DataTables `options` are completely exposed as `opts`, simply use the native method per [jQuery DataTables example](https://editor.datatables.net/manual/security#Prevention)\n\ni.e, something like:\n```javascript\nopts: {\n  'ajax': {\n    'url': url,\n    'type': 'GET',\n    'beforeSend': function (request) {\n        request.setRequestHeader(\"token\", token);\n    }\n  }\n}\n\n// or as headers parameter\nopts: {\n  'ajax': {\n    'url': url,\n    'type': 'GET',\n    'headers': {\n      'CSRFToken': TOKEN\n    }\n  }\n}\n\n// or as query parameter\nopts: {\n  'ajax': {\n    'url': url,\n    'type': 'GET',\n    'data': function ( d ) {\n      d.CSRFToken = TOKEN;\n    }\n  }\n}\n\n```\n\nIf you haven't already guessed, ajax is basically the signature of [jQuery.ajax](http://api.jquery.com/jquery.ajax/), which can be seen in this [jQuery DataTables ajax pipeline](https://datatables.net/examples/server_side/pipeline.html) code demonstration.\n\n## Row Action Buttons\nUse `data-action` attribute to automatically wire up any action button/elements.  To render action button/element in a row, simply define dummy field like so:\n```javascript\nactions: {\n  label: 'Actions',\n  defaultContent: '\u003ca href=\"javascript:void(0);\" data-action=\"edit\" class=\"btn btn-primary btn-sm\"\u003e\u003ci class=\"mdi mdi-square-edit-outline\"\u003e\u003c/i\u003e Edit\u003c/a\u003e' +\n    '\u003cspan data-action=\"delete\" class=\"btn btn-danger btn-sm\"\u003e\u003ci class=\"mdi mdi-delete\"\u003e\u003c/i\u003e Delete\u003c/span\u003e'\n}\n```\n\n## Reload method and reloaded event\nAllow you to refresh ajax content after some event.  Let say you have something like this:\n\n```html\n\u003ctemplate\u003e\n  \u003cdiv id=\"app\"\u003e\n    \u003cvdtnet-table\n      :fields=\"fields\"\n      :opts=\"options\"\n      ref=\"table\"\n      @delete=\"doAjaxDelete\"\n      @reloaded=\"doSomethingAfterReload\"\n    /\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n\u003cscript\u003e\n// ... component top ...\n  methods: {\n    doAjaxDelete(data, row, tr, target) {\n      // do some ajax delete\n      // then reload after ajax complete\n      this.$refs.table.reload()\n    },\n    doSomethingAfterReload(data, table) {\n      // some something after data loaded from server\n    }\n  }\n// ... component bottom ...\n```\n\n## Customizable table head (th) columns\nLet say you have a column `description`, you can provide table head template for the description column like so:\n```html\n\u003ctemplate v-slot:HEAD_description\u003e\n  \u003ch1\u003edesc\u003c/h1\u003e\n\u003c/template\u003e\n```\n\n## Customizable table footer (th) columns\nLet say you have a column `description`, you can provide table footer template for the description column like so:\n```html\n\u003ctemplate v-slot:FOOT_description\u003e\n  \u003ch1\u003edesc\u003c/h1\u003e\n\u003c/template\u003e\n```\n\n## dom (Searching and Toolbar)\n`dom` configuration defines how jQuery DataTables components are rendered - https://datatables.net/reference/option/dom\n\nOur default configuration compatible with Bootstrap5 is:\n```html\n\"tr\u003c'row vdtnet-footer'\u003c'col-sm-12 col-md-5'i\u003e\u003c'col-sm-12 col-md-7'pl\u003e\u003e\"\n```\n\nThis is based on the configuration `lftiprB`, also see: https://datatables.net/reference/option/dom\n\nNote, we do not include toolbar buttons (B) or search control (s).  This is because we defer these functions to you (the User).  Toolbar Buttons are client-side; and since we do not use client-side, we don't need these buttons.  We expose a `search` method on `vdtnet-table` so you can use this method to perform search.\n\nSimply create your own Buttons for server-side exports, bulk, and/or other things.  Create your own search control and use the `search` method.  See example App.  All these things are now Vue natives.\n\nThough, if you really insists on using these client-side controls, simply override the default `opts.dom` and `opts.buttons` with your own settings.\n\n## getServerParams method\nThis function return the parameters last used by our server-side endpoint.  It allow you to use for server-side export API call.  Example:\n```javascript\nconst parms = this.$refs.table.getServerParams()\nparms.export = 'csv'\n// boom export\nconst url = 'export.php?' + $.param(data)\nwindow.open(url)\n```\n\n## Responsive\n1. In Bootstrap5, there's a class called [table-responsive](https://getbootstrap.com/docs/5.0/content/tables/#responsive-tables) that wrap the table at each screen breakpoint.  We apply this class on our wrapper div to make the table scroll horizontally.  We also include `d-print-inline` for print.\n\n2. Alternatively, you can set `options.responsive = true` to use jQuery DataTable responsive plugin.  **WARNING**: This plugin does not play well with `select-checkbox`, `master-details`, and many other features.  It is recommended to use option 1 above.\n\n## Master-details pattern\n`details` configuration allow you to create template for displaying details row in Master-details pattern.  Schema:\n```javascript\n{\n  index: 'a number (start at 1) representing the column position',\n  template: 'the template where {{ data.column }} is the item/row data',\n  render: 'provide a custom render function as alternative to template'\n}\n```\n\n## Native templating (sort-of) explained\nTake a look at example app, you can template:\n```\n \u003ctemplate\n  v-slot:address2=\"ctx\"\n\u003e\n  \u003cspan\u003e{{ ctx.data.city }}, {{ ctx.comp.formatCode(ctx.data.zipcode) }}\u003c/span\u003e\n\u003c/template\u003e\n```\n\n- The context object will have the following properties\n  1. `data` the column value, in this case is `address` property which is an object with sub-properties (street, suite, city, zipcode, geo, etc...)\n  2. `type` the jQuery DataTables rendering type, usually `display`\n  3. `row` the entire row data\n  4. `meta` jQuery DataTables column config\n  5. `vdtnet` the vdtnet table object\n  6. `def` vdtnet field config\n  7. `comp` your component, notice how it demonstrate calling of a function on the example component to strip out all number after the dash.  You can use this to do things like permission checking.  Also see **Note** below.\n\n**Note**: Things that are related to display rendering should work.  Event handling doesn't work and I'm still looking for better way handle this.  Of course, you can still use `data-action` to handle clicks.\n\n## Export\nThis is something you want to explore on your own.  We try our best to provide as much example of export as possible in our demo, but Server-Side and/or Language/Framework Specific Code is too much/time-consuming to dive into.  Also, sometime output rendering are ties to specific requirement and cannot generically meet everyone needs.  We suggest that you create a Bounty for your specific needs.\n\n**Client-Side**\nThis is mostly provided by jQuery DataTables.  We demonstrate in our default demo.  You can find the documentation for [Buttons](https://datatables.net/extensions/buttons/) directly on the jQuery DataTables website.\n\n**Server-Side**\nOur demo for server-side export is here: https://laratt.niiknow.org/home/contacts\n\nThe source of the demo can be found here: https://github.com/niiknow/laratt-api\nAnd, specifically, the client-side vue component usage source: https://github.com/niiknow/laratt-api/blob/5117bfae1273b31f95af6aa99c51aae7fc413d2f/resources/js/components/DataTableNet.vue#L148\n\nThe code use `convention` to calculate a route/url as:\n```\nurl: that.$app.apiRoute(that.rName, that.rPath),\n```\n\nWhich result to a URL like so: https://laratt.niiknow.org/api/v1/democontact/example?x-tenant=test\u0026x-api-key=demo123\n\nAnd the server-side source for the export is simply: https://github.com/niiknow/laratt-api/blob/876ce385fc64d83b564f2e697790465675741634/api/Controllers/DemoContactController.php#L90\n\nAs far as PDF export, you will need to handle this yourself.  Tip, use [laravel-snappy](https://github.com/barryvdh/laravel-snappy).  The basic concept is to render your result to some html/blade template and use laravel-snappy to convert HTML to PDF.\n\n**Export Tip**\nOutside of csv export, most modern OS and Browser support PDF printing.  As a result, simply instruct the user to Print your page and use printing CSS to manipulate for exporting of PDF.\n\n## Tips\nIf you're like us, you want to write as little code as possible; as in, application of the DRY Principle.  This mean the UI has a standard look/feel/behavior; where toolbar, search, and other controls are place at specific location.  So this mean you want to wrap this component inside your own component?  Our sample App give you a good idea on how to start.  Below are a few things to consider:\n\n1. Identify all properties of the new component and howto translate into this component.  Example: hidePageLength -\u003e opts.lengthChange, hideQuickSearch -\u003e v-if on quickSearch form, hideToolbar -\u003e v-if on toolbar div, etc...\n2. Identify methods to wrap, i.e. your component API: reload, getServerParams, etc...\n3. Wrap individual action events you want to expose, or simply wrap with v-on=\"$listeners\" to pipe all events from this component to your component.\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniiknow%2Fvue-datatables-net","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniiknow%2Fvue-datatables-net","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniiknow%2Fvue-datatables-net/lists"}