diff --git a/deploy-docs.sh b/deploy-docs.sh new file mode 100755 index 00000000..90894f79 --- /dev/null +++ b/deploy-docs.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env sh + +# abort on errors +set -e + +# build +npm run docs:build + +# navigate into the build output directory +cd docs/.vuepress/dist + +# if you are deploying to a custom domain +# echo 'www.example.com' > CNAME + +git init +git add -A +git commit -m 'deploy' + +# if you are deploying to https://.github.io +# git push -f git@github.com:/.github.io.git master + +# if you are deploying to https://.github.io/ +git push -f git@github.com:xaksis/vue-good-table.git master:gh-pages + +cd - \ No newline at end of file diff --git a/docs/.vuepress/components/before-after-columns.vue b/docs/.vuepress/components/before-after-columns.vue new file mode 100644 index 00000000..59786e9c --- /dev/null +++ b/docs/.vuepress/components/before-after-columns.vue @@ -0,0 +1,81 @@ + + + + + diff --git a/docs/.vuepress/components/checkbox-table.vue b/docs/.vuepress/components/checkbox-table.vue new file mode 100644 index 00000000..2c78712a --- /dev/null +++ b/docs/.vuepress/components/checkbox-table.vue @@ -0,0 +1,74 @@ + + + + + diff --git a/docs/.vuepress/components/custom-row.vue b/docs/.vuepress/components/custom-row.vue new file mode 100644 index 00000000..9969be1a --- /dev/null +++ b/docs/.vuepress/components/custom-row.vue @@ -0,0 +1,69 @@ + + + + + diff --git a/docs/.vuepress/components/grouped-table.vue b/docs/.vuepress/components/grouped-table.vue new file mode 100644 index 00000000..61d02c06 --- /dev/null +++ b/docs/.vuepress/components/grouped-table.vue @@ -0,0 +1,90 @@ + + + + + diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 5496a913..56758acc 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -1,6 +1,7 @@ module.exports = { title: 'vue-good-table', description: 'A powerful and easy to use data table plugin for VueJS', + base: '/vue-good-table/', themeConfig: { repo: 'xaksis/vue-good-table', sidebar: { @@ -25,6 +26,16 @@ module.exports = { '/guide/configuration/column-filter-options', ] }, + { + title: 'Avanced Configuration', + collapsable: false, + children: [ + '/guide/advanced/', + '/guide/advanced/checkbox-table', + '/guide/advanced/grouped-table', + '/guide/advanced/remote-workflow', + ] + }, { title: 'Style Configuration', collapsable: false, diff --git a/docs/guide/advanced/README.md b/docs/guide/advanced/README.md new file mode 100644 index 00000000..a85e4502 --- /dev/null +++ b/docs/guide/advanced/README.md @@ -0,0 +1,72 @@ +# Customizations + +## Custom Row Template + +Sometimes you might want to customize exactly how rows are displayed in a table. Vue-good-table also supports dynamic td templates where you dictate how to display the cells. Example: +```html + + + +``` + +### Result + + +::: tip NOTE +* The original row object can be accessed via `props.row` +* The currently displayed table row index can be accessed via `props.index` . +* The original row index can be accessed via `props.row.originalIndex`. You can then access the original row object by using `rows[props.row.originalIndex]`. +* The column object can be accessed via `props.column` +* You can access the formatted row data (for example - formatted date) via `props.formattedRow` +::: + +## Adding custom columns + +Sometimes you might want to add columns to the table that are not part of your row data. Maybe before or after the other columns. + +```html + + + +``` + +### Result + + +## Custom column headers +Sometimes you might want to customize column headers. You can do that in the following way +```html + + + +``` \ No newline at end of file diff --git a/docs/guide/advanced/checkbox-table.md b/docs/guide/advanced/checkbox-table.md new file mode 100644 index 00000000..01f3f0ba --- /dev/null +++ b/docs/guide/advanced/checkbox-table.md @@ -0,0 +1,70 @@ +# Checkbox Table + +One of the most common customizations in datatables is selectable rows. Creating a checkbox table with **vue-good-table** is easier than ever. + + +## Configuration + +type: `Object` + +Object containing select options +```html + +``` + + + +you can also programmatically get selected rows at any time by putting a `ref` on the table and then doing + +```js +this.$refs['my-table'].selectedRows; +``` + +### Example +```vue + + +``` + + + + +## Selected row action slot +Once you select a row, an info bar shows up. This bar allows for a customizable slot for your action buttons. + +### Example + +```html + +
+ +
+ +``` + + diff --git a/docs/guide/advanced/grouped-table.md b/docs/guide/advanced/grouped-table.md new file mode 100644 index 00000000..d302b7de --- /dev/null +++ b/docs/guide/advanced/grouped-table.md @@ -0,0 +1,87 @@ +# Grouped Table + +To create grouped rows, you need two things. +#### 1. Add groupOptions to table component +```html + + +``` + +#### 2. Make sure the rows are formatted correctly. Grouped rows need to be nested with headers rows containing rows in their children property. For example: + +```js +rows: [{ + mode: 'span', // span means this header will span all columns + label: 'Header Two', // this is the label that'll be used for the header + children: [ + { name: 'Chris', age: 55, createdAt: '2011-10-11', score: 0.03343 }, + { name: 'Dan', age: 40, createdAt: '2011-10-21', score: 0.03343 }, + ] +}] +``` + + + + +#### 3. Sometimes, you might want a summary row instead of a header row. For example, if you want to show total score for your group + +```javascript +rows: [{ + name: 'Total', // this is the label that'll be used for the header + age: undefined, + createdAt: undefined, + score: 0.3, // total score here + children: [ + { name: 'Chris', age: 55, createdAt: '2011-10-11', score: 0.03343 }, + { name: 'Dan', age: 40, createdAt: '2011-10-21', score: 0.03343 }, + ] +}] +``` + +#### 4. If you want the header/summary row to show up at the bottom of the group, you can specify that in the groupOptions property of the table. +```html + + +``` + + +#### 5. What if you wanted to add a total count in summary rows? + +In your column definition add a property, `headerField`. This is just like `field` property but for summary/header rows only. So lets say we wanted to add a **sum function** to this field. + +```js +// in columns +{ + label: 'Count', + field: 'count', + headerField: this.sumCount, + type: 'number', +}, + +// in methods we define sumCount +methods: { + sumCount(rowObj) { + console.log(rowObj); + let sum = 0; + for (let i = 0; i < rowObj.children.length; i++) { + sum += rowObj.children[i].count; + } + return sum; + }, +}, + +``` + + + diff --git a/docs/guide/advanced/remote-workflow.md b/docs/guide/advanced/remote-workflow.md new file mode 100644 index 00000000..93b1a19a --- /dev/null +++ b/docs/guide/advanced/remote-workflow.md @@ -0,0 +1,152 @@ +# Server Side Table + +## Why Remote Mode? + +Vue-good-table's in-built features like sorting, paging, filtering etc. are all performed client side and therefore are great for most of the use-cases. Sometimes though, we might have **too much data to render all of it at once on the UI**. In such cases, we would want to do things like sorting, paging, filtering on the server side. Fortunately, vue-good-table comes with `remote mode` to switch from client side to server side. + +When remote mode is on, vue-good-table does not perform sorting, paging, filtering etc. on the client side but instead emits events that we can use to then send proper parameters to the back-end. The server then is expected to send the correct rows to display on the UI. + +Following is a workflow you can use to get a server powered vue-good-table instace: + +## Prep Work +### What do we send to server? + +Before we dive into remote mode, lets agree on what we're going to be sending to the server. A set of parameters that tells the server exactly what rows I need to get back. Here's a proposed parameter object to send: + +```js +serverParams: { + // a map of column filters example: {name: 'john', age: '20'} + columnFilters: { + }, + sort: { + field: '', // example: 'name' + type: '' // 'asc' or 'desc' + }, + + page: 1, // what page I want to show + perPage: 10 // how many items I'm showing per page +} +``` +With the above information, server should be able to generate the relevant rows to send back. + +### What does the server send back? +Two things are required for the server to send back +1. **relevant rows** - set of rows for the current page, matching the current filter and sort. +2. **totalRecords** - number of total records matching the params we sent (not just the current page). This is required for the pagination to work correctly. + +## Set mode to remote + +```html + +``` +this tells VGT to not do client side paging/sorting/filtering + +## Provide handlers for user events + +Now instead of doing the above client side, each user interaction will generate events. So lets provide handlers for those events: +```html + +``` + +... in data +```javascript +data() { + return { + columns: [ + //... + ], + rows: [], + totalRecords: 0, + serverParams: { + columnFilters: { + }, + sort: { + field: '', + type: '', + }, + page: 1, + perPage: 10 + } + }; +}, +``` + +... handlers + +```javascript +methods: { + updateParams(newProps) { + this.serverParams = Object.assign({}, this.serverParams, newProps); + }, + + onPageChange(params) { + this.updateParams({page: params.currentPage}); + this.loadItems(); + }, + + onPerPageChange(params) { + this.updateParams({perPage: params.currentPerPage}); + this.loadItems(); + }, + + onSortChange(params) { + this.updateParams({ + sort: { + type: params.sortType, + field: this.columns[params.columnIndex].field, + }, + }); + this.loadItems(); + }, + + onColumnFilter(params) { + this.updateParams(params); + this.loadItems(); + } + + // load items is what brings back the rows from server + loadItems() { + getFromServer(this.serverParams).then(response => { + this.totalRecords = response.totalRecords; + this.rows = response.rows; + }); + } +} +``` + +## So, what is happening? +1. Everytime the user interacts with the table, an appropriate event is emitted. +1. Along with this, VGT knows that this event will now result in fetching things from the backend. So it starts a loading screen. +1. In the handler of that event, we first update the `serverParams` and then send a request to the backend. +1. When we get the response back, we update both the totalRecords and the rows data objects. +1. Row object's update signifies to VGT that the loading event is now done, and VGT shows the new rows on the table. + +::: tip +If you want to show loading notification manually, you can do so using table's `:isLoading=true` property. +::: + +::: tip +to style the loading dom, you can use the slot - `loadingContent` +::: + +## Conclusion +So that wasn't too bad. You now have VGT that's powered completely by your backend server. + diff --git a/docs/guide/configuration/README.md b/docs/guide/configuration/README.md index 357cae35..0e709bfc 100644 --- a/docs/guide/configuration/README.md +++ b/docs/guide/configuration/README.md @@ -38,7 +38,7 @@ Array containing row objects. Each row object contains data that will be display ] ``` ::: tip -for **grouped rows**, you need a nested format. Refer to [Grouped Rows](#grouped-rows) for an example. +for **grouped rows**, you need a nested format. Refer to [Grouped Table](/guide/advanced/grouped-table.md) for examples. ::: ## lineNumbers @@ -72,7 +72,7 @@ type: `String` Set mode=`remote` to allow sorting/filtering etc to be powered by server side instead of client side. -for a detailed workflow example check out [Server Side Workflow](https://github.com/xaksis/vue-good-table/wiki/Remote-Mode-Workflow) +for a detailed workflow example check out [Server Side Workflow](/guide/advanced/remote-workflow.md) ```html