update doc

niiknow · Nov 4, 2018 · d04c26e · d04c26e
1 parent 64be101
commit d04c26e
Show file tree

Hide file tree

Showing 8 changed files with 129 additions and 76 deletions.
diff --git a/README.md b/README.md
@@ -1,18 +1,19 @@
 # vue-datatables-net
 > Vue jQuery DataTable.net wrapper component 
 
-This library is simply a wrapper for [jQuery DataTable](https://datatables.net/).  It's a tiny package that doesn't include anything, not even the datatable.net core library.  Per example below, you basically have to include only/any datatable.net package(s) that you need.
+This library is a wrapper for [jQuery DataTable](https://datatables.net/).  It's a tiny package that doesn't include anything, not even the datatables.net core library.
 
-The initial focus/design of this library is to use with ajax/server-side endpoint.  For local data, simply use native methods like so:
+The initial focus/design of this library is to use with ajax/server-side endpoint.  Though, since it is a datatables.net wrapper, local data use/loading is simply:
 
 ```javascript
 component.dataTable.clear().draw();
 component.dataTable.rows.add(newDataArray).draw();
 ```
+
 ## Development
 This library uses the NodeJS library `laravel-mix` to simplify build and packaging.
 
-To run locally, it automatically launch firefox:
+To run locally (automatically launch firefox):
 ```
 npm run watch
 ```
@@ -37,20 +38,22 @@ import VdtnetTable from 'vue-datatables-net'
 import 'datatables.net-bs4'
 
 /*
-// you can import these if needed
-// this import all buttons that we need
+// you can import these on a needed basis
+// this import all buttons that we need, for
+// use with opts: { buttons: ['csv', 'print', ...]}
 import 'datatables.net-buttons/js/dataTables.buttons.js';
 import 'datatables.net-buttons/js/buttons.html5.js';
 import 'datatables.net-buttons/js/buttons.print.js';
 import 'datatables.net-responsive/js/dataTables.responsive.js';
 
-// import the rest
+// import any datatable extension as you would when using it raw
 import 'datatables.net-buttons-bs4'
 import 'datatables.net-responsive-bs4'
 import 'datatables.net-fixedheader-bs4'
 import 'datatables.net-scroller-bs4';
 import 'datatables.net-select-bs4';
 
+// import any styles to support the packages you import above
 import 'datatables.net-bs4/css/dataTables.bootstrap4.min.css';
 import 'datatables.net-buttons-bs4/css/buttons.bootstrap4.min.css';
 import 'datatables.net-responsive-bs4/css/responsive.bootstrap4.min.css';
@@ -60,12 +63,12 @@ import 'datatables.net-select-bs4/css/select.bootstrap4.min.css';
 </script>
 ```
 
-> Use it like the example App
+> See example [App](https://niiknow.github.io/vue-datatables-net/)
 
-This demonstrate how to pass in overrides for our [jQuery DataTable](https://datatables.net/manual/options) default options - https://github.com/niiknow/vue-datatables-net/blob/master/example/App.vue#L8
+Example App demonstrate how to pass in overrides for our [jQuery DataTable](https://datatables.net/manual/options) default options - https://github.com/niiknow/vue-datatables-net/blob/master/example/App.vue#L8
 
 **NOTE:**
-The example app use free API endpoint from typicode [https://jsonplaceholder.typicode.com] so it's not jQuery DataTable.net compatible.  As a result, we have to define a dataSrc wrapper like so:
+The example App use free API endpoint from typicode [https://jsonplaceholder.typicode.com] so it's not jQuery DataTable.net queryable.  As a result, we have to define a dataSrc wrapper like so:
 ```
 ajax: {
   url: 'https://jsonplaceholder.typicode.com/users',
@@ -75,55 +78,86 @@ ajax: {
 }
 ```
 
-Some example server-side ajax parsers implementation:
+Here are some server-side ajax parser implementation:
 * PHP - https://github.com/lampjunkie/php-datatables
 * PHP Symphony - https://github.com/stwe/DatatablesBundle
 * PHP Laravel - https://github.com/yajra/laravel-datatables
 * dotNET - https://github.com/ALMMa/datatables.aspnet, https://github.com/garvincasimir/csharp-datatables-parser
 * NodeJS - https://github.com/jpravetz/node-datatable
 * Rails - https://github.com/jbox-web/ajax-datatables-rails
 
-> Or simply with url that can handle datatable.net server-side endpoint:
-
-```html
-<template>
-  <div id="app">
-    <vdtnet-table :fields="fields" url="/some/api/using/yajra/laravel-datatables/or/similar" />
-  </div>
-</template>
+## Documentation
+Since it's a wrapper, all/most features are provided by the [jQuery DataTable](https://datatables.net/manual/) library.
 
-<script>
-import VdtnetTable from 'vue-datatables-net'
-import 'datatables.net-bs4'
+More documentations below.
 
-export default {
-  name: 'app',
-  components: { VdtnetTable },
-  data() {
-    const vm = this
-
-    return {
-      fields: {
-        id: { label: 'ID', sortable: true },
-        name: { label: 'Name', sortable: true, searchable: true },
-        username: { label: 'Username', sortable: false, searchable: true  },
-        email: { label: 'Email' },
-        phone: { label: 'Phone' },
-        website: { label: 'Website' }
-      }
-    }
+## Parameters
+Our component parameters:
+```javascript
+props: {
+  // Set the table classes you wish to use, default with bootstrap4
+  // but you can override with: themeforest, foundation, etc..
+  className: {
+    type: String,
+    default: 'table table-striped table-bordered dt-responsive nowrap w-100'
+  },
+  // the options object: https://datatables.net/manual/options
+  opts: {
+    type: Object
+  },
+  /**
+   * List all fields to be converted to opts columns
+   *
+   * @type {Object}
+   */
+  fields: {
+    type: Object
+  },
+  /**
+   * Pass in DataTables.Net loaded jQuery to resolve
+   * any multiple loaded browser jQuery conflict
+   *
+   * @type {Object}
+   */
+  jquery: {
+    type: Object
+  },
+  /**
+   * True to enable multi-select checkboxes
+   * Current implementation require datatables.net-select
+   *
+   * @type Boolean
+   */
+  selectable: {
+    type: Boolean
   }
-}
-</script>
+},
 ```
 
-## Documentation
-Since it's a wrapper, all/most features are provided by the [jQuery DataTable](https://datatables.net/manual/) library.
+`fields` is an schema object that identify all datatables.net columns, example:
 
-More documentations below.
+Example:
+```json
+fields: {
+  _id: { label: "ID" },
+  title: { label: "Title", searchable: true, sortable: true },
+  type: { label: "Type" }
+}
+```
+
+### Field properties
+- `label` Title for display
+- `searchable` true to enable search of field
+- `sortable` false to disable sorting
+- `name` to override the name
+- `visible` false to hide
+- `width` to provide custom width
+- `className` set column class names
+- `defaultContent` provide default html for null
+- `render` custom cell rendering function https://datatables.net/reference/option/columns.render
 
 ## Additional Headers
-Since options are completely exposed, simply use the native method per [jQuery DataTable example](https://editor.datatables.net/manual/security#Prevention)
+Many server-side usage require CSRF and/or API token headers.  Since options are completely exposed, simply use the native method per [jQuery DataTable example](https://editor.datatables.net/manual/security#Prevention)
 
 i.e, something like:
 ```javascript
@@ -141,7 +175,7 @@ options: {
 If you haven't already figured it out, ajax is basically the signature of [jQuery.ajax](http://api.jquery.com/jquery.ajax/) which is demonstrated here wrapped as [jQuery DataTable ajax pipeline](https://datatables.net/examples/server_side/pipeline.html)
 
 ## Row Action Buttons
-Use `data-action` attribute to automatically wire up any action button/elements.  To render action button/element in a row, simply define field like below (also, see example App):
+Use `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:
 ```javascript
 actions: {
   label: 'Actions',
@@ -150,11 +184,4 @@ actions: {
 }
 ```
 
-## Selectable
-> set this to enable datatable.net-select extension
-
-```html
- <vdtnet-table :selectable="true" />
-```
-
 # MIT