Skip to content

Commit abceb3d

Browse files
yaroslav8765yaroslav8765
authored
Merge pull request #688 from devforth/next
Next
2 parents fee684d + 1f7401e commit abceb3d

17 files changed

Lines changed: 419 additions & 211 deletions

File tree

‎adminforth/documentation/docs/tutorial/03-Customization/02-customFieldRendering.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -605,6 +605,30 @@ For fields containing sensitive data (like passwords, API keys, tokens, or other
605605
606606
The renderer wraps the standard value output and adds a click-to-reveal blur effect. Clicking again hides the value.
607607
608+
For long values (like API keys) you can enable compact mode by passing `compact: true` via `meta`. When set, the value is shortened the same way as the `CompactUUID` renderer (first 4 + `...` + last 4 characters). In compact mode you can additionally pass `copy: true` to render a copy-to-clipboard button next to the value:
609+
610+
```ts title='./resources/anyResource.ts'
611+
columns: [
612+
...
613+
{
614+
name: 'api_key',
615+
components: {
616+
show: {
617+
//diff-add
618+
file: '@/renderers/SensitiveBlurCell.vue',
619+
//diff-add
620+
meta: { compact: true, copy: true },
621+
},
622+
list: {
623+
//diff-add
624+
file: '@/renderers/SensitiveBlurCell.vue',
625+
//diff-add
626+
meta: { compact: true, copy: true },
627+
},
628+
},
629+
...
630+
```
631+
608632
609633
### Custom filter component for square meters
610634

‎adminforth/documentation/docs/tutorial/09-Plugins/11-oauth.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ plugins: [
145145
4. Create credentials for OAuth 2.0 client IDs.
146146
5. Select application type: "Web application".
147147
6. Add your application's name and redirect URI.
148-
7. In "Authorized redirect URIs", add `https://your-domain/oauth/callback` and `http://localhost:3500/oauth/callback`. Include `baseUrl` when your AdminForth app uses it, for example `https://your-domain/base/oauth/callback`.
148+
7. In "Authorized redirect URIs", add `https://your-domain/oauth/callback` (for production) and `http://localhost:3500/oauth/callback`(for local, where 3500 - is your app port). Include `baseUrl` when your AdminForth app uses it, for example `https://your-domain/base/oauth/callback`.
149149
8. Add the credentials to your `.env` file:
150150

151151
```bash

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

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
---
2+
title: Dashboard plugin
3+
description: "Documentation for the Dashboard plugin."
4+
slug: /tutorial/Plugins/dashboard
5+
---
6+
7+
# Dashboard Plugin
8+
9+
The **Dashboard Plugin** adds dynamic, configurable dashboards to AdminForth. This page is a practical guide / reference demonstrating how to build and manage your dashboards using the **[Agent Plugin](/docs/tutorial/Plugins/agent)**.
10+
11+
While manual configuration is supported, the plugin is primarily designed to be managed via conversational prompts using the AI Agent. This is the fastest, easiest, and recommended way to create and modify your dashboards.
12+
13+
### Quick Start: Conversation Prompts
14+
If you have the Agent Plugin active, you can interact with it right away using these prompts in the chat interface:
15+
* *"Create a new dashboard named 'Sales Overview'"*
16+
* *"Add a pie chart showing cars by body type to the Sales Overview dashboard"*
17+
* *"Add a KPI card showing the average price of cars"*
18+
19+
---
20+
21+
## Using the Dashboard with the Agent
22+
23+
Once the Dashboard plugin is installed, the AI Agent has full capability to manage it. You do not need to construct YAML configurations yourself; the agent handles all database record updates and layout adjustments.
24+
25+
### End-to-End Prompt Examples
26+
Here are interactive examples you can test immediately in the demo application generated via the AdminForth CLI:
27+
28+
#### 1. KPI Cards for Basic Metrics
29+
* **Initial Prompt:**
30+
> *"Create a new dashboard group named 'Sales Stats' and add two KPI cards inside it: one for 'Total Cars' (count of all cars) and another for 'Average Price' (average car price)."*
31+
* **Expected Result:**
32+
The agent creates a new group named "Sales Stats" containing two cards. One card displays the count of all records in the `cars` resource (e.g., `24`), and the second displays the average price formatted with a dollar sign (e.g., `$12,450`).
33+
* **Follow-up Prompt:**
34+
> *"Change the background color of the Average Price card to blue and adjust its width to match the other card."*
35+
36+
#### 2. Visualizing Categories with a Bar Chart
37+
* **Initial Prompt:**
38+
> *"Add a bar chart named 'Cars by Body Type' to the 'Sales Stats' group. Group it by body_type and sort by the number of cars from high to low."*
39+
* **Expected Result:**
40+
A bar chart is created. It queries the `cars` resource, groups by `body_type`, and orders the bars so the body type with the most cars appears first.
41+
* **Follow-up Prompt:**
42+
> *"Change the chart type to a pie chart and set its size to medium."*
43+
44+
#### 3. Data Table with Filters and Limits
45+
* **Initial Prompt:**
46+
> *"Add a wide table widget named 'Top 5 Most Expensive Listed Cars' to my dashboard. Show the model, price, and production_year columns. Only include listed cars, and sort them by price descending."*
47+
* **Expected Result:**
48+
A data table widget is added. It displays columns for model, price, and production year, filtered to only show cars where `listed` is true, limited to the top 5 most expensive.
49+
* **Follow-up Prompt:**
50+
> *"Add the color column to this table, and rename the widget to 'Top 5 Premium Cars'."*
51+
52+
---
53+
54+
## Installation & Setup
55+
56+
Before using the dashboard, you need to perform the initial package installation and register the database tables:
57+
58+
### 1. Install Package
59+
60+
```bash
61+
pnpm install @adminforth/dashboard --save
62+
```
63+
64+
### 2. Create Dashboard Configs Table
65+
66+
The plugin needs one database resource to store dashboard definitions. For Prisma-based projects, add the table to your schema:
67+
68+
```prisma title="./schema.prisma"
69+
model dashboard_configs {
70+
id String @id
71+
slug String @unique
72+
label String
73+
revision Int
74+
config Json
75+
76+
@@index([slug])
77+
}
78+
```
79+
80+
Create and apply a migration:
81+
82+
```bash
83+
pnpm makemigration --name add-dashboard-configs
84+
pnpm migrate:local
85+
```
86+
87+
The generated SQL should be equivalent to:
88+
89+
```sql title="./migrations/.../migration.sql"
90+
CREATE TABLE "dashboard_configs" (
91+
"id" TEXT NOT NULL PRIMARY KEY,
92+
"slug" TEXT NOT NULL,
93+
"label" TEXT NOT NULL,
94+
"revision" INTEGER NOT NULL,
95+
"config" JSON NOT NULL
96+
);
97+
98+
CREATE UNIQUE INDEX "dashboard_configs_slug_key" ON "dashboard_configs"("slug");
99+
CREATE INDEX "dashboard_configs_slug_idx" ON "dashboard_configs"("slug");
100+
```
101+
102+
Use the JSON column type supported by your database connector. For example, PostgreSQL migrations might use `JSONB`, while SQLite migrations can use `JSON`.
103+
104+
### 3. Create Resource
105+
106+
Create a resource that points to the `dashboard_configs` table:
107+
108+
```ts title="./resources/dashboard_configs.ts"
109+
import { randomUUID } from 'crypto';
110+
import { AdminForthDataTypes } from 'adminforth';
111+
import type { AdminForthResourceInput } from 'adminforth';
112+
113+
export default {
114+
dataSource: 'maindb',
115+
table: 'dashboard_configs',
116+
resourceId: 'dashboard_configs',
117+
label: 'Dashboard Configs',
118+
recordLabel: (record) => record.label,
119+
columns: [
120+
{
121+
name: 'id',
122+
primaryKey: true,
123+
type: AdminForthDataTypes.STRING,
124+
fillOnCreate: () => randomUUID(),
125+
showIn: {
126+
list: false,
127+
edit: false,
128+
create: false,
129+
show: true,
130+
filter: false,
131+
},
132+
},
133+
{
134+
name: 'slug',
135+
type: AdminForthDataTypes.STRING,
136+
label: 'Slug',
137+
},
138+
{
139+
name: 'label',
140+
type: AdminForthDataTypes.STRING,
141+
label: 'Label',
142+
},
143+
{
144+
name: 'revision',
145+
type: AdminForthDataTypes.INTEGER,
146+
label: 'Revision',
147+
fillOnCreate: () => 1,
148+
showIn: {
149+
edit: false,
150+
create: false,
151+
},
152+
},
153+
{
154+
name: 'config',
155+
type: AdminForthDataTypes.JSON,
156+
label: 'Config',
157+
},
158+
],
159+
} as AdminForthResourceInput;
160+
```
161+
162+
Register this resource in your AdminForth app:
163+
164+
```ts title="./index.ts"
165+
import dashboardConfigsResource from './resources/dashboard_configs.js';
166+
167+
export const admin = new AdminForth({
168+
// ...
169+
resources: [
170+
// ...
171+
dashboardConfigsResource,
172+
],
173+
});
174+
```
175+
176+
### 4. Configure Plugin
177+
178+
Attach the plugin to one of your resources, usually the users resource:
179+
180+
```ts title="./resources/adminuser.ts"
181+
import DashboardPlugin from '@adminforth/dashboard';
182+
183+
export default {
184+
// ...
185+
plugins: [
186+
// ...
187+
new DashboardPlugin({
188+
dashboardConfigsResourceId: 'dashboard_configs',
189+
}),
190+
],
191+
} as AdminForthResourceInput;
192+
```
193+
194+
After `admin.discoverDatabases()` runs, the plugin creates a default dashboard config if the table is empty:
195+
196+
```yaml
197+
version: 1
198+
groups:
199+
- id: default
200+
label: Default Group
201+
order: 1
202+
widgets: []
203+
```
204+
205+
---
206+
207+
## Manual Configuration
208+
209+
If you need to configure dashboards without using the AI Agent, you can do so manually via the AdminForth interface:
210+
211+
1. **Access Dashboards**: Open the **Dashboards** group in the sidebar and choose a dashboard page.
212+
2. **Interactive UI Editor**: Superadmins can add, rename, reorder, and remove groups or widgets directly from the user interface.
213+
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.
214+
215+
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)**.
216+
217+
### Adding new dashboard pages manually
218+
219+
To create a new dashboard page manually, add a new record to your dashboard configs resource (e.g. `dashboard_configs` table in the database):
220+
221+
```yaml title="dashboard_configs.config"
222+
version: 1
223+
groups:
224+
- id: sales
225+
label: Sales
226+
order: 1
227+
widgets: []
228+
```
229+
230+
Use a unique `slug`, for example `sales`. The plugin will expose it as `/dashboard/sales` and add it to the **Dashboards** sidebar group.

0 commit comments

Comments
 (0)