frappe-syntax-reports

Name: frappe-syntax-reports
Author: Impertio-Studio

151stars49forks

How to install frappe-syntax-reports?

impertio-studio/frappe_claude_skill_package/frappe-syntax-reports

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-syntax-reports

Installs into the current project.

Summary

Use when building Query Reports, Script Reports, or configuring Report Builder, including chart data integration. Prevents report errors from wrong column definitions, missing permissions, and incorrect data formatting. Covers Query Report (SQL-based), Script Report (Python-based

Files · 1

View on GitHub

SKILL.md

1	# Reports: Query, Script & Report Builder
2
3	## Quick Reference
4
5	### Report Types at a Glance
6
7	\| Type \| Code Required \| Use Case \| Permission \|
8	\|------\|--------------\|----------\|------------\|
9	\| Report Builder \| None \| Simple single-DocType listing with filters, group by \| Any user \|
10	\| Query Report \| SQL only \| Direct SQL queries, legacy column format \| System Manager \|
11	\| Script Report (Standard) \| Python + JS \| Complex logic, charts, summaries, trees \| Administrator + Developer Mode \|
12	\| Script Report (Custom) \| Python in UI \| Quick custom reports without app deployment \| System Manager \|
13
14	### Script Report execute() Return Values
15
16	```python
17	def execute(filters=None):
18	columns = [...] # List of dicts
19	data = [...] # List of dicts or lists
20	message = "..." # Optional: HTML message above report
21	chart = {...} # Optional: chart configuration
22	report_summary = [...] # Optional: summary cards
23	skip_total_row = False # Optional: suppress auto-total
24	return columns, data, message, chart, report_summary, skip_total_row
25	```
26
27	### Column Definition (Dict Format)
28
29	```python
30	columns = [
31	{
32	"fieldname": "customer",
33	"label": _("Customer"),
34	"fieldtype": "Link",
35	"options": "Customer",
36	"width": 200
37	},
38	{
39	"fieldname": "amount",
40	"label": _("Amount"),
41	"fieldtype": "Currency",
42	"options": "currency", # field in row holding currency code
43	"width": 120
44	}
45	]
46	```
47
48	### Query Report Column Format (Legacy String)
49
50	```sql
51	SELECT
52	name as "Sales Order:Link/Sales Order:200",
53	customer as "Customer:Link/Customer:180",
54	grand_total as "Total:Currency:120",
55	transaction_date as "Date:Date:100"
56	FROM `tabSales Order`
57	WHERE docstatus = 1
58	```
59
60	Format: `"Label:Fieldtype/Options:Width"` — Options only needed for Link, Dynamic Link, Currency.
61
62	### Filter Definition (JS)
63
64	```javascript
65	frappe.query_reports["My Report"] = {
66	filters: [
67	{
68	fieldname: "company",
69	label: __("Company"),
70	fieldtype: "Link",
71	options: "Company",
72	default: frappe.defaults.get_user_default("company"),
73	reqd: 1
74	},
75	{
76	fieldname: "from_date",
77	label: __("From Date"),
78	fieldtype: "Date",
79	default: frappe.datetime.add_months(frappe.datetime.get_today(), -1)
80	},
81	{
82	fieldname: "status",
83	label: __("Status"),
84	fieldtype: "Select",
85	options: "\nDraft\nSubmitted\nCancelled"
86	}
87	]
88	};
89	```
90
91	## Decision Tree: Which Report Type?
92
93	```
94	Need a report?
95	├─ Simple list/group of one DocType → Report Builder
96	│ (no code, UI-only, supports Group By with Count/Sum/Avg)
97	├─ Direct SQL query, no Python logic needed → Query Report
98	│ (SQL in Report doc, column format in aliases)
99	├─ Complex logic, calculations, charts → Script Report (Standard)
100	│ (Python .py + JS .js files, requires Developer Mode)
101	└─ Quick one-off with Python but no app deploy → Script Report (Custom)
102	(Python in Report doc UI, System Manager can create)
103	```
104
105	```
106	Script Report returns what?
107	├─ Just data → return columns, data
108	├─ Data + chart → return columns, data, None, chart
109	├─ Data + summary → return columns, data, None, None, report_summary
110	├─ Data + message → return columns, data, message
111	└─ Everything → return columns, data, message, chart, report_summary, skip_total_row
112	```
113
114	## Supported Fieldtypes for Columns
115
116	\| Fieldtype \| Options Required \| Notes \|
117	\|-----------\|-----------------\|-------\|
118	\| `Data` \| No \| Plain text \|
119	\| `Link` \| DocType name \| Clickable link to document \|
120	\| `Dynamic Link` \| Fieldname holding DocType \| Pair with a column containing DocType \|
121	\| `Currency` \| Currency field or code \| Fieldname in row that holds currency \|
122	\| `Float` \| No \| Decimal number \|
123	\| `Int` \| No \| Integer \|
124	\| `Percent` \| No \| Shows percentage bar \|
125	\| `Date` \| No \| Date display \|
126	\| `Datetime` \| No \| Date + time \|
127	\| `Check` \| No \| Boolean checkbox \|
128	\| `Select` \| No \| Dropdown value \|
129	\| `Text` \| No \| Long text \|
130	\| `HTML` \| No \| Raw HTML rendering \|
131
132	## Supported Filter Fieldtypes
133
134	\| Fieldtype \| Options \| Behavior \|
135	\|---------

People who liked this also viewed

6 picks

Type

frappe-syntax-reports

151stars49forks

View on GitHub

How to install frappe-syntax-reports?

impertio-studio/frappe_claude_skill_package/frappe-syntax-reports

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-syntax-reports

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Reports: Query, Script & Report Builder
2
3	## Quick Reference
4
5	### Report Types at a Glance
6
7	\| Type \| Code Required \| Use Case \| Permission \|
8	\|------\|--------------\|----------\|------------\|
9	\| Report Builder \| None \| Simple single-DocType listing with filters, group by \| Any user \|
10	\| Query Report \| SQL only \| Direct SQL queries, legacy column format \| System Manager \|
11	\| Script Report (Standard) \| Python + JS \| Complex logic, charts, summaries, trees \| Administrator + Developer Mode \|
12	\| Script Report (Custom) \| Python in UI \| Quick custom reports without app deployment \| System Manager \|
13
14	### Script Report execute() Return Values
15
16	```python
17	def execute(filters=None):
18	columns = [...] # List of dicts
19	data = [...] # List of dicts or lists
20	message = "..." # Optional: HTML message above report
21	chart = {...} # Optional: chart configuration
22	report_summary = [...] # Optional: summary cards
23	skip_total_row = False # Optional: suppress auto-total
24	return columns, data, message, chart, report_summary, skip_total_row
25	```
26
27	### Column Definition (Dict Format)
28
29	```python
30	columns = [
31	{
32	"fieldname": "customer",
33	"label": _("Customer"),
34	"fieldtype": "Link",
35	"options": "Customer",
36	"width": 200
37	},
38	{
39	"fieldname": "amount",
40	"label": _("Amount"),
41	"fieldtype": "Currency",
42	"options": "currency", # field in row holding currency code
43	"width": 120
44	}
45	]
46	```
47
48	### Query Report Column Format (Legacy String)
49
50	```sql
51	SELECT
52	name as "Sales Order:Link/Sales Order:200",
53	customer as "Customer:Link/Customer:180",
54	grand_total as "Total:Currency:120",
55	transaction_date as "Date:Date:100"
56	FROM `tabSales Order`
57	WHERE docstatus = 1
58	```
59
60	Format: `"Label:Fieldtype/Options:Width"` — Options only needed for Link, Dynamic Link, Currency.
61
62	### Filter Definition (JS)
63
64	```javascript
65	frappe.query_reports["My Report"] = {
66	filters: [
67	{
68	fieldname: "company",
69	label: __("Company"),
70	fieldtype: "Link",
71	options: "Company",
72	default: frappe.defaults.get_user_default("company"),
73	reqd: 1
74	},
75	{
76	fieldname: "from_date",
77	label: __("From Date"),
78	fieldtype: "Date",
79	default: frappe.datetime.add_months(frappe.datetime.get_today(), -1)
80	},
81	{
82	fieldname: "status",
83	label: __("Status"),
84	fieldtype: "Select",
85	options: "\nDraft\nSubmitted\nCancelled"
86	}
87	]
88	};
89	```
90
91	## Decision Tree: Which Report Type?
92
93	```
94	Need a report?
95	├─ Simple list/group of one DocType → Report Builder
96	│ (no code, UI-only, supports Group By with Count/Sum/Avg)
97	├─ Direct SQL query, no Python logic needed → Query Report
98	│ (SQL in Report doc, column format in aliases)
99	├─ Complex logic, calculations, charts → Script Report (Standard)
100	│ (Python .py + JS .js files, requires Developer Mode)
101	└─ Quick one-off with Python but no app deploy → Script Report (Custom)
102	(Python in Report doc UI, System Manager can create)
103	```
104
105	```
106	Script Report returns what?
107	├─ Just data → return columns, data
108	├─ Data + chart → return columns, data, None, chart
109	├─ Data + summary → return columns, data, None, None, report_summary
110	├─ Data + message → return columns, data, message
111	└─ Everything → return columns, data, message, chart, report_summary, skip_total_row
112	```
113
114	## Supported Fieldtypes for Columns
115
116	\| Fieldtype \| Options Required \| Notes \|
117	\|-----------\|-----------------\|-------\|
118	\| `Data` \| No \| Plain text \|
119	\| `Link` \| DocType name \| Clickable link to document \|
120	\| `Dynamic Link` \| Fieldname holding DocType \| Pair with a column containing DocType \|
121	\| `Currency` \| Currency field or code \| Fieldname in row that holds currency \|
122	\| `Float` \| No \| Decimal number \|
123	\| `Int` \| No \| Integer \|
124	\| `Percent` \| No \| Shows percentage bar \|
125	\| `Date` \| No \| Date display \|
126	\| `Datetime` \| No \| Date + time \|
127	\| `Check` \| No \| Boolean checkbox \|
128	\| `Select` \| No \| Dropdown value \|
129	\| `Text` \| No \| Long text \|
130	\| `HTML` \| No \| Raw HTML rendering \|
131
132	## Supported Filter Fieldtypes
133
134	\| Fieldtype \| Options \| Behavior \|
135	\|---------

People who liked this also viewed

6 picks

Type