Skip to content
This repository was archived by the owner on Apr 1, 2022. It is now read-only.

Commit a702543

Browse files
author
Ken Berkeley
committed
Release v2.0.0
1 parent 1d133da commit a702543

File tree

162 files changed

+1445
-18373
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

162 files changed

+1445
-18373
lines changed

‎.npmignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1+
.DS_Store
12
*.log
23
.git
34
node_modules
4-
docs
5+
doc
56
examples

‎README.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
# Vue2 Datatable
1+
# vue2-datatable-component
22

33
[![npm version][npm-v-img]][npm-url]
44
[![npm download][npm-dl-img]][npm-url]
55

6-
> The Best Datatable for Vue.js 2.x which never sucks
6+
> The best Datatable for Vue.js 2.x which never sucks
77
> `npm i -S vue2-datatable-component`
88
9-
[Documentation](https://OneWayTech.github.io/vue2-datatable/docs/_book) |
9+
[Documentation](https://OneWayTech.github.io/vue2-datatable/doc) |
1010
[Online examples](https://OneWayTech.github.io/vue2-datatable/examples/dist)
1111

1212
[npm-url]: https://www.npmjs.com/package/vue2-datatable-component

‎doc/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
> Choose a language · 请选择语言
2+
3+
- [English](en/)
4+
- [中文](zh-cn/)

‎doc/_coverpage.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# vue2-datatable-component
2+
3+
> The best Datatable for Vue.js 2.x which never sucks
4+
5+
[GitHub](https://github.com/OneWayTech/vue2-datatable)
6+
[Online examples](https://onewaytech.github.io/vue2-datatable/examples/dist)

‎doc/_images/structure.png

93.3 KB
Loading

‎doc/_sidebar.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
- Languages · 语言
2+
- [English](en/)
3+
- [中文](zh-cn/)

‎docs/en/DIY.md renamed to ‎doc/en/DIY.md

File renamed without changes.

‎doc/en/README.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# § Summary
2+
3+
> This Datatable is only for Vue 2.x.
4+
> But you can downgrade it according to [Migration from Vue 1.x](https://vuejs.org/v2/guide/migration.html).
5+
> (In most of the time, you just have to replace `ref / key / <hooks>`)
6+
7+
There are plenty of open-source Datatables, but none of them could meet all the scenarios.
8+
(if there is, this project has no meanings at all)
9+
10+
This documentation is dedicated to letting you comprehend the design and the source code.
11+
Under this premise, you could build the most suitable Datatable for your own scenario.
12+
13+
The dependencies of this project are shown as below:
14+
15+
* BootStrap 3.x + Font Awesome 4.x（must available globally）
16+
* [lodash.orderBy](https://lodash.com/docs/4.17.4#orderBy)
17+
* [replace-with](https://github.com/kenberkeley/replace-with)
18+
19+
P.S. *BootStrap* and *Font Awesome* can be replaced with other popular libraries.
20+
(It seems to me that you just have to replace some classes / styles)

‎doc/en/_sidebar.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
- [Summary](en/README)
2+
- [Preparation](en/preparation)
3+
- [Getting started](en/getting-started)
4+
- [Details (click me)](en/details/README)
5+
- [`props` of Datatable](en/details/datatable-props)
6+
- [`:columns`](en/details/props-columns)
7+
- [`:data`](en/details/props-data)
8+
- [`:query`](en/details/props-query)
9+
- [`:selection`](en/details/props-selection)
10+
- [`:xprops`](en/details/props-xprops)
11+
- [Dynamic Components](en/details/dynamic-comps)
12+
- [I18N](en/i18n)
13+
- [DIY](en/DIY)
14+
- [Q & A (issues)](https://github.com/OneWayTech/vue2-datatable/issues)
15+
- [Changelog (releases)](https://github.com/OneWayTech/vue2-datatable/releases)

‎doc/en/details/README.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# § Details
2+
3+
It would be better for you to understand the structure of this Datatable before the details.
4+
5+
The source tree [`lib/`](https://github.com/OneWayTech/vue2-datatable/tree/master/lib) is shown as below:
6+
7+
```
8+
lib/
9+
├─ HeaderSettings/
10+
│   ├─ ColumnGroup.vue
11+
│   └─ index.vue
12+
├── MainTable
13+
│   ├─ _SCROLLBAR_WIDTH.js
14+
│   ├─ _syncScroll.js
15+
│   ├─ HeadSort.vue
16+
│   ├─ index.vue
17+
│   ├─ MultiSelect.vue
18+
│   ├─ TableBody.vue
19+
│   ├─ TableFooter.vue
20+
│   ├─ TableFrame.vue
21+
│   └─ TableHeader.vue
22+
├─ index.vue
23+
├─ LimitSelect.vue
24+
├─ Pagination.vue
25+
└─ props.mixin.js
26+
```
27+
28+
Here is the illustration for the tree above, which is captured from the advanced example (source: [`examples/src/Advanced/index.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/examples/src/Advanced/index.vue), demo: [examples#advanced](https://OneWayTech.github.io/vue2-datatable/examples/dist#advanced)):
29+
30+
<a href="_images/structure.png" target="_blank" title="Click to enlarge">
31+
<img src="_images/structure.png" alt="Structure">
32+
</a>

‎doc/en/details/datatable-props.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# § `props` of Datatable
2+
3+
> Source: [`lib/props.mixin.js`](https://github.com/OneWayTech/vue2-datatable/blob/master/lib/props.mixin.js)
4+
5+
| prop | Desc | Type | Optional values | Default value | Required |
6+
|---|---|---|---|---|---|
7+
| columns | Defination of columns | Array | - | - | Y |
8+
| data | Data of the current page (rows) | Array | - | - | Y |
9+
| total | Total number of the records | Number | - | - | Y |
10+
| query | Query object | Object | - | - | Y |
11+
| selection | Container for multi-select | Array | - | - | N |
12+
| summary | Summary row | Object | - | - | N |
13+
| xprops | Carrier for extra props passed to dynamic components | Object | - | - | N |
14+
| HeaderSettings | Whether to render `HeaderSettings` | Boolean | true / false | true | N |
15+
| Pagination | Whether to render pagination relevant | Boolean | true / false | true | N |
16+
| tbl-class | Classes for `<table>` | String / Object / Array | - | - | N |
17+
| tbl-style | Inline styles for `<table>` | String / Object / Array | - | - | N |
18+
| fixHeaderAndSetBodyHeight | (Just as its name implies) | Number | - | - | N |
19+
| support-backup | Whether to enable backup of `HeaderSettings` | Boolean | true / false | false | N |
20+
| support-nested | Whether to enable `nested components` feature (`accordion` mode is available) | Boolean / String | true / false / 'accordion' | false | N |
21+
22+
> The advanced example (source: [`examples/src/Advanced/index.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/examples/src/Advanced/index.vue), demo: [examples#advanced](https://OneWayTech.github.io/vue2-datatable/examples/dist#advanced))
23+
> almost covers all the usages, which is highly recommended to study and imitate.
24+
25+
In the following sections, these props would be elaborated:
26+
27+
* `columns`
28+
* `data`
29+
* `query`
30+
* `selection`
31+
* `summary`
32+
* `xprops`
33+
* Dynamic components（`thComp / tdComp / nested component`）

‎docs/_book/en/detailed/dynamic-comps.md renamed to ‎doc/en/details/dynamic-comps.md

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,46 @@
11
# § Dynamic Components（`thComp / tdComp / nested component`）
22

3-
> The following code is excerpted from the source [`lib/index.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/lib/index.vue)
4-
53
## ⊙ `thComp`
64

5+
> Source: [`lib/MainTable/TableHeader.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/lib/MainTable/TableHeader.vue)
6+
77
```html
8-
<!-- table head component (thComp) -->
9-
<component v-if="column.thComp"
10-
:is="comp[column.thComp]"
11-
:column="column"
12-
:field="column.field"
13-
:title="column.title"
8+
<!-- <th> component (thComp) -->
9+
<component
10+
v-if="col.thComp"
11+
:is="comp[col.thComp]"
12+
:column="col"
13+
:field="col.field"
14+
:title="col.title"
1415
v-bind="$props">
1516
</component>
1617
```
1718

1819
| prop | Desc | Type |
19-
|-----------|------------------------|--------------------|
20+
|---|---|---|
2021
| column | Defination of column | Object |
2122
| field | Field name | String / undefined |
2223
| title | Displayed title | String / undefined |
2324
| `...$props` | all the `props` from Datatable | (Spread) |
2425

2526
## ⊙ `tdComp`
2627

28+
> Source: [`lib/MainTable/TableBody.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/lib/MainTable/TableBody.vue)
29+
2730
```html
28-
<!-- table body component (tdComp) -->
29-
<component v-if="column.tdComp"
30-
:is="comp[column.tdComp]"
31-
:row="item"
32-
:field="column.field"
33-
:value="item[column.field]"
34-
:nested="item.__nested__"
31+
<!-- <td> component (tdComp) -->
32+
<component
33+
v-if="col.tdComp"
34+
:is="comp[col.tdComp]"
35+
:row="summary"
36+
:field="col.field"
37+
:value="summary[col.field]"
3538
v-bind="$props">
3639
</component>
3740
```
3841

3942
| prop | Desc | Type |
40-
|-----------|------------------------|--------------------|
43+
|---|---|---|
4144
| row | Current row | Object |
4245
| field | Field name | String / undefined |
4346
| value | Value | Any |
@@ -46,6 +49,8 @@
4649

4750
## ⊙ `nested component`
4851

52+
> Source: [`lib/MainTable/TableBody.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/lib/MainTable/TableBody.vue)
53+
4954
```html
5055
<!-- nested component -->
5156
<component
@@ -57,7 +62,7 @@
5762
```
5863

5964
| prop | Desc | Type |
60-
|-----------|------------------------|--------------------|
65+
|---|---|---|
6166
| row | Current row | Object |
6267
| nested | Controller of the related nested component（reference to `row.__nested__`） | Object / undefined |
6368
| `...$props` | all the `props` from Datatable | (Spread) |

‎doc/en/details/props-columns.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# `:columns`
2+
3+
These are the properties of `columns[i]`:
4+
5+
| Attr | Desc | Type | Optional values | Default value | Required |
6+
|---|---|---|---|---|---|
7+
| title | Displayed title | String | - | - | N |
8+
| label | Label in `HeaderSettings` (`title` will take its place if not set) | String | - | - | N |
9+
| field | Field name of the row | String | - | - | N |
10+
| explain | Explanation of the field (tooltip) | String | - | - | N |
11+
| sortable | Is sortable | Boolean | true / false | false | N |
12+
| visible | Is visible | Boolean / String (if the type is String, the visibility is not allowed to toggle) | true / false / 'true' / 'false' | true | N |
13+
| fixed | Is fixed | Boolean / String | true / false / 'left' / 'right' | - | N |
14+
| group | Group name | String | - | - | N |
15+
| colClass | Classes for the whole column | String / Object | - | - | N |
16+
| colStyle | Inline styles for the whole column | Object | - | - | N |
17+
| thClass | Classes for `<th>` | String | - | - | N |
18+
| thStyle | Inline styles for `<th>` | Object | - | - | N |
19+
| thComp | Name of dynamic component for `<th>` | String | - | - | N |
20+
| tdClass | Classes for `<td>` | String | - | - | N |
21+
| tdStyle | Inline styles for `<td>` | Object | - | - | N |
22+
| tdComp | Name of dynamic component for `<td>` | String | - | - | N |

‎doc/en/details/props-data.md

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# `:data`
2+
3+
> In a more semantic way, it should be named `rows`.
4+
> However, most of the popular Datatables prefer `data`, which should be complied with.
5+
6+
Normally, it's not necessary to talk about this prop (it's too simple).
7+
But this Datatable supports `nested components` feature by performing magic on it.
8+
9+
It would be more direct to excerpt `watch:data` from the source code ([`lib/index.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/lib/index.vue)) to see how it works:
10+
11+
```js
12+
watch: {
13+
data: {
14+
handler (data) {
15+
const { supportNested } = this
16+
// support nested components feature with extra magic
17+
if (supportNested) {
18+
data.forEach(item => {
19+
if (!item.__nested__) {
20+
this.$set(item, '__nested__', {
21+
comp: '', // name of the current nested component
22+
visible: false,
23+
$toggle (comp, visible) {
24+
switch (arguments.length) {
25+
case 0:
26+
this.visible = !this.visible
27+
break
28+
case 1:
29+
switch (typeof comp) {
30+
case 'boolean':
31+
this.visible = comp
32+
break
33+
case 'string':
34+
this.comp = comp
35+
this.visible = !this.visible
36+
break
37+
}
38+
break
39+
case 2:
40+
this.comp = comp
41+
this.visible = visible
42+
break
43+
}
44+
}
45+
})
46+
// omit the implementation of accordion...
47+
Object.defineProperty(item, '__nested__', { enumerable: false })
48+
}
49+
})
50+
}
51+
},
52+
immediate: true
53+
}
54+
}
55+
```
56+
57+
According to the above, an **unenumerable** property `__nested__` is `$set` in every item (row) of data (rows), which includes three properties:
58+
59+
| Attr | Desc | Type | Optional values / usages | Default value |
60+
|---|---|---|---|---|
61+
| comp | Name of the current nested component | String | - | '' |
62+
| visible | Is the nested component visible | Boolean | true / false | false |
63+
| $toggle | A convenient API to control `comp` and `visible` | Function | `$toggle(comp)` / `$toggle(visible)` / `$toggle(comp, visible)` | - |
64+
65+
In the source template, `__nested__` would be passed to the related `tdComp` and `nested components`:
66+
67+
```html
68+
<!-- <td> component (tdComp) -->
69+
<component
70+
v-if="col.tdComp"
71+
:is="comp[col.tdComp]"
72+
:row="item"
73+
:field="col.field"
74+
:value="item[col.field]"
75+
:nested="item.__nested__"
76+
v-bind="$props">
77+
</component>
78+
79+
<!-- nested component -->
80+
<component
81+
:is="comp[item.__nested__.comp]"
82+
:row="item"
83+
:nested="item.__nested__"
84+
v-bind="$props">
85+
</component>
86+
```
87+
88+
By doing all these, we can control the `nested component` by `props.nested.$toggle` within the corresponding dynamic components.
89+
(Of cource, you can manipulate `props.row.__nested__` directly, which is the same thing but more verbose)
90+
91+
> In the advanced example, component [`Opt`](https://github.com/OneWayTech/vue2-datatable/blob/master/examples/src/Advanced/comps/td-Opt.vue) makes a full use of `props.nested`, which is highly recommended to study and imitate.

0 commit comments

Comments
 (0)