@sulzanoks/vue-datatable 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,130 +1,199 @@
1
- # DatatableCard Component
2
-
3
- DatatableCard is a custom Vue.js component designed to provide a flexible and customizable datatable for your web applications. It is built from scratch, inspired by the Bootstrap datatable, but with added features to support Vue.js style links and row selection.
4
-
5
- ## Installation
6
-
7
- You can install the DatatableCard component using npm:
8
-
9
- ```bash
10
- npm install @sulzanoks/vue-datatable
11
- ```
12
-
13
- ## Usage
14
-
15
- To use the DatatableCard component in your Vue.js application, you can import it and include it in your component's template. Here's an example of how to use it:
16
-
17
- ```vue
18
- <template>
19
- <div>
20
- <datatable-card
21
- :card-title="cardTitle"
22
- :columns="columns"
23
- :url="dataUrl"
24
- >
25
- </datatable-card>
26
- </div>
27
- </template>
28
-
29
- <script>
30
- import DatatableCard from '@sulzanoks/vue-datatable';
31
- import '@sulzanoks/vue-datatable/dist/style.css';
32
-
33
- export default {
34
- components: {
35
- DatatableCard,
36
- },
37
- data() {
38
- return {
39
- cardTitle: 'My Datatable',
40
- columns: [
41
- // Define your datatable columns here
42
- // Example: { data: 'id', name: 'ID', sortable: true, searchable: true }
43
- ],
44
- dataUrl: '/api/data', // Replace with your data endpoint URL
45
- };
46
- },
47
- };
48
- </script>
49
- ```
50
-
51
- ## Props
52
-
53
- The DatatableCard component accepts the following props:
54
-
55
- - `cardTitle` (String): The title for the datatable card.
56
- - `clickable-rows` (Boolean, optional, default: false): Set to true to enable `row-click` event.
57
- - `columns` (Array): An array of column objects defining the datatable columns.
58
- - `data` (String): The key to access the data for this column in the API response.
59
- - `displayName` (String): The display name or label for this column.
60
- - `name` (String): The unique name or identifier for this column.
61
- - `searchable` (Boolean, optional, default: true): Set to `false` to disable searching for this column.
62
- - `sortable` (Boolean, optional, default: true): Set to `false` to disable sorting for this column.
63
- - `visible` (Boolean, optional, default: true): Set to `false` to remove column from table.
64
- - `width` (String, optional): Set solumn to width specified css param.
65
- - `linkParams` (Object, optional): Defines link parameters for generating Vue.js style links.
66
- - `name` (String): The name of the Vue.js route to navigate to when clicking the link.
67
- - `resourceIds` (Array): An array of resource IDs to use in generating the link. Replace with actual resource IDs.
68
- - `query` (Object, optional): object of attributes to include in link query params
69
- - `url` (String): The URL for fetching datatable data.
70
- - `selectableRows` (Boolean): Set to `true` to enable row selection. For now only works if you have a, `id` column in your data set.
71
- - `order` (Array): The initial column sorting order. example: `[{ column: 0, dir: 'asc' }]`
72
- - `advancedSearch` (Boolean): Set to `true` to enable advanced search, which generates an individual search input for each searchable column.
73
- - `loadDataOnInit` (Boolean): Set to `true` to load data when the component is initialized.
74
- - `cardIconStyle` (String, optional, default: 'card-header-primary'. There are no other options): The CSS class to apply to the card's header for icon styling.
75
- - `cardIcon` (String, optional, default: null): The name of an icon from [Google Icons](https://fonts.google.com/icons) to display in the card's header. Provide the icon name without any additional markup, such as `<i>` tags. For example, if you want to use the "account_circle" icon, set this prop to `'account_circle'`. If not specified, no icon will be displayed in the card's header.
76
- - `cardClasses` (String, optional, default: null): Additional CSS classes to apply to the card.
77
- - `createLink` (String, optional, default: null): A link or URL to navigate to when clicking a "Create" button or link within the card.
78
- - `requestQueryParams` (Object, optional): additional request query parameters to include when loading data from server.
79
- - `actions` (Array, optional): Array of action objects defining action buttons for each row.
80
- - `emit` (String, required): name of event to emit upon click
81
- - `icon` (String, optional): The name of an icon from [Google Icons](https://fonts.google.com/icons) to display inside button.
82
- - `label` (String, optional): Text to display inside button.
83
- - `class` (String, optional): CSS class to apply to button.
84
-
85
- ## Internal Methods
86
-
87
- These methods are meant to be used by component internally, but maybe you can find use for them
88
-
89
- - `toggleSearch()`: Toggle the search input.
90
- - `clearSearch()`: Clear the search bar and reload data.
91
- - `setAdvancedSearchFilters()`: Set advanced search filters based in input element values and reload data.
92
- - `loadData()`: Load datatable data.
93
- - `initColumnSettings()`: Initialize column settings.
94
- - `setPageLength(length)`: Set the number of rows per page and reload data.
95
- - `setPage(page)`: Set the current page and reload data.
96
- - `setSearchTerm()`: Set the full text search term for basic search on all columns and reload data.
97
- - `setSorting(index)`: Set the sorting order for a column and reload data.
98
- - `generateLink(linkParams, row)`: Generate a link based on parameters and row data.
99
- - `selectAllRows()`: Select or deselect all rows.
100
- - `clearSelectedRows()`: Clear the selected rows.
101
-
102
- ## Methods
103
- - `getSelectedRows()`: Returns array of selected rows
104
- - `filterColumns(params)`: Filter columns based on parameters and reload data.
105
- ```javascript
106
- this.$refs.myDataTable.filterColumns([
107
- {
108
- name: 'serial_number',
109
- value: this.uniqueId,
110
- },
111
- {
112
- name: 'product_name',
113
- value: this.productName,
114
- }
115
- ]);
116
- ```
117
- - `refresh()`: Clears all sorting and filters, reloads or clears data based on `loadDataOnInit` prop.
118
-
119
- ## Events
120
- - `row-click`: Emitted when row is click if `clickable-rows` prop is set to true. The event payload contains the clicked row data.
121
-
122
- ## Compatibility
123
-
124
- This component is designed to work with Laravel's [`yajra/laravel-datatables-oracle`](https://yajrabox.com/docs/laravel-datatables). It may work with other packages that use a similar input/output structure, but it has not been tested extensively with other packages.
125
-
126
- Please make sure that your Laravel backend and the API endpoints are configured to work with this component.
127
-
128
- ## License
129
-
1
+ # DatatableCard Component
2
+
3
+ DatatableCard is a custom Vue.js component designed to provide a flexible and customizable datatable for your web applications. It is built from scratch, inspired by the Bootstrap datatable, but with added features to support Vue.js style links and row selection.
4
+
5
+ ## Installation
6
+
7
+ You can install the DatatableCard component using npm:
8
+
9
+ ```bash
10
+ npm install @sulzanoks/vue-datatable
11
+ ```
12
+
13
+ ## Usage
14
+
15
+ To use the DatatableCard component in your Vue.js application, you can import it and include it in your component's template. Here's an example of how to use it:
16
+
17
+ ```vue
18
+ <template>
19
+ <div>
20
+ <datatable-card
21
+ :card-title="cardTitle"
22
+ :columns="columns"
23
+ :url="dataUrl"
24
+ >
25
+ </datatable-card>
26
+ </div>
27
+ </template>
28
+
29
+ <script>
30
+ import DatatableCard from '@sulzanoks/vue-datatable';
31
+ import '@sulzanoks/vue-datatable/dist/style.css';
32
+
33
+ export default {
34
+ components: {
35
+ DatatableCard,
36
+ },
37
+ data() {
38
+ return {
39
+ cardTitle: 'My Datatable',
40
+ columns: [
41
+ // Define your datatable columns here
42
+ // Example: { data: 'id', name: 'ID', sortable: true, searchable: true }
43
+ ],
44
+ dataUrl: '/api/data', // Replace with your data endpoint URL
45
+ };
46
+ },
47
+ };
48
+ </script>
49
+ ```
50
+
51
+ ## Props
52
+
53
+ The DatatableCard component accepts the following props:
54
+
55
+ - `cardTitle` (String): The title for the datatable card.
56
+ - `clickable-rows` (Boolean, optional, default: false): Set to true to enable `row-click` event.
57
+ - `columns` (Array): An array of column objects defining the datatable columns.
58
+ - `data` (String): The key to access the data for this column in the API response.
59
+ - `displayName` (String): The display name or label for this column.
60
+ - `name` (String): The unique name or identifier for this column.
61
+ - `searchable` (Boolean, optional, default: true): Set to `false` to disable searching for this column.
62
+ - `sortable` (Boolean, optional, default: true): Set to `false` to disable sorting for this column.
63
+ - `visible` (Boolean, optional, default: true): Set to `false` to remove column from table.
64
+ - `width` (String, optional): Set solumn to width specified css param.
65
+ - `linkParams` (Object, optional): Defines link parameters for generating Vue.js style links.
66
+ - `name` (String): The name of the Vue.js route to navigate to when clicking the link.
67
+ - `resourceIds` (Array): An array of resource IDs to use in generating the link. Replace with actual resource IDs.
68
+ - `query` (Object, optional): object of attributes to include in link query params
69
+ - `url` (String): The URL for fetching datatable data.
70
+ - `selectableRows` (Boolean): Set to `true` to enable row selection. For now only works if you have a, `id` column in your data set.
71
+ - `order` (Array): The initial column sorting order. example: `[{ column: 0, dir: 'asc' }]`
72
+ - `advancedSearch` (Boolean): Set to `true` to enable advanced search, which generates an individual search input for each searchable column.
73
+ - `loadDataOnInit` (Boolean): Set to `true` to load data when the component is initialized.
74
+ - `cardIconStyle` (String, optional, default: 'card-header-primary'. There are no other options): The CSS class to apply to the card's header for icon styling.
75
+ - `cardIcon` (String, optional, default: null): The name of an icon from [Google Icons](https://fonts.google.com/icons) to display in the card's header. Provide the icon name without any additional markup, such as `<i>` tags. For example, if you want to use the "account_circle" icon, set this prop to `'account_circle'`. If not specified, no icon will be displayed in the card's header.
76
+ - `cardClasses` (String, optional, default: null): Additional CSS classes to apply to the card.
77
+ - `createLink` (String, optional, default: null): A link or URL to navigate to when clicking a "Create" button or link within the card.
78
+ - `requestQueryParams` (Object, optional): additional request query parameters to include when loading data from server.
79
+ - `actions` (Array, optional): Array of action objects defining action buttons for each row.
80
+ - `emit` (String, required): name of event to emit upon click
81
+ - `icon` (String, optional): The name of an icon from [Google Icons](https://fonts.google.com/icons) to display inside button.
82
+ - `label` (String, optional): Text to display inside button.
83
+ - `class` (String, optional): CSS class to apply to button.
84
+
85
+ ## Link Parameters (`linkParams`)
86
+
87
+ The `generateLink` method now supports **two modes** for building links:
88
+
89
+ ### 1. Laravel Route Name (default / original behavior)
90
+
91
+ Use when you want to leverage Laravel named routes via Ziggy’s `route()` helper.
92
+
93
+ ```js
94
+ {
95
+ data: 'title',
96
+ linkParams: {
97
+ name: 'users.show', // Laravel route name
98
+ resourceIds: ['id'], // values taken from the row
99
+ query: { tab: 'info' } // optional query params
100
+ }
101
+ }
102
+ ```
103
+
104
+ ➡️ If `row.id = 5`, this builds:
105
+ ```
106
+ /users/5?tab=info
107
+ ```
108
+
109
+ ### 2. Link Template
110
+
111
+ Use when you want full control over the URL structure without relying on Laravel route names.
112
+
113
+ #### Object Form
114
+ ```js
115
+ {
116
+ data: 'title',
117
+ linkParams: {
118
+ template: '/users/{id}/posts/{post_id}',
119
+ params: { post_id: 'latest' }, // override or add interpolation values
120
+ query: { filter: 'active' } // optional query params
121
+ }
122
+ }
123
+ ```
124
+ ➡️ If `row.id = 5`, this builds:
125
+ ```
126
+ /users/5/posts/latest?filter=active
127
+ ```
128
+
129
+ #### String Shorthand
130
+ ```js
131
+ {
132
+ data: 'title',
133
+ linkParams: '/users/{id}'
134
+ }
135
+ ```
136
+ ➡️ If `row.id = 5`, this builds:
137
+ ```
138
+ /users/5
139
+ ```
140
+
141
+ ### Template Placeholders
142
+
143
+ Templates support both styles:
144
+ - `{key}` → `/users/{id}`
145
+ - `:key` → `/users/:id`
146
+
147
+ Both will be replaced with the row’s value (or overridden via `params`).
148
+
149
+ ### Notes
150
+ - If both `params` and row values define the same key, `params` takes precedence.
151
+ - Query parameters (`query`) are supported in both modes.
152
+ - If you just need a simple route name, use **mode 1**; if you want custom URLs, use **mode 2**.
153
+
154
+ ## Internal Methods
155
+
156
+ These methods are meant to be used by component internally, but maybe you can find use for them
157
+
158
+ - `toggleSearch()`: Toggle the search input.
159
+ - `clearSearch()`: Clear the search bar and reload data.
160
+ - `setAdvancedSearchFilters()`: Set advanced search filters based in input element values and reload data.
161
+ - `loadData()`: Load datatable data.
162
+ - `initColumnSettings()`: Initialize column settings.
163
+ - `setPageLength(length)`: Set the number of rows per page and reload data.
164
+ - `setPage(page)`: Set the current page and reload data.
165
+ - `setSearchTerm()`: Set the full text search term for basic search on all columns and reload data.
166
+ - `setSorting(index)`: Set the sorting order for a column and reload data.
167
+ - `generateLink(linkParams, row)`: Generate a link based on parameters and row data.
168
+ - `selectAllRows()`: Select or deselect all rows.
169
+ - `clearSelectedRows()`: Clear the selected rows.
170
+
171
+ ## Methods
172
+ - `getSelectedRows()`: Returns array of selected rows
173
+ - `filterColumns(params)`: Filter columns based on parameters and reload data.
174
+ ```javascript
175
+ this.$refs.myDataTable.filterColumns([
176
+ {
177
+ name: 'serial_number',
178
+ value: this.uniqueId,
179
+ },
180
+ {
181
+ name: 'product_name',
182
+ value: this.productName,
183
+ }
184
+ ]);
185
+ ```
186
+ - `refresh()`: Clears all sorting and filters, reloads or clears data based on `loadDataOnInit` prop.
187
+
188
+ ## Events
189
+ - `row-click`: Emitted when row is click if `clickable-rows` prop is set to true. The event payload contains the clicked row data.
190
+
191
+ ## Compatibility
192
+
193
+ This component is designed to work with Laravel's [`yajra/laravel-datatables-oracle`](https://yajrabox.com/docs/laravel-datatables). It may work with other packages that use a similar input/output structure, but it has not been tested extensively with other packages.
194
+
195
+ Please make sure that your Laravel backend and the API endpoints are configured to work with this component.
196
+
197
+ ## License
198
+
130
199
  This DatatableCard component is open-source software licensed under the MIT License. See the [LICENSE](LICENSE) file for more information.