Skip to content

Commit 936e8fa

Browse files
committed
docs: enhance dashboard access control with viewRoles option for read-only access
1 parent b194f86 commit 936e8fa

1 file changed

Lines changed: 7 additions & 4 deletions

File tree

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

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -189,16 +189,19 @@ export const globalPlugins = [
189189

190190
#### Control Dashboard Access and Editing Permissions
191191

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:
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, and the `viewRoles` option to grant read-only access:
193193

194194
```ts title="./globalPlugins.ts"
195195
new DashboardPlugin({
196196
dashboardConfigsResourceId: 'dashboard_configs',
197197
editRoles: ['superadmin', 'admin'], // allow 'admin' users to edit dashboards too
198+
viewRoles: ['manager'], // allow 'manager' users to view dashboards without editing them
198199
});
199200
```
200201

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+
Users with a role from `viewRoles` see the **Dashboards** sidebar group and can open dashboards, but they do not get the edit mode button and receive a `403` response from all dashboard mutation endpoints. Roles from `editRoles` can always view dashboards, so there is no need to repeat them in `viewRoles`.
203+
204+
Users whose role is listed in neither option do not see the **Dashboards** sidebar group and receive a `403` response from dashboard configuration and widget-data endpoints. The dashboard configs resource itself stays available only to `editRoles`.
202205

203206
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`.
204207

@@ -233,12 +236,12 @@ widgets: []
233236
If you need to configure dashboards without using the AI Agent, you can do so manually via the AdminForth interface:
234237
235238
1. **Access Dashboards**: Open the **Dashboards** group in the sidebar and choose a dashboard page.
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.
239+
2. **Interactive UI Editor**: Users with a role listed in the plugin's `editRoles` option (defaults to `superadmin`) see a wrench button in the dashboard header that toggles edit mode. Turning it on reveals the controls to add, rename, reorder, and remove groups or widgets directly from the user interface. With edit mode off, the dashboard looks the same as it does for read-only viewers.
237240
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.
238241

239242
### Editing dashboard settings
240243

241-
Click the tools icon in the dashboard header to edit the dashboard itself. The YAML editor accepts these fields:
244+
Turn on edit mode with the wrench button and click the gear icon next to it to edit the dashboard itself. The YAML editor accepts these fields:
242245

243246
```yaml
244247
label: Sales Overview

0 commit comments

Comments
 (0)