@rglabs/butterfly 2.0.1

package/docs/reports.md

@@ -0,0 +1,197 @@
+# Reports Guide
+
+Reports in Butterfly are created using the `cms_reports` table with queries in `cms_report_queries`.
+
+> **Important:** Always use `cms_report_queries` for Twig query code. The `query` field in `cms_reports` is **deprecated**.
+
+## Creating a Report
+
+### 1. Create Report Record
+
+```bash
+butterfly-cli record add cms_reports --data '{
+  "title": "Sales Report",
+  "alias": "sales-report",
+  "category_id": 1
+}'
+```
+
+### 2. Add Report Query
+
+```bash
+butterfly-cli record add cms_report_queries --data '{
+  "cms_report_id": <REPORT_ID>,
+  "name": "Sales Data",
+  "system_name": "sales_data",
+  "column_size": "1",
+  "query": "{% set records = db().table(\"orders\").where(\"status\", \"completed\").get() %}"
+}'
+```
+
+## Report Query Fields
+
+| Field | Description |
+|-------|-------------|
+| `cms_report_id` | Parent report ID |
+| `name` | Display name |
+| `system_name` | System identifier |
+| `query` | Twig query code |
+| `column_size` | Layout width: `1`, `1/2`, `1/3`, `2/3`, `1/4`, `3/4` |
+| `js_code` | Optional JavaScript processing code |
+
+## Query Code Examples
+
+### Basic Query
+
+```twig
+{% set records = db()
+    .table('orders')
+    .where('status', 'completed')
+    .orderByDesc('created_at')
+    .get()
+%}
+```
+
+### With Parameters
+
+```twig
+{% set startDate = getParameter('start_date') %}
+{% set endDate = getParameter('end_date') %}
+
+{% set records = db()
+    .table('orders')
+    .where('created_at', '>=', startDate)
+    .where('created_at', '<=', endDate)
+    .get()
+%}
+```
+
+### With Joins
+
+```twig
+{% set records = db()
+    .table('orders')
+    .join('users', 'users.id', '=', 'orders.user_id')
+    .join('products', 'products.id', '=', 'orders.product_id')
+    .select(
+        'orders.*',
+        'users.name as customer_name',
+        'products.title as product_name'
+    )
+    .get()
+%}
+```
+
+### Aggregations
+
+```twig
+{% set summary = db()
+    .table('orders')
+    .select(
+        'status',
+        'COUNT(*) as count',
+        'SUM(total) as total_amount'
+    )
+    .groupBy('status')
+    .get()
+%}
+```
+
+### Current User Filter
+
+```twig
+{% set userId = currentUser('id') %}
+
+{% set records = db()
+    .table('tasks')
+    .where('assigned_to', userId)
+    .get()
+%}
+```
+
+## Report Specs
+
+Report specs use the same field types as object specs. Add filter fields to reports:
+
+```bash
+butterfly-cli record add cms_report_specs --data '{
+  "cms_report_id": <REPORT_ID>,
+  "name": "Status Filter",
+  "column_name": "status_filter",
+  "type": "from_list",
+  "val_1": "all:All|pending:Pending|completed:Completed"
+}'
+```
+
+Use in query:
+
+```twig
+{% set statusFilter = getParameter('status_filter') %}
+
+{% set query = db().table('orders') %}
+
+{% if statusFilter and statusFilter != 'all' %}
+    {% set query = query.where('status', statusFilter) %}
+{% endif %}
+
+{% set records = query.get() %}
+```
+
+## File Structure
+
+Downloaded reports are stored in:
+
+```
+butterfly-resources/
+└── reports/
+    └── [report-alias]/
+        ├── report.json           # Report definition
+        ├── queries/
+        │   └── [query-name]/
+        │       ├── query.json
+        │       ├── query_code.bfy   # Twig query code
+        │       └── script.js        # Optional JS code
+        └── specs/
+            └── [field-name]/
+                ├── spec.json
+                └── code.js          # Optional JS code
+```
+
+## JavaScript Code (js_code)
+
+Process data client-side after query execution:
+
+```javascript
+// Access query results
+var data = window.reportData.sales_data;
+
+// Process or transform data
+data.forEach(function(row) {
+    row.formatted_total = '$' + row.total.toFixed(2);
+});
+```
+
+## Best Practices
+
+1. **Use `cms_report_queries`** - Never use the deprecated `query` field in `cms_reports`
+2. **Add parameters** - Use `getParameter()` for user-configurable filters
+3. **Limit results** - Use `.limit()` for large datasets
+4. **Check errors** - Monitor `.butterfly/error_log.txt` for query errors
+5. **Test queries** - Use `butterfly-cli code` to test before deploying
+
+### Testing Queries
+
+```bash
+butterfly-cli code -c "{% set records = db().table('orders').limit(5).get() %}{{ dump(records) }}"
+```
+
+## Column Sizes
+
+| Value | Width |
+|-------|-------|
+| `1` | Full width |
+| `1/2` | Half width |
+| `1/3` | One third |
+| `2/3` | Two thirds |
+| `1/4` | One quarter |
+| `3/4` | Three quarters |