Skip to content

Commit 9a730bb

Browse files
committed
docs: document import export and dashboard updates
1 parent a3346e7 commit 9a730bb

2 files changed

Lines changed: 72 additions & 7 deletions

File tree

adminforth/documentation/docs/tutorial/09-Plugins/08-import-export.md

Lines changed: 48 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
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 Import Export plugin for CSV and XLSX data transfer, including installation, import flow, export flow, and resource-level usage."
44
slug: /tutorial/Plugins/import-export
55
---
66

77
# Import-Export
88

9-
Import-Export is a plugin that allows you to import data from and export data to a CSV file.
9+
Import Export is a plugin that allows you to import and export resource data as CSV or Excel (`.xlsx`) files.
1010

1111
This plugin is mostly useful for the following use cases:
1212

@@ -51,9 +51,41 @@ export default {
5151
],
5252
...
5353
}
54-
5554
```
5655

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+
new ImportExport({
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+
new ImportExport({
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+
5789

5890
## Upload export
5991

@@ -81,6 +113,7 @@ export default {
81113
plugins: [
82114
...
83115
new ImportExport({
116+
fileFormat: 'xlsx', // optional; defaults to 'csv'
84117
exportViaUpload: {
85118
storageAdapter: new AdminForthAdapterS3Storage({
86119
bucket: process.env.AWS_BUCKET_NAME as string,
@@ -94,5 +127,16 @@ export default {
94127
],
95128
...
96129
}
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+
new ImportExport({
136+
exportViaUpload: {
137+
storageAdapter,
138+
bufferSizeMb: 10, // defaults to 5 MiB; minimum is 5 MiB
139+
readChunkSize: 500, // defaults to 100 records
140+
},
141+
})
98142
```

adminforth/documentation/docs/tutorial/09-Plugins/27-0-dashboard.md

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -187,9 +187,9 @@ export const globalPlugins = [
187187
];
188188
```
189189

190-
#### Control Dashboard Editing Permissions
190+
#### Control Dashboard Access and Editing Permissions
191191

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:
193193

194194
```ts title="./globalPlugins.ts"
195195
new DashboardPlugin({
@@ -198,7 +198,11 @@ new DashboardPlugin({
198198
});
199199
```
200200

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.
202206

203207
Then pass it to the AdminForth configuration:
204208

@@ -232,6 +236,22 @@ If you need to configure dashboards without using the AI Agent, you can do so ma
232236
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.
233237
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.
234238

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+
235255
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)**.
236256

237257
### Adding new dashboard pages manually
@@ -240,6 +260,7 @@ To create a new dashboard page manually, add a new record to your dashboard conf
240260

241261
```yaml title="dashboard_configs.config"
242262
version: 1
263+
icon: flowbite:chart-pie-solid
243264
groups:
244265
- id: sales
245266
label: Sales

0 commit comments

Comments
 (0)