mirror of https://github.com/abpframework/abp.git
SALİH ÖZKARA
1 month ago
16 changed files with 726 additions and 14 deletions
@ -0,0 +1,183 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Define ABP Low-Code dashboard pages, visualizations, filters, layout, permissions, and React runtime data flow." |
|||
} |
|||
``` |
|||
|
|||
# Dashboards |
|||
|
|||
Dashboards are low-code pages that render charts, lists, and number widgets from low-code entity data. A dashboard is still a page, so it uses the normal page name, title, icon, order, group, and permission model, but its page type is `dashboard` and its page definition carries a nested `dashboard` payload. |
|||
|
|||
The runtime below was generated from a low-code dashboard page definition: |
|||
|
|||
 |
|||
|
|||
## Dashboard Pages |
|||
|
|||
Dashboard pages live in the normal page descriptor collection. In source-controlled models, a dashboard page still belongs under `pages/`, not a separate dashboard folder. |
|||
|
|||
Typical page-level fields include: |
|||
|
|||
* `name` |
|||
* `title` |
|||
* `icon` |
|||
* `type: "dashboard"` |
|||
* `group` |
|||
* `order` |
|||
* `permissionConfig` |
|||
* `dashboard` |
|||
|
|||
Runtime routes use the same dynamic page convention: |
|||
|
|||
```text |
|||
/dynamic/<page-name> |
|||
``` |
|||
|
|||
## Layout Model |
|||
|
|||
The stored dashboard descriptor uses a **flat visualization list**. Each visualization defines its own placement: |
|||
|
|||
* `row`: zero-based visual row index |
|||
* `order`: order within the row |
|||
* `width`: current dashboard grid width, typically `1` or `2` |
|||
|
|||
At runtime, the React UI groups those flat visualizations into rendered rows. This is similar to form layouts: storage stays flat, rendering derives the grouped structure. |
|||
|
|||
```json |
|||
{ |
|||
"name": "sales-dashboard", |
|||
"title": "Sales Dashboard", |
|||
"type": "dashboard", |
|||
"group": "analytics", |
|||
"dashboard": { |
|||
"description": "Operational sales view", |
|||
"globalFilters": [ |
|||
{ "type": "dateRange" } |
|||
], |
|||
"visualizations": [ |
|||
{ |
|||
"name": "sales-by-status", |
|||
"type": "chart", |
|||
"title": "Sales by Status", |
|||
"row": 0, |
|||
"order": 0, |
|||
"width": 2, |
|||
"entityName": "Acme.Sales.Order", |
|||
"chart": { |
|||
"chartType": "bar", |
|||
"xAxis": { "property": "Status" }, |
|||
"yAxis": [ |
|||
{ "aggregation": "count", "label": "Orders" } |
|||
] |
|||
} |
|||
}, |
|||
{ |
|||
"name": "totals", |
|||
"type": "numberContainer", |
|||
"title": "Totals", |
|||
"row": 1, |
|||
"order": 0, |
|||
"width": 2, |
|||
"numberContainer": { |
|||
"items": [ |
|||
{ |
|||
"name": "order-count", |
|||
"title": "Order Count", |
|||
"entityName": "Acme.Sales.Order", |
|||
"aggregation": "count", |
|||
"format": "number" |
|||
} |
|||
] |
|||
} |
|||
} |
|||
] |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Visualization Types |
|||
|
|||
The current dashboard visualization types are: |
|||
|
|||
* `chart` |
|||
* `list` |
|||
* `numberContainer` |
|||
|
|||
### Chart |
|||
|
|||
Chart visualizations define: |
|||
|
|||
* `chartType`: `bar`, `line`, `pie`, or `donut` |
|||
* `xAxis` |
|||
* one or more `yAxis` aggregation series |
|||
* optional `maxItems` |
|||
* optional `showRecordCount` |
|||
* optional bar orientation |
|||
|
|||
### List |
|||
|
|||
List visualizations define: |
|||
|
|||
* `fields` |
|||
* optional `sortBy` |
|||
* `maxRows` |
|||
* `rowHeight` |
|||
* optional `colorBy` |
|||
|
|||
### Number Container |
|||
|
|||
Number containers hold one or more number items. Each item can define: |
|||
|
|||
* `aggregation` |
|||
* `aggregationProperty` |
|||
* `format` |
|||
* `color` |
|||
* entity-specific filters and global date filter linkage |
|||
* click-through behavior |
|||
|
|||
## Filters and Interactivity |
|||
|
|||
Dashboards support three filter layers: |
|||
|
|||
* `globalFilters` for page-level controls such as date range |
|||
* visualization-level `filter` for fixed query constraints |
|||
* visualization `userFilters` for interactive filtering exposed to the runtime user |
|||
|
|||
Other useful dashboard interaction fields include: |
|||
|
|||
* `globalDateFilterProperty` |
|||
* `showDescriptionAsTooltip` |
|||
* `clickToSeeRecords` |
|||
|
|||
These options let a dashboard stay compact while still allowing drill-down behavior in the runtime. |
|||
|
|||
## Runtime Shape |
|||
|
|||
The runtime definition exposed to React is grouped by rows and items, even though the stored descriptor is flat. The React runtime uses: |
|||
|
|||
* `useDashboardDefinition` |
|||
* `useDashboardData` |
|||
* `GET /api/low-code/ui/dashboards/{pageName}` |
|||
* `POST /api/low-code/dashboards/{pageName}/data` |
|||
|
|||
See [React Runtime](react-runtime.md) for hook-level details and route integration. |
|||
|
|||
## Permissions and Menu Placement |
|||
|
|||
Dashboard pages are read-oriented. Generated dashboard page operations are **view only**, so the usual CRUD operation set does not apply. |
|||
|
|||
Dashboard pages can still: |
|||
|
|||
* appear inside a [Page Group](page-groups.md) |
|||
* carry a menu icon and order |
|||
* use explicit or generated page permission configuration |
|||
|
|||
Menu placement is handled at the page level through the normal `group` and `order` fields. |
|||
|
|||
## See Also |
|||
|
|||
* [React Runtime](react-runtime.md) |
|||
* [Low-Code Designer](designer.md) |
|||
* [Page Groups](page-groups.md) |
|||
* [Model Descriptor Files](model-json.md) |
|||
@ -0,0 +1,83 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Review the ABP Low-Code model health snapshot to inspect entities, pages, forms, page groups, permissions, and script assets before publishing runtime changes." |
|||
} |
|||
``` |
|||
|
|||
# Health |
|||
|
|||
The **Health** section in the Low-Code Designer is a selected-layer readiness view. It helps you review the resolved low-code model for the currently selected layer before publishing changes or relying on the generated runtime pages. |
|||
|
|||
Health works on the **resolved view of the selected layer**, not on raw JSON files. In practice, this means it shows the selected layer after lower-layer inheritance and descriptor materialization have been applied. It does not silently merge unrelated edits from another layer. To review runtime-only overrides, switch the Designer to **Runtime JSON** or use the runtime-focused [MCP Integration](mcp.md) workflow. |
|||
|
|||
## What Health Reads |
|||
|
|||
The health snapshot is a combined view of the current low-code model in the selected layer. It includes: |
|||
|
|||
* Entities |
|||
* Enums |
|||
* Page groups |
|||
* Pages |
|||
* Forms |
|||
* Custom permissions |
|||
* Effective page permission configuration |
|||
* Custom endpoints |
|||
* Script event handlers |
|||
* Script background jobs |
|||
* Script background workers |
|||
|
|||
This makes Health the best place to review cross-descriptor relationships instead of checking each designer tab in isolation. |
|||
|
|||
## What It Helps You Catch |
|||
|
|||
Health is most useful for selected-layer consistency problems that often appear only after several descriptors start referencing each other. |
|||
|
|||
Typical problem classes include: |
|||
|
|||
* Page to form mismatches, where a page references a form that does not exist or belongs to another entity |
|||
* Page-type configuration errors, such as a kanban page missing `groupByProperty`, a calendar page using invalid date or time fields, or a gallery page pointing to a non-image property |
|||
* Page-group structure problems such as missing parents, circular references, or nesting deeper than the supported depth |
|||
* Form layout issues where fields exist but valid placements do not |
|||
* Permission and page configuration mismatches that would affect runtime visibility or access |
|||
* Script assets that exist in the model but still need review in the broader context of entities, pages, and permissions |
|||
|
|||
Some of these issues are also enforced by runtime validation and mutation rules. Health gives you a selected-layer review point before users discover the problem in the runtime UI. |
|||
|
|||
## Use It When |
|||
|
|||
Use Health in these moments: |
|||
|
|||
* After changing entities, pages, forms, page groups, or permissions in the Designer |
|||
* After applying MCP-driven runtime mutations |
|||
* Before publishing a set of runtime changes |
|||
* After copying or importing source-controlled descriptors into an application |
|||
|
|||
If you automate low-code changes through [MCP Integration](mcp.md), re-read the health snapshot after apply and treat that review as part of the success criteria. |
|||
|
|||
## Health and Source-Controlled Models |
|||
|
|||
Health is not a replacement for source-controlled file validation. |
|||
|
|||
When you edit `_Dynamic/model/**/*.json` directly: |
|||
|
|||
1. Run the generated model file checker: |
|||
|
|||
```bash |
|||
dotnet run --project <startup-project> -- --check-lowcode-model-files |
|||
``` |
|||
|
|||
2. Run the required migration workflow for schema-affecting entity changes. |
|||
3. Open the Designer and review **Health** after the model has loaded successfully. |
|||
|
|||
The file checker catches JSON and category-level problems. Health complements it by helping you inspect the resolved model after descriptors, references, permissions, pages, and forms are all combined. |
|||
|
|||
A useful example is form layout drift: a descriptor can still pass `--check-lowcode-model-files` while a source-controlled form renders with no visible fields because its layout placements are stale. Health and runtime preview are the places to catch that class of issue. |
|||
|
|||
## See Also |
|||
|
|||
* [Low-Code Designer](designer.md) |
|||
* [MCP Integration](mcp.md) |
|||
* [Model Descriptor Files](model-json.md) |
|||
* [Dashboards](dashboards.md) |
|||
* [Page Groups](page-groups.md) |
|||
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 55 KiB |
|
Before Width: | Height: | Size: 29 KiB After Width: | Height: | Size: 26 KiB |
|
Before Width: | Height: | Size: 92 KiB After Width: | Height: | Size: 80 KiB |
|
Before Width: | Height: | Size: 61 KiB After Width: | Height: | Size: 33 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
Before Width: | Height: | Size: 45 KiB After Width: | Height: | Size: 40 KiB |
|
After Width: | Height: | Size: 123 KiB |
@ -0,0 +1,126 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Use the ABP Low-Code Designer MCP integration to inspect, validate, and apply structured runtime mutations to the database-backed low-code model." |
|||
} |
|||
``` |
|||
|
|||
# MCP Integration |
|||
|
|||
> **Preview:** The low-code MCP surface is part of the preview Low-Code System. Tool names, mutation metadata, and validation advice may change before general availability. |
|||
|
|||
The low-code designer exposes a Model Context Protocol (MCP) surface for automation. It is intended for agents and scripted tooling that need to inspect or mutate the same **runtime database-backed** model that the Designer edits in the **Runtime JSON** layer. |
|||
|
|||
## Scope |
|||
|
|||
The MCP surface is **runtime-only**: |
|||
|
|||
* It always works against the database-backed runtime model. |
|||
* It does not choose between layers at call time. |
|||
* It is not the right surface for source-controlled `_Dynamic/model/**/*.json` files. |
|||
|
|||
Use [Model Descriptor Files](model-json.md) when you need source-controlled descriptors. Use MCP when an agent or automation needs safe, structured changes to the runtime model that the Designer can immediately show. |
|||
|
|||
## Mental Model |
|||
|
|||
MCP is not a raw JSON document editor. It is a semantic mutation layer over low-code concepts such as: |
|||
|
|||
* Entities and properties |
|||
* Pages, page groups, and dashboards |
|||
* Forms and form layout |
|||
* Permissions |
|||
* Custom endpoints and script actions |
|||
|
|||
The MCP surface includes read/query capabilities, mutation metadata, dry-run validation, a single mutation apply path, and a health snapshot. The normal workflow is: |
|||
|
|||
1. Read the current runtime model state for the item you want to change. |
|||
2. Fetch the latest mutation metadata and keep its `concurrencyStamp`. |
|||
3. Build a small ordered mutation batch that touches only the changed paths. |
|||
4. Dry-run the batch with validation. |
|||
5. Apply the batch. |
|||
6. Re-read the changed item and review [Health](health.md). |
|||
|
|||
## Concurrency and Validation |
|||
|
|||
Every runtime write depends on the latest `concurrencyStamp`. If another write changes the runtime model first, your apply attempt becomes stale and must be rebuilt from the refreshed model state. |
|||
|
|||
Validation happens before apply and returns structured feedback instead of requiring a client to guess from generic failures. The validation layer checks: |
|||
|
|||
* Stale concurrency stamps |
|||
* Target path syntax |
|||
* Missing required input such as `data` or move destinations |
|||
* Primitive-only `Set` data |
|||
* Final descriptor shape after the batch is simulated |
|||
* Entity property type and foreign key rules |
|||
* Form layout consistency |
|||
* Dashboard layout consistency |
|||
* Runtime override rules for descriptors inherited from lower layers |
|||
|
|||
Treat validation as part of the normal write flow, not as an optional extra. |
|||
|
|||
## Mutation Model |
|||
|
|||
Runtime writes are intentionally narrow: |
|||
|
|||
* `Add` creates a keyed descriptor or collection member. |
|||
* `Set` changes a scalar value or a supported primitive list. |
|||
* `Remove` deletes the semantic target. |
|||
* `Move` relocates an existing node without resending the whole object. |
|||
|
|||
Important behavior: |
|||
|
|||
* `Set` data must stay primitive: string, number, boolean, `null`, or a supported primitive string list. |
|||
* Do not replace whole descriptor trees when only one field changed. |
|||
* Keep batches small and semantic. Send changed paths, not full model payloads. |
|||
* If a mapped entity or property is removed with drop behavior, the runtime model can also remove the physical table or column in the runtime layer. |
|||
|
|||
## Runtime Override and Schema Rules |
|||
|
|||
Runtime MCP writes can extend descriptors that originate from lower layers, but they do not have unlimited control over inherited schema. |
|||
|
|||
For entity properties inherited from a lower layer, runtime edits are intentionally restricted. Typical runtime-safe changes are display labels and runtime-owned validators. Inherited storage details such as type, database mapping, default value, required or unique behavior, foreign key settings, and file or image storage options remain immutable in runtime. |
|||
|
|||
This separation matches the low-code layer model: |
|||
|
|||
* Runtime database-backed changes use **direct** schema mutation. |
|||
* Source-controlled JSON layer changes use the normal **migration** workflow. |
|||
|
|||
If you are working in `_Dynamic/model`, MCP is the wrong tool. Use the source-controlled descriptor flow and migrations instead. |
|||
|
|||
## Layout and Type Conventions |
|||
|
|||
Several conventions matter when MCP clients generate mutations: |
|||
|
|||
* Use canonical lowercase entity property types: `string`, `int`, `long`, `decimal`, `datetime`, `boolean`, `guid`, `enum`, `date`, `time`, `file`, `image`, `money`. |
|||
* Use canonical lowercase form field types: `text`, `textarea`, `number`, `checkbox`, `date`, `datetime`, `select`, `lookup`, `guid`, `computed`, `time`, `file`, `image`, `money`. |
|||
* Form layout is flat and id-keyed under `layout.tabs[].groups[].fields[]`. Each placement carries `row`, `colSpan`, and optional `colStart`. |
|||
* Dashboard layout is flat and name-keyed under `dashboard.visualizations[]`. Each visualization carries `row`, `order`, and `width`. |
|||
* Page and page-group icons are CSS class strings, not URLs or image file paths. |
|||
* For foreign access, `foreignKey.access` values are `none`, `view`, or `edit`. |
|||
|
|||
These rules matter because validation and runtime rendering assume them. For example, a form can define fields correctly but still render an empty group if no valid placements point to those field IDs. |
|||
|
|||
## Designer and MCP Together |
|||
|
|||
Use the Designer when you want: |
|||
|
|||
* Interactive editing |
|||
* Visual context for entities, pages, forms, and permissions |
|||
* Manual review before publishing |
|||
|
|||
Use MCP when you want: |
|||
|
|||
* Agent-driven or scripted changes |
|||
* Repeatable runtime mutation workflows |
|||
* Structured validation before write |
|||
* Safe, incremental edits instead of raw JSON replacement |
|||
|
|||
The two surfaces are complementary. A common workflow is to inspect or prototype in the Designer, automate a repeatable mutation flow through MCP, then reopen the Designer and [Health](health.md) to confirm the result. |
|||
|
|||
## See Also |
|||
|
|||
* [Low-Code Designer](designer.md) |
|||
* [Health](health.md) |
|||
* [Dashboards](dashboards.md) |
|||
* [Page Groups](page-groups.md) |
|||
* [Model Descriptor Files](model-json.md) |
|||
@ -0,0 +1,123 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Define ABP Low-Code page groups to organize runtime pages into dynamic menu folders with ordering, icons, and nesting." |
|||
} |
|||
``` |
|||
|
|||
# Page Groups |
|||
|
|||
Page groups are dynamic menu folders used by low-code pages. They let you organize runtime pages into nested navigation structures without hardcoding menu items in the frontend. |
|||
|
|||
## What a Page Group Stores |
|||
|
|||
A page group descriptor stores: |
|||
|
|||
| Field | Description | |
|||
|-------|-------------| |
|||
| `name` | Stable identifier used by pages in their `group` field | |
|||
| `title` | Display label shown in the runtime menu | |
|||
| `icon` | CSS class string for the menu icon | |
|||
| `order` | Sort order among sibling groups | |
|||
| `parent` | Optional parent group name for nesting | |
|||
|
|||
If a group does not define an icon, the runtime menu uses a folder-style default icon. |
|||
|
|||
## How Pages Use Groups |
|||
|
|||
Pages reference a group by name: |
|||
|
|||
```json |
|||
{ |
|||
"name": "orders", |
|||
"title": "Orders", |
|||
"type": "dataGrid", |
|||
"entityName": "Acme.Sales.Order", |
|||
"group": "sales" |
|||
} |
|||
``` |
|||
|
|||
If `group` is omitted, the page becomes a top-level runtime menu item. |
|||
|
|||
A group is only a container. It does not define page data, routes, or entity behavior by itself. |
|||
|
|||
## Nesting Rules |
|||
|
|||
Groups can nest by pointing `parent` to another page group name. |
|||
|
|||
Important constraints: |
|||
|
|||
* Group nesting cannot be circular. |
|||
* Maximum depth is `3` levels. |
|||
* Root groups are groups whose `parent` is empty. |
|||
|
|||
This keeps runtime navigation predictable and avoids unbounded nesting in the generated menu. |
|||
|
|||
## Visibility and Permissions |
|||
|
|||
Page groups do not replace page permissions. Runtime visibility still depends on the pages inside the group. |
|||
|
|||
In practice: |
|||
|
|||
* Pages are added to the runtime menu only if the current user can access them. |
|||
* Groups are containers for those visible pages. |
|||
* Groups without visible page descendants are omitted from the runtime root menu. |
|||
|
|||
This means page permissions remain the real security boundary, while page groups control menu organization. |
|||
|
|||
## Split Descriptor Example |
|||
|
|||
In split descriptor projects, a page group file in `pageGroups/` stores **one descriptor object**, not a wrapper document: |
|||
|
|||
```json |
|||
{ |
|||
"name": "sales-reports", |
|||
"title": "Reports", |
|||
"icon": "fa-solid fa-folder-tree", |
|||
"order": 20, |
|||
"parent": "sales" |
|||
} |
|||
``` |
|||
|
|||
For example, `pageGroups/sales-reports.json` would use that shape directly. |
|||
|
|||
If you are looking at the logical aggregate model instead of split files, the same data appears under the top-level `pageGroups` array: |
|||
|
|||
```json |
|||
{ |
|||
"pageGroups": [ |
|||
{ |
|||
"name": "sales", |
|||
"title": "Sales", |
|||
"icon": "fa-solid fa-chart-line", |
|||
"order": 10 |
|||
}, |
|||
{ |
|||
"name": "sales-reports", |
|||
"title": "Reports", |
|||
"icon": "fa-solid fa-folder-tree", |
|||
"order": 20, |
|||
"parent": "sales" |
|||
} |
|||
] |
|||
} |
|||
``` |
|||
|
|||
In split descriptor projects, page groups belong to the `pageGroups/` descriptor category. |
|||
|
|||
## Icon Guidance |
|||
|
|||
Use CSS class strings for icons, for example: |
|||
|
|||
* `fa-solid fa-folder` |
|||
* `fa-solid fa-folder-tree` |
|||
* `fa-solid fa-chart-line` |
|||
|
|||
Do not treat `icon` as an image URL or file path. |
|||
|
|||
## See Also |
|||
|
|||
* [Dashboards](dashboards.md) |
|||
* [React Runtime](react-runtime.md) |
|||
* [Low-Code Designer](designer.md) |
|||
* [Model Descriptor Files](model-json.md) |
|||
Loading…
Reference in new issue