NocoBase Page Building

Core Philosophy: Agent-First Development

This toolkit is designed for AI agents to build and maintain pages. Every tool
prioritizes agent convenience with sensible defaults:

• - nb_crud_page: One call builds a complete page — agents don't need to

orchestrate 8+ individual tools.

• - Detail popup auto-generation: When detail_json is omitted, the detail popup

is automatically generated from the edit form's field layout (same fields, same dividers, minus required markers). Agents ONLY need to specify detail_json when they want sub-table tabs or custom blocks beyond the main detail fields.

• - nb_inspect_page: Compact visual output designed for agent comprehension —

structure at a glance, not raw JSON.

• - nb_read_node: Deep-dive into any node's event flows, JS code, or linkage

rules when debugging.

Defaults eliminate unnecessary work. If something has a sensible default, the
agent should NOT specify it. The less the agent writes, the fewer mistakes.

---

You are guiding the user to build pages in NocoBase using FlowModel API. Follow this exact workflow.

Key Concepts

Group vs Page

• - Group (📁): Folder in sidebar. NO content, only holds children.
• Page (📄): Has actual content (tables, forms, etc.). Must be under a group.

FlowModel Tree Structure

CODEBLOCK0

CRITICAL: FlowModel API is Full Replace

The flowModels:update API does a full replace, not incremental merge. The client always does GET → deep_merge → PUT internally. Never send partial data.

Recommended: Fast Path (nbcrudpage)

For standard CRUD pages, use nb_crud_page — it creates layout + KPIs + filter + table + forms + popup in ONE call:

CODEBLOCK1

This replaces 8+ individual tool calls with ONE call. Use this for every standard page.

When to use individual tools instead:

• - Non-standard layouts (multiple tables on one page)
• JS blocks, event flows, outlines
• Page modifications after initial build

Manual Path (Individual Tools)

Phase 1: Menu Structure

Use nb_create_menu for the simplest approach:

CODEBLOCK2

This creates a group + pages in one call, returning {"Asset Ledger": "tab_uid_1", "Purchases": "tab_uid_2"}.

Or build manually:

1. 1. nb_create_group("Module Name", parent_id) — creates the folder
2. INLINECODE10 — creates each page

Phase 2: Page Content (Per Page)

For each page, follow this order:

Step 1: Create Page Layout

nb_page_layout("tab_uid")  →  returns grid_uid

This cleans existing content (idempotent) and creates a BlockGridModel.

Step 2: Create KPI Cards (Optional)

CODEBLOCK4

Step 3: Create Filter/Search Bar

CODEBLOCK5

Parameters:

• - label (str, default "Search"): Placeholder label for the search input.

Note: Create filter AFTER table (needs table_uid for target), but place it ABOVE in layout.

Step 4: Create Table Block

CODEBLOCK6

Parameters:

• - first_click (bool, default true): If true, the first column becomes click-to-open

(users click to view detail popup). Set to false if no detail popup needed.

• - title (str, optional): Card header title displayed above the table.

Returns: INLINECODE17

Step 5: Create AddNew Form

CODEBLOCK7

Fields DSL syntax:

• - name — single field, full width
• INLINECODE19 — required field
• INLINECODE20 — two fields side by side (auto 12+12)
• INLINECODE21 — explicit widths (total=24)
• INLINECODE22 — divider with label
• INLINECODE23 — plain divider

Step 6: Create Edit Action

CODEBLOCK8

Step 7: Set Layout

CODEBLOCK9

Layout rules:

• - Each row is an array of [uid, span] pairs
• Spans use Ant Design grid (total = 24 per row)
• INLINECODE25 or [["uid",24]] = full width
• INLINECODE27 = two equal columns

Step 8: Detail Popup (Auto-Generated by Default)

You usually DON'T need to specify detail_json. When omitted in nb_crud_page,
a "详情" tab is auto-generated using the same field layout as the Edit form
(form_fields DSL minus * required markers). This gives every page a meaningful
detail popup with zero extra work.

Only specify detail_json when you need:

• - Sub-table tabs (e.g., customer → contacts, orders)
• JS blocks or custom layout inside the popup
• A different field layout from the edit form

CODEBLOCK10

Detail popup modes:

• - mode="drawer" + size="large" — side panel, good for business detail pages
• INLINECODE34 + size="medium" — smaller side panel, for reference data
• INLINECODE36 + size="small" — modal dialog, for quick views

Finding the click field UID:
The first column in a table created with first_click=true is clickable. Use the clickfielduid from the column's DisplayFieldModel. The field_name passed to the find function must match the first column's field name.

Multi-tab detail popup with sub-tables:

[
    {"title": "Details", "blocks": [
        {"type": "details", "fields": "--- Section 1\\nfield1 | field2\\nfield3"}
    ]},
    {"title": "Sub Items", "assoc": "items", "coll": "nb_order_items",
     "fields": ["name", "quantity", "price", "createdAt"]}
]

Note: The assoc sub-table requires an o2m relation to be defined between the parent and child collections.

Step 9: Outlines — Plan JS Capabilities (Recommended)

Use nb_outline to plan JS blocks/columns without writing actual code. A dedicated JS agent implements them later.

kind parameter (default "block"):

• - "block" — creates JSBlockModel on page grid (for KPI cards, charts)
• INLINECODE44 — creates JSColumnModel in a table (for status tags, computed columns)
• INLINECODE45 — creates JSItemModel in a form (for computed form fields)

CODEBLOCK12

Step 10: Event Flows (Optional)

CODEBLOCK13

Step 11: JS Columns — Direct Implementation (Alternative to Outlines)

CODEBLOCK14

Parameters:

• - width (int, optional): Column width in pixels. Omit for auto-width.

Phase 3: Verify & Debug — Three-Level Drill-Down

CODEBLOCK15

Full tree (for raw UIDs): INLINECODE47

Workflow: Debug → Locate → Fix

1. 1. nb_inspect_page — find the problem area (empty popup, wrong layout, hidden-point hints)
2. INLINECODE49 — see the actual event flow code or configuration
3. INLINECODE50 / nb_patch_field / nb_js_block — fix it

Common Patterns

Standard CRUD Page

1. 1. page_layout → grid
2. INLINECODE54 × N → kpi cards
3. INLINECODE55 → table + addnew + actcol
4. INLINECODE56 → search bar (target=table)
5. INLINECODE57 → new record form
6. INLINECODE58 → edit record form
7. INLINECODE59 → arrange: KPIs row → filter → table
8. Optionally: detail_popup, INLINECODE61

KPI Row Pattern

CODEBLOCK16

Multi-Block Detail Popup

CODEBLOCK17

Page Modification & Debugging

For tweaking existing pages or diagnosing issues: CODEBLOCK18

nb_patch_field common patches:
CODEBLOCK19

nb_patch_column common patches:
CODEBLOCK20

nb_delete_route — remove a menu item:
CODEBLOCK21

Batch inspect — check all pages in a system:
CODEBLOCK22

Ant Design Icons

Common icons for menus: homeoutlined, settingoutlined, databaseoutlined, shoppingcartoutlined, bankoutlined, tooloutlined, formoutlined, barchartoutlined, piechartoutlined, idcardoutlined, caroutlined, containeroutlined, clusteroutlined, apartmentoutlined, environmentoutlined, shopoutlined, controloutlined, appstoreoutlined, inboxoutlined, deleteoutlined, swapoutlined, INLINECODE86

Status Tag Colors

For ctx.antd.Tag in JS columns/blocks:

• - Green: active, completed, approved → color: 'green' or INLINECODE89
• Blue: in progress, processing → color: 'blue' or INLINECODE91
• Orange: pending, warning → color: 'orange' or INLINECODE93
• Red: error, rejected, overdue → color: 'red' or INLINECODE95
• Default: draft, inactive → INLINECODE96