frappe-impl-workspace

Name: frappe-impl-workspace
Author: Impertio-Studio

151stars49forks

How to install frappe-impl-workspace?

impertio-studio/frappe_claude_skill_package/frappe-impl-workspace

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-impl-workspace

Installs into the current project.

Summary

Use when creating or customizing Workspace pages in Frappe v14-v16. Covers Workspace DocType structure, shortcuts, number cards, dashboard charts, custom HTML blocks, JSON content format, shipping workspaces with custom apps, and role-based access control. Prevents common mistake

Files · 1

View on GitHub

SKILL.md

1	# Frappe Workspace Implementation Workflow
2
3	Step-by-step workflows for creating and customizing Workspace pages. Workspaces are the block-based dashboard/navigation pages in Frappe Desk.
4
5	Version: v14/v15/v16 (version-specific features noted)
6
7	---
8
9	## Quick Reference
10
11	\| Concept \| Description \|
12	\|---------\|-------------\|
13	\| Workspace \| Block-based page with 12-column grid layout \|
14	\| Public Workspace \| Visible to all permitted users; requires Workspace Manager role to edit \|
15	\| Private Workspace \| Per-user dashboard under "My Workspaces"; any Desk User can create \|
16	\| Content field \| JSON array storing the block layout \|
17	\| Child tables \| 6 tables: charts, shortcuts, links, quick_lists, number_cards, custom_blocks \|
18	\| Module association \| Primary access control mechanism \|
19
20	---
21
22	## Master Decision: What Do You Need?
23
24	```
25	NEED A WORKSPACE?
26	│
27	├─► Default DocType landing page?
28	│ └─► NO workspace needed — Frappe auto-generates list views
29	│
30	├─► Custom dashboard for a module?
31	│ └─► Create PUBLIC Workspace (Workspace Manager role required)
32	│
33	├─► Personal dashboard for a user?
34	│ └─► Create PRIVATE Workspace (appears under "My Workspaces")
35	│
36	└─► Navigation link in sidebar?
37	└─► type="Link" (internal) or type="URL" (external)
38
39	ADDING COMPONENTS?
40	│
41	├─► Key metrics (counts, sums) → Number Cards
42	├─► Trend / time-series data → Dashboard Charts
43	├─► Quick navigation links → Shortcuts
44	├─► Grouped link categories → Link Cards (Card Break + Links)
45	├─► Custom HTML/JS content → Custom HTML Blocks
46	└─► Recent record lists → Quick Lists
47	```
48
49	---
50
51	## Workspace DocType Structure
52
53	### Key Fields
54
55	\| Field \| Type \| Purpose \|
56	\|-------\|------\|---------\|
57	\| `label` \| Data \| Display name in sidebar \|
58	\| `title` \| Data \| Page title (defaults to label) \|
59	\| `module` \| Link → Module Def \| Associates workspace with a module for access control \|
60	\| `parent_page` \| Link → Workspace \| Nesting under another workspace in sidebar \|
61	\| `icon` \| Data \| Sidebar icon (e.g., `"chart-line"`) \|
62	\| `type` \| Select \| `Workspace` / `Link` / `URL` (v15+) \|
63	\| `sequence_id` \| Int \| Sidebar ordering \|
64	\| `content` \| JSON \| Block layout as JSON array \|
65	\| `for_user` \| Data \| If set, workspace is private to that user \|
66	\| `roles` \| Table → Has Role \| Role-based access restrictions \|
67	\| `app` \| Data \| Owning app identifier (v15+) \|
68	\| `indicator_color` \| Color \| Sidebar indicator dot (v15+) \|
69
70	### Child Tables (6 total)
71
72	\| Child Table \| DocType \| Purpose \|
73	\|-------------\|---------\|---------\|
74	\| `charts` \| Workspace Chart \| Dashboard Chart references \|
75	\| `shortcuts` \| Workspace Shortcut \| DocType/Report/Page/URL shortcuts \|
76	\| `links` \| Workspace Link \| Grouped navigation links \|
77	\| `quick_lists` \| Workspace Quick List \| Recent record lists \|
78	\| `number_cards` \| Workspace Number Card \| Metric card references \|
79	\| `custom_blocks` \| Workspace Custom Block \| HTML block references \|
80
81	> CRITICAL: The `content` JSON and the child tables MUST stay in sync. ALWAYS use the Workspace Builder UI or programmatic API — NEVER manually edit the `content` JSON without updating child tables. See `references/anti-patterns.md`.
82
83	---
84
85	## Content JSON Format
86
87	The `content` field is a JSON array. Each element represents a block in the 12-column grid:
88
89	```json
90	[
91	{
92	"id": "unique-block-id",
93	"type": "header",
94	"data": {"text": "Overview", "level": 4, "col": 12}
95	},
96	{
97	"id": "unique-block-id-2",
98	"type": "chart",
99	"data": {
100	"chart_name": "Sales Trends",
101	"col": 12
102	}
103	},
104	{
105	"id": "unique-block-id-3",
106	"type": "number_card",
107	"data": {
108	"number_card_name": "Open Orders",
109	"col": 4
110	}
111	},
112	{
113	"id": "unique-block-id-4",
114	"type": "shortcut",
115	"data": {
116	"shortcut_name": "New Sales Order",
117	"col": 4
118	}
119	},
120	{
121	"id": "unique-block-id-5",
122	"type": "spacer",
123	"data": {"col": 12}
124	}
125	]
126	```
127
128	### Block Types
129
130	\| Type \| `data` fields \| Description \|
131	\|------\|---------------\|-------------\|
132	\| `header` \| `text`, `level`, `col` \| Section heading (h3/h4/h5) \|
133	\| `chart` \| `chart_name`, `col` \| References a Dashboard Chart doc \|
134	\| `number_card` \| `number_card_name`, `col` \| References a Number Card doc \|
135	\| `shortcut` \| `shortcut_name`, `col` \| References a Workspace Shortcut chil

People who liked this also viewed

6 picks

Type

frappe-impl-workspace

151stars49forks

View on GitHub

How to install frappe-impl-workspace?

impertio-studio/frappe_claude_skill_package/frappe-impl-workspace

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-impl-workspace

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Frappe Workspace Implementation Workflow
2
3	Step-by-step workflows for creating and customizing Workspace pages. Workspaces are the block-based dashboard/navigation pages in Frappe Desk.
4
5	Version: v14/v15/v16 (version-specific features noted)
6
7	---
8
9	## Quick Reference
10
11	\| Concept \| Description \|
12	\|---------\|-------------\|
13	\| Workspace \| Block-based page with 12-column grid layout \|
14	\| Public Workspace \| Visible to all permitted users; requires Workspace Manager role to edit \|
15	\| Private Workspace \| Per-user dashboard under "My Workspaces"; any Desk User can create \|
16	\| Content field \| JSON array storing the block layout \|
17	\| Child tables \| 6 tables: charts, shortcuts, links, quick_lists, number_cards, custom_blocks \|
18	\| Module association \| Primary access control mechanism \|
19
20	---
21
22	## Master Decision: What Do You Need?
23
24	```
25	NEED A WORKSPACE?
26	│
27	├─► Default DocType landing page?
28	│ └─► NO workspace needed — Frappe auto-generates list views
29	│
30	├─► Custom dashboard for a module?
31	│ └─► Create PUBLIC Workspace (Workspace Manager role required)
32	│
33	├─► Personal dashboard for a user?
34	│ └─► Create PRIVATE Workspace (appears under "My Workspaces")
35	│
36	└─► Navigation link in sidebar?
37	└─► type="Link" (internal) or type="URL" (external)
38
39	ADDING COMPONENTS?
40	│
41	├─► Key metrics (counts, sums) → Number Cards
42	├─► Trend / time-series data → Dashboard Charts
43	├─► Quick navigation links → Shortcuts
44	├─► Grouped link categories → Link Cards (Card Break + Links)
45	├─► Custom HTML/JS content → Custom HTML Blocks
46	└─► Recent record lists → Quick Lists
47	```
48
49	---
50
51	## Workspace DocType Structure
52
53	### Key Fields
54
55	\| Field \| Type \| Purpose \|
56	\|-------\|------\|---------\|
57	\| `label` \| Data \| Display name in sidebar \|
58	\| `title` \| Data \| Page title (defaults to label) \|
59	\| `module` \| Link → Module Def \| Associates workspace with a module for access control \|
60	\| `parent_page` \| Link → Workspace \| Nesting under another workspace in sidebar \|
61	\| `icon` \| Data \| Sidebar icon (e.g., `"chart-line"`) \|
62	\| `type` \| Select \| `Workspace` / `Link` / `URL` (v15+) \|
63	\| `sequence_id` \| Int \| Sidebar ordering \|
64	\| `content` \| JSON \| Block layout as JSON array \|
65	\| `for_user` \| Data \| If set, workspace is private to that user \|
66	\| `roles` \| Table → Has Role \| Role-based access restrictions \|
67	\| `app` \| Data \| Owning app identifier (v15+) \|
68	\| `indicator_color` \| Color \| Sidebar indicator dot (v15+) \|
69
70	### Child Tables (6 total)
71
72	\| Child Table \| DocType \| Purpose \|
73	\|-------------\|---------\|---------\|
74	\| `charts` \| Workspace Chart \| Dashboard Chart references \|
75	\| `shortcuts` \| Workspace Shortcut \| DocType/Report/Page/URL shortcuts \|
76	\| `links` \| Workspace Link \| Grouped navigation links \|
77	\| `quick_lists` \| Workspace Quick List \| Recent record lists \|
78	\| `number_cards` \| Workspace Number Card \| Metric card references \|
79	\| `custom_blocks` \| Workspace Custom Block \| HTML block references \|
80
81	> CRITICAL: The `content` JSON and the child tables MUST stay in sync. ALWAYS use the Workspace Builder UI or programmatic API — NEVER manually edit the `content` JSON without updating child tables. See `references/anti-patterns.md`.
82
83	---
84
85	## Content JSON Format
86
87	The `content` field is a JSON array. Each element represents a block in the 12-column grid:
88
89	```json
90	[
91	{
92	"id": "unique-block-id",
93	"type": "header",
94	"data": {"text": "Overview", "level": 4, "col": 12}
95	},
96	{
97	"id": "unique-block-id-2",
98	"type": "chart",
99	"data": {
100	"chart_name": "Sales Trends",
101	"col": 12
102	}
103	},
104	{
105	"id": "unique-block-id-3",
106	"type": "number_card",
107	"data": {
108	"number_card_name": "Open Orders",
109	"col": 4
110	}
111	},
112	{
113	"id": "unique-block-id-4",
114	"type": "shortcut",
115	"data": {
116	"shortcut_name": "New Sales Order",
117	"col": 4
118	}
119	},
120	{
121	"id": "unique-block-id-5",
122	"type": "spacer",
123	"data": {"col": 12}
124	}
125	]
126	```
127
128	### Block Types
129
130	\| Type \| `data` fields \| Description \|
131	\|------\|---------------\|-------------\|
132	\| `header` \| `text`, `level`, `col` \| Section heading (h3/h4/h5) \|
133	\| `chart` \| `chart_name`, `col` \| References a Dashboard Chart doc \|
134	\| `number_card` \| `number_card_name`, `col` \| References a Number Card doc \|
135	\| `shortcut` \| `shortcut_name`, `col` \| References a Workspace Shortcut chil

People who liked this also viewed

6 picks

Type