You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: adminforth/documentation/docs/tutorial/09-Plugins/08-import-export.md
+48-4Lines changed: 48 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,12 @@
1
1
---
2
2
title: Import Export
3
-
description: "Guide to the Import-Export plugin for CSV-based data transfer, including installation, import flow, export flow, and resource-level usage."
3
+
description: "Guide to the ImportExport plugin for CSV and XLSX data transfer, including installation, import flow, export flow, and resource-level usage."
4
4
slug: /tutorial/Plugins/import-export
5
5
---
6
6
7
7
# Import-Export
8
8
9
-
Import-Export is a plugin that allows you to import data from and export data to a CSV file.
9
+
ImportExport is a plugin that allows you to import and export resource data as CSV or Excel (`.xlsx`) files.
10
10
11
11
This plugin is mostly useful for the following use cases:
12
12
@@ -51,9 +51,41 @@ export default {
51
51
],
52
52
...
53
53
}
54
-
55
54
```
56
55
56
+
CSV import and export are enabled by default.
57
+
58
+
## File format
59
+
60
+
Set `fileFormat` on each plugin instance to choose the format used by both import and export:
61
+
62
+
```typescript
63
+
newImportExport({
64
+
fileFormat: 'xlsx',
65
+
})
66
+
```
67
+
68
+
Supported values are:
69
+
70
+
-`'csv'` (default)
71
+
-`'xlsx'`
72
+
73
+
For XLSX imports, the first row of each non-empty worksheet is treated as the column header. Rows from multiple worksheets are combined, but all non-empty worksheets must have the same columns in the same order.
74
+
75
+
Both classic and upload export support XLSX. A background XLSX export that exceeds Excel's limit of 1,048,575 data rows per worksheet is automatically split into multiple worksheets, with the header repeated on each worksheet.
76
+
77
+
## Export-only mode
78
+
79
+
Import is enabled by default. To expose only the export action, set `importEnabled` to `false`:
80
+
81
+
```typescript
82
+
newImportExport({
83
+
importEnabled: false,
84
+
})
85
+
```
86
+
87
+
This removes the import action from the resource UI and does not register the import endpoints. Export remains available in the selected `fileFormat`.
88
+
57
89
58
90
## Upload export
59
91
@@ -81,6 +113,7 @@ export default {
81
113
plugins: [
82
114
...
83
115
newImportExport({
116
+
fileFormat: 'xlsx', // optional; defaults to 'csv'
84
117
exportViaUpload: {
85
118
storageAdapter: newAdminForthAdapterS3Storage({
86
119
bucket: process.env.AWS_BUCKET_NAMEasstring,
@@ -94,5 +127,16 @@ export default {
94
127
],
95
128
...
96
129
}
97
-
130
+
```
131
+
132
+
The upload mode supports the same `fileFormat` values as classic export. You can also tune memory usage and database read size:
133
+
134
+
```typescript
135
+
newImportExport({
136
+
exportViaUpload: {
137
+
storageAdapter,
138
+
bufferSizeMb: 10, // defaults to 5 MiB; minimum is 5 MiB
#### Control Dashboard Access and Editing Permissions
191
191
192
-
By default, only users with the `superadmin` role can edit dashboards (add, rename, reorder, and remove groups or widgets). Use the `editRoles` option to grant editing to other roles:
192
+
By default, only users with the `superadmin` role can access dashboards. Use the `editRoles` option to grant dashboard access and editing to other roles:
193
193
194
194
```ts title="./globalPlugins.ts"
195
195
newDashboardPlugin({
@@ -198,7 +198,11 @@ new DashboardPlugin({
198
198
});
199
199
```
200
200
201
-
Users whose role is not listed in `editRoles` can view dashboards but are not shown the editing controls and cannot modify dashboards, groups, or widgets through the API.
201
+
Users whose role is not listed in `editRoles` do not see the **Dashboards** sidebar group and receive a `403` response from dashboard configuration and widget-data endpoints. The same role check protects all dashboard mutations on the backend.
202
+
203
+
Dashboard widget queries also respect the target resource's list access rules. Before loading data, the plugin checks `allowedActions.list`, runs the resource's `list.beforeDatasourceRequest` hooks, and applies any filters added by those hooks. A widget cannot query a column that is `backendOnly` or hidden from the current user with `showIn.list`.
204
+
205
+
When a query omits `select`, it implicitly requests every column. If the resource contains restricted columns, specify an explicit `select` containing only columns the dashboard users may list. These checks also apply to fields used only for filters, grouping, ordering, buckets, or sparklines.
202
206
203
207
Then pass it to the AdminForth configuration:
204
208
@@ -232,6 +236,22 @@ If you need to configure dashboards without using the AI Agent, you can do so ma
232
236
2. **Interactive UI Editor**: Users with a role listed in the plugin's `editRoles` option (defaults to `superadmin`) can add, rename, reorder, and remove groups or widgets directly from the user interface.
233
237
3. **YAML Configuration Editor**: The dashboard builder has built-in code editors. When editing a widget or a group manually, you write configurations using a YAML-based DSL.
234
238
239
+
### Editing dashboard settings
240
+
241
+
Click the tools icon in the dashboard header to edit the dashboard itself. The YAML editor accepts these fields:
242
+
243
+
```yaml
244
+
label: Sales Overview
245
+
slug: sales-overview
246
+
icon: flowbite:chart-pie-solid
247
+
```
248
+
249
+
- `label`is the page title and sidebar label.
250
+
- `slug`defines the URL at `/dashboard/<slug>`. It must contain only lowercase letters, numbers, and hyphens, and must be unique.
251
+
- `icon`is an optional [Iconify](https://icon-sets.iconify.design/) icon name used in the sidebar. Remove the field to use the default dashboard icon.
252
+
253
+
Saving a changed slug redirects the browser to the new dashboard URL.
254
+
235
255
For the complete schema specifications of queries, formulas, custom variables, layout fields, and advanced chart configurations, see the **[Dashboard Query Reference](/docs/tutorial/Plugins/dashboard-reference)**.
236
256
237
257
### Adding new dashboard pages manually
@@ -240,6 +260,7 @@ To create a new dashboard page manually, add a new record to your dashboard conf
0 commit comments