@rglabs/butterfly 2.0.1

package/docs/examples/product-catalog.md

@@ -0,0 +1,195 @@
+# Product Catalog Example
+
+Complete example for creating an e-commerce product catalog.
+
+## Step 1: Create Categories Object
+
+```bash
+# Create object
+butterfly-cli record add objects --data '{
+  "name": "Product Categories",
+  "table_name": "product_categories",
+  "has_order": 1
+}'
+# Note the ID (e.g., 150)
+
+# Add fields
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Name","column_name":"name","type":"string","required":1,"list_column":1,"edit_order_no":1}'
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Slug","column_name":"slug","type":"slug","edit_order_no":2}'
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Parent","column_name":"parent_id","type":"dropdown","val_1":"product_categories","val_2":"id","val_3":"name","edit_order_no":3}'
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Active","column_name":"is_active","type":"checkbox","default_value":"1","edit_order_no":4}'
+```
+
+## Step 2: Create Products Object
+
+```bash
+# Create object
+butterfly-cli record add objects --data '{
+  "name": "Products",
+  "table_name": "products",
+  "has_trash": 1
+}'
+# Note the ID (e.g., 151)
+
+# Basic Info Section
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "Title",
+  "column_name": "title",
+  "type": "string",
+  "required": 1,
+  "list_column": 1,
+  "search_column": 1,
+  "section_title": "Basic Information",
+  "edit_order_no": 1
+}'
+
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "SKU",
+  "column_name": "sku",
+  "type": "string",
+  "list_column": 1,
+  "column_size": "col-md-6",
+  "edit_order_no": 2
+}'
+
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "Category",
+  "column_name": "category_id",
+  "type": "dropdown",
+  "val_1": "product_categories",
+  "val_2": "id",
+  "val_3": "name",
+  "val_4": "is_active = 1",
+  "column_size": "col-md-6",
+  "edit_order_no": 3
+}'
+
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "Description",
+  "column_name": "description",
+  "type": "textarea",
+  "height": 150,
+  "edit_order_no": 4
+}'
+
+# Pricing Section
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "Price",
+  "column_name": "price",
+  "type": "decimal",
+  "required": 1,
+  "section_title": "Pricing",
+  "column_size": "col-md-4",
+  "edit_order_no": 5
+}'
+
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "Sale Price",
+  "column_name": "sale_price",
+  "type": "decimal",
+  "column_size": "col-md-4",
+  "edit_order_no": 6
+}'
+
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "Tax Rate %",
+  "column_name": "tax_rate",
+  "type": "decimal",
+  "default_value": "18",
+  "column_size": "col-md-4",
+  "edit_order_no": 7
+}'
+
+# Inventory Section
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "Stock",
+  "column_name": "stock",
+  "type": "integer",
+  "default_value": "0",
+  "section_title": "Inventory",
+  "column_size": "col-md-6",
+  "edit_order_no": 8
+}'
+
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "Low Stock Alert",
+  "column_name": "low_stock_threshold",
+  "type": "integer",
+  "default_value": "5",
+  "column_size": "col-md-6",
+  "edit_order_no": 9
+}'
+
+# Media
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "Image",
+  "column_name": "image",
+  "type": "image",
+  "section_title": "Media",
+  "edit_order_no": 10
+}'
+
+# Sidebar fields
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "Status",
+  "column_name": "status",
+  "type": "from_list",
+  "val_1": "draft:Draft,active:Active,archived:Archived",
+  "default_value": "draft",
+  "edit_position": 1,
+  "edit_order_no": 1
+}'
+
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "Featured",
+  "column_name": "is_featured",
+  "type": "checkbox",
+  "edit_position": 1,
+  "edit_order_no": 2
+}'
+
+# Calculated field
+butterfly-cli record add object_specs --data '{
+  "object_id": 151,
+  "name": "Final Price",
+  "column_name": "final_price",
+  "type": "calculated",
+  "val_1": "{% set base = info.sale_price > 0 ? info.sale_price : info.price %}{{ base * (1 + info.tax_rate/100) }}",
+  "edit_position": 1,
+  "edit_order_no": 3
+}'
+```
+
+## Step 3: Verify
+
+```bash
+# Check products object
+butterfly-cli record get objects --column table_name --value "products"
+
+# List all product specs
+butterfly-cli record get object_specs --column object_id --value 151
+```
+
+## Result
+
+You now have:
+- **Product Categories** with hierarchical structure
+- **Products** with:
+  - Basic info (title, SKU, category, description)
+  - Pricing (price, sale price, tax rate)
+  - Inventory tracking
+  - Image upload
+  - Status workflow
+  - Calculated final price with tax

package/docs/examples/reports.md

@@ -0,0 +1,187 @@
+# Reports Example
+
+Complete example for creating reports with queries and specs via CLI.
+
+## Overview
+
+Reports in Butterfly consist of three related tables:
+- `cms_reports` - Main report definition
+- `cms_report_queries` - Sub-queries for the report
+- `cms_report_specs` - Field specifications/columns for display
+
+## Step 1: Create a Report
+
+```bash
+# Create the main report
+butterfly-cli record add cms_reports --data '{
+  "name": "Sales Summary",
+  "alias": "sales_summary",
+  "query": "SELECT o.id, o.order_number, o.total, o.created_at, c.name as customer_name FROM orders o LEFT JOIN customers c ON o.customer_id = c.id WHERE 1=1 {% if filters.date_from %}AND o.created_at >= \"{{ filters.date_from }}\"{% endif %} {% if filters.date_to %}AND o.created_at <= \"{{ filters.date_to }}\"{% endif %}"
+}'
+# Response: SUCCESS (ID: 50)
+```
+
+### Report Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Display name of the report |
+| `alias` | URL-friendly identifier (used in file structure) |
+| `query` | Main Twig/SQL query |
+| `cms_report_category_id` | Category ID for grouping |
+
+## Step 2: Add Report Queries
+
+Report queries are sub-queries that can be used within the report.
+
+```bash
+# Add a summary query
+butterfly-cli record add cms_report_queries --data '{
+  "cms_report_id": 50,
+  "name": "totals",
+  "system_name": "totals",
+  "query": "SELECT COUNT(*) as order_count, SUM(total) as total_revenue FROM orders WHERE 1=1 {% if filters.date_from %}AND created_at >= \"{{ filters.date_from }}\"{% endif %}"
+}'
+# Response: SUCCESS (ID: 101)
+
+# Add a query with JavaScript processing
+butterfly-cli record add cms_report_queries --data '{
+  "cms_report_id": 50,
+  "name": "monthly_breakdown",
+  "system_name": "monthly_breakdown",
+  "query": "SELECT DATE_FORMAT(created_at, \"%Y-%m\") as month, SUM(total) as revenue FROM orders GROUP BY month ORDER BY month",
+  "js_code": "// Process results\ndata.forEach(row => { row.revenue_formatted = \"$\" + parseFloat(row.revenue).toFixed(2); });\nreturn data;"
+}'
+# Response: SUCCESS (ID: 102)
+```
+
+### Report Query Fields
+
+| Field | Description |
+|-------|-------------|
+| `cms_report_id` | Foreign key to parent report |
+| `name` | Display name (used for folder naming) |
+| `system_name` | System identifier |
+| `query` | Twig/SQL query code |
+| `js_code` | JavaScript for post-processing results |
+
+## Step 3: Add Report Specs
+
+Report specs define the columns/fields displayed in the report output.
+
+```bash
+# Add column specs
+butterfly-cli record add cms_report_specs --data '{
+  "cms_report_id": 50,
+  "field_name": "order_number",
+  "title": "Order #",
+  "order_no": 1
+}'
+
+butterfly-cli record add cms_report_specs --data '{
+  "cms_report_id": 50,
+  "field_name": "customer_name",
+  "title": "Customer",
+  "order_no": 2
+}'
+
+butterfly-cli record add cms_report_specs --data '{
+  "cms_report_id": 50,
+  "field_name": "total",
+  "title": "Total",
+  "order_no": 3,
+  "js_code": "return \"$\" + parseFloat(value).toFixed(2);"
+}'
+
+butterfly-cli record add cms_report_specs --data '{
+  "cms_report_id": 50,
+  "field_name": "created_at",
+  "title": "Date",
+  "order_no": 4
+}'
+```
+
+### Report Spec Fields
+
+| Field | Description |
+|-------|-------------|
+| `cms_report_id` | Foreign key to parent report |
+| `field_name` | Column name from query results |
+| `title` | Display title for the column |
+| `order_no` | Display order |
+| `js_code` | JavaScript for formatting the field value |
+
+## Complete Example: Inventory Report
+
+```bash
+# 1. Create the report
+butterfly-cli record add cms_reports --data '{
+  "name": "Inventory Status",
+  "alias": "inventory_status",
+  "query": "SELECT p.id, p.sku, p.title, p.stock, p.low_stock_threshold, (p.stock <= p.low_stock_threshold) as is_low_stock FROM products p WHERE p.status = \"active\" ORDER BY p.stock ASC"
+}'
+# Note the ID (e.g., 51)
+
+# 2. Add a summary query
+butterfly-cli record add cms_report_queries --data '{
+  "cms_report_id": 51,
+  "name": "summary",
+  "system_name": "summary",
+  "query": "SELECT COUNT(*) as total_products, SUM(CASE WHEN stock <= low_stock_threshold THEN 1 ELSE 0 END) as low_stock_count, SUM(stock) as total_stock FROM products WHERE status = \"active\""
+}'
+
+# 3. Add report specs
+butterfly-cli record add cms_report_specs --data '{"cms_report_id":51,"field_name":"sku","title":"SKU","order_no":1}'
+butterfly-cli record add cms_report_specs --data '{"cms_report_id":51,"field_name":"title","title":"Product","order_no":2}'
+butterfly-cli record add cms_report_specs --data '{"cms_report_id":51,"field_name":"stock","title":"Stock","order_no":3}'
+butterfly-cli record add cms_report_specs --data '{
+  "cms_report_id": 51,
+  "field_name": "is_low_stock",
+  "title": "Status",
+  "order_no": 4,
+  "js_code": "return value == 1 ? \"<span class=badge-danger>Low Stock</span>\" : \"<span class=badge-success>OK</span>\";"
+}'
+```
+
+## Verify Reports
+
+```bash
+# Get report by alias
+butterfly-cli record get cms_reports --column alias --value "inventory_status"
+
+# List all queries for a report
+butterfly-cli record get cms_report_queries --column cms_report_id --value 51
+
+# List all specs for a report
+butterfly-cli record get cms_report_specs --column cms_report_id --value 51
+```
+
+## File Structure After Download
+
+When you run `butterfly-cli download -t reports`, reports are saved as:
+
+```
+data/reports/
+├── categories.json
+└── inventory_status/
+    ├── report.json
+    ├── main_query.bfy
+    ├── queries/
+    │   └── summary/
+    │       ├── query.json
+    │       └── query_code.bfy
+    └── specs/
+        └── is_low_stock/
+            ├── spec.json
+            └── code.js
+```
+
+## Editing Reports
+
+After downloading, you can edit report files locally and upload changes using `butterfly-cli upload <path>`:
+
+1. Edit `report.json` - Updates report metadata
+2. Edit `main_query.bfy` - Updates main query
+3. Edit `queries/*/query_code.bfy` - Updates query code
+4. Edit `queries/*/script.js` - Updates query JS processing
+5. Edit `specs/*/code.js` - Updates spec JS formatting

package/docs/excel-export.md

@@ -0,0 +1,216 @@
+# Excel Export
+
+Butterfly provides a built-in Excel export function for generating downloadable spreadsheets from Twig code.
+
+## Where It Works
+
+Excel export only works in:
+- **Custom fields** (`template_code.bfy` / `processing_code.bfy`)
+- **Calculated fields** (`code.bfy`)
+- **Reports** (`query_code.bfy`)
+- **Webservices** (`page_code.bfy`)
+
+It does **NOT** work in state machine transition codes, even though they use Twig.
+
+## Recommended Pattern: Query Parameter Trigger
+
+The best approach is to add a query parameter to the current URL and check for it in the same Twig template:
+
+```twig
+{# Check if export is requested #}
+{% if getParameter('download_excel') %}
+    {% set data = db().table('orders').where('status', 'completed').get() %}
+    {% do excel().sheet('Orders').autoTable(data).download('orders.xlsx') %}
+{% endif %}
+
+{# Display export button - preserves existing URL parameters #}
+<a href="{{ currentUrlWith({'download_excel': 1}) }}" class="btn btn-primary">Export to Excel</a>
+```
+
+### Preserving URL Parameters with currentUrlWith()
+
+Use `currentUrlWith()` to merge new parameters with existing query string parameters. This ensures filters, pagination, and other URL parameters are preserved when triggering the export.
+
+```twig
+{{ currentUrlWith({'download_excel': 1}) }}
+{# If current URL is ?page=2&sort=asc, result is ?page=2&sort=asc&download_excel=1 #}
+
+{{ currentUrlWith({'page': 2, 'sort': 'desc'}) }}
+{# New params override existing ones with the same key #}
+```
+
+## Quick Export (autoTable)
+
+```twig
+{% do excel().sheet('Sheet Name').autoTable(data).download('filename.xlsx') %}
+```
+
+## With Options
+
+```twig
+{% do excel().sheet('Report').autoTable(data, 'A1', {
+    labels: {field_name: 'Custom Label'},
+    types: {amount: 'currency', qty: 'number', date: 'date'},
+    widths: {description: 40},
+    decimals: {price: 2},
+    symbols: {amount: '€'},
+    exclude: ['id', 'password'],
+    only: ['name', 'email', 'total']
+}).download('report.xlsx') %}
+```
+
+### autoTable Options
+
+| Option   | Description                                      | Example                          |
+|----------|--------------------------------------------------|----------------------------------|
+| labels   | Custom column headers                            | `{field_name: 'Custom Label'}`   |
+| types    | Column data types                                | `{amount: 'currency'}`           |
+| widths   | Column widths                                    | `{description: 40}`              |
+| decimals | Decimal places for number types                  | `{price: 2}`                     |
+| symbols  | Currency symbols                                 | `{amount: '€'}`                  |
+| aligns   | Column alignment (overrides type defaults)       | `{status: 'center'}`             |
+| exclude  | Fields to exclude from export                    | `['id', 'password']`             |
+| only     | Only include these fields (whitelist)            | `['name', 'email', 'total']`     |
+
+## Column Types
+
+| Type     | Output           | Default Alignment | Options               |
+|----------|------------------|-------------------|------------------------|
+| text     | Plain text       | left              | -                      |
+| currency | ₺ 1,234.56       | right             | symbols: {field: '€'}  |
+| number   | 1,234            | right             | decimals: {field: 0}   |
+| decimal  | 1,234.56         | right             | decimals: {field: 2}   |
+| percent  | 12.34%           | right             | -                      |
+| date     | 25.01.2025       | left              | -                      |
+| datetime | 25.01.2025 14:30 | left              | -                      |
+
+## Column Alignment
+
+The `aligns` option allows you to override the default alignment for any column.
+
+### Available Alignment Values
+
+| Value  | Description                                                   |
+|--------|---------------------------------------------------------------|
+| left   | Align text to the left (default for text, date columns)       |
+| center | Center align text                                             |
+| right  | Align text to the right (default for number/currency columns) |
+
+### Example
+
+```twig
+{% set orders = db().table('orders').get() %}
+
+{% do excel().sheet('Orders').autoTable(orders, 'A1', {
+    labels: {
+        id: 'Order ID',
+        status: 'Status',
+        total: 'Total'
+    },
+    types: {
+        total: 'currency'
+    },
+    aligns: {
+        id: 'center',
+        status: 'center'
+    }
+}).download('orders.xlsx') %}
+```
+
+## Manual Column Definitions (table)
+
+For more control over columns, use the `table()` method:
+
+```twig
+{% do excel().sheet('Sales').table([
+    {key: 'product', label: 'Product', width: 30},
+    {key: 'qty', label: 'Quantity', type: 'number'},
+    {key: 'price', label: 'Price', type: 'currency', symbol: '₺'}
+], data).download('sales.xlsx') %}
+```
+
+### Column Definition Properties
+
+| Property | Description                    |
+|----------|--------------------------------|
+| key      | Field name in data             |
+| label    | Column header text             |
+| width    | Column width                   |
+| type     | Data type (see Column Types)   |
+| symbol   | Currency symbol for currency type |
+
+## Multi-Sheet Export
+
+```twig
+{% do excel()
+    .sheet('Summary').autoTable(summaryData)
+    .sheet('Details').autoTable(detailData)
+    .download('report.xlsx')
+%}
+```
+
+## Styling Methods
+
+```twig
+{% set e = excel().sheet('Report').autoTable(data) %}
+{% do e.bold('A1:D1') %}
+{% do e.background('A1:D1', 'FFFF00') %}
+{% do e.border('A1:D10', 'medium') %}
+{% do e.freeze('A2') %}
+{% do e.download('styled.xlsx') %}
+```
+
+## Available Methods
+
+| Method                                 | Description                  |
+|----------------------------------------|------------------------------|
+| `.sheet(name)`                         | Create/switch sheet          |
+| `.autoTable(data, startCell, options)` | Auto-generate table          |
+| `.table(columns, data, startCell)`     | Manual column table          |
+| `.bold(range)`                         | Bold text                    |
+| `.background(range, color)`            | Background color (hex)       |
+| `.border(range, type)`                 | Borders: thin, medium, thick |
+| `.freeze(cell)`                        | Freeze panes                 |
+| `.merge(range)`                        | Merge cells                  |
+| `.width(col, width)`                   | Set column width             |
+| `.wrapText(range)`                     | Enable text wrap             |
+| `.download(filename)`                  | Download file                |
+
+## Complete Example
+
+```twig
+{# In a report query or custom field template_code #}
+
+{% if getParameter('export_orders') %}
+    {% set orders = db()
+        .table('orders')
+        .join('customers', 'customers.id', '=', 'orders.customer_id')
+        .select(['orders.*', 'customers.name as customer_name'])
+        .where('orders.status', 'completed')
+        .get()
+    %}
+
+    {% set e = excel().sheet('Orders') %}
+    {% do e.autoTable(orders, 'A1', {
+        labels: {
+            customer_name: 'Customer',
+            order_date: 'Date',
+            total_amount: 'Total'
+        },
+        types: {
+            order_date: 'date',
+            total_amount: 'currency'
+        },
+        symbols: {total_amount: '₺'},
+        exclude: ['id', 'customer_id', 'created_at', 'updated_at']
+    }) %}
+    {% do e.bold('A1:D1') %}
+    {% do e.freeze('A2') %}
+    {% do e.download('orders_export.xlsx') %}
+{% endif %}
+
+{# Export button - preserves existing URL parameters like filters #}
+<a href="{{ currentUrlWith({'export_orders': 1}) }}" class="btn btn-success">
+    <i class="lucide-download"></i> Export to Excel
+</a>
+```

package/docs/field-types/README.md

@@ -0,0 +1,29 @@
+# Field Types
+
+## Basic Types
+string, textarea, integer, float, decimal, money, date, datetime, time, checkbox, yes_no, status, code, password, slug, color_picker, hidden_string, hidden_integer
+
+## Selection Types
+| Type | val_1 | val_2 | val_3 | val_4 | val_5 |
+|------|-------|-------|-------|-------|-------|
+| dropdown | table_name | title_column | value_column | where | - |
+| autocomplete | table_name | search_column | value_column | where | additional_columns |
+| from_list | options (pipe-separated) | edit_on_list | other_value | - | - |
+
+## Multi-Select Types
+multidropdown, multicheckbox, multicheckbox_from_list, tag, hierarchy, tree
+
+## File Types
+file_upload, file_upload_multiple, image_upload, image_upload_multiple, image_upload_extended
+
+## Advanced Types
+| Type | val_1 | val_2 | val_3 |
+|------|-------|-------|-------|
+| [calculated](./calculated.md) | twig_code | - | - |
+| [custom](./custom.md) | template_code | processing_code | - |
+| filter | - | - | filter_code |
+| nested | yaml_config | multiple | sortable |
+| nested_single | yaml_config | - | - |
+
+## Column Sizes
+`1` `1/2` `1/3` `1/4` `2/3` `3/4`