@rglabs/butterfly 2.0.1

package/docs/field-types/calculated.md

@@ -0,0 +1,147 @@
+# Calculated Field Type
+
+Computed field using Twig expressions. Value is calculated server-side.
+
+## Type
+
+```
+type: "calculated"
+```
+
+## Parameters
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `val_1` | string | Twig code for calculation |
+
+## File Export
+
+When downloaded, `val_1` is exported to `code.bfy`.
+
+## Basic Example
+
+Calculate total from price and quantity:
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Total",
+  "column_name": "total",
+  "type": "calculated",
+  "val_1": "{{ info.price * info.quantity }}"
+}'
+```
+
+## Available Variables
+
+| Variable | Description |
+|----------|-------------|
+| `info` | Current record data (e.g., `info.price`, `info.quantity`) |
+| `_user` | Current logged-in user |
+| `_GET` | GET parameters |
+| `_POST` | POST parameters |
+
+## Examples
+
+### Simple Math
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Tax Amount",
+  "column_name": "tax_amount",
+  "type": "calculated",
+  "val_1": "{{ info.subtotal * 0.18 }}"
+}'
+```
+
+### String Concatenation
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Full Name",
+  "column_name": "full_name",
+  "type": "calculated",
+  "val_1": "{{ info.first_name ~ \" \" ~ info.last_name }}"
+}'
+```
+
+### Conditional Value
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Status Label",
+  "column_name": "status_label",
+  "type": "calculated",
+  "val_1": "{% if info.status == 1 %}Active{% else %}Inactive{% endif %}"
+}'
+```
+
+### Date Formatting
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Formatted Date",
+  "column_name": "formatted_date",
+  "type": "calculated",
+  "val_1": "{{ info.created_at|date(\"d/m/Y\") }}"
+}'
+```
+
+### Database Query
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Order Count",
+  "column_name": "order_count",
+  "type": "calculated",
+  "val_1": "{% set count = db().table(\"orders\").where(\"customer_id\", info.id).count() %}{{ count }}"
+}'
+```
+
+### Related Record Lookup
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Category Name",
+  "column_name": "category_name",
+  "type": "calculated",
+  "val_1": "{% set cat = db().table(\"categories\").where(\"id\", info.category_id).first() %}{{ cat.name|default(\"-\") }}"
+}'
+```
+
+### Price with Currency
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Price Display",
+  "column_name": "price_display",
+  "type": "calculated",
+  "val_1": "{{ info.price|number_format(2, \",\", \".\") }} TL"
+}'
+```
+
+### Complex Calculation
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Grand Total",
+  "column_name": "grand_total",
+  "type": "calculated",
+  "val_1": "{% set subtotal = info.price * info.quantity %}{% set discount = subtotal * (info.discount_percent / 100) %}{% set tax = (subtotal - discount) * 0.18 %}{{ subtotal - discount + tax }}"
+}'
+```
+
+## Notes
+
+- Calculated fields are read-only in the form
+- Values are recalculated on each view/save
+- Use `|default()` filter for null handling
+- Complex calculations should be tested with the `code` command first

package/docs/field-types/code-mappings.md

@@ -0,0 +1,84 @@
+# Field Type Code Parameter Mappings
+
+The CLI automatically exports code parameters from field specs based on their field types. Only parameters that contain actual code/configuration are exported as separate files.
+
+## Field Types That Export Code Files
+
+| Field Type | Parameter | Exported File | Description |
+|------------|-----------|---------------|-------------|
+| `calculated` | `val_1` | `code.bfy` | Twig calculation code |
+| `custom` | `val_1` | `template_code.bfy` | Twig template code |
+| `custom` | `val_2` | `processing_code.bfy` | Twig processing code |
+| `filter` | `val_3` | `filter_code.bfy` | Twig filter code |
+| `nested` | `val_1` | `configuration.yaml` | YAML configuration |
+| `nested_single` | `val_1` | `configuration.yaml` | YAML configuration |
+
+## Object Spec Fields That Export Code Files
+
+| Field | Exported File | Description |
+|-------|---------------|-------------|
+| `js_code` | `code.js` | JavaScript code |
+| `css_code` | `style.css` | CSS code |
+
+## Field Types That DO NOT Export Code Files
+
+- **code**: Despite the name, this field type only stores dropdown selections for code language and AI tasks, not actual code content
+- All other field types: Only contain string, dropdown, integer, or checkbox parameters
+
+## Object Files Exported
+
+| File | Description |
+|------|-------------|
+| `object.json` | Complete object definition |
+| `listing_query.bfy` | Object's listing query (if present) |
+
+## Report Files Exported
+
+| File | Description |
+|------|-------------|
+| `report.json` | Report definition from `cms_reports` |
+| `main_query.bfy` | **DEPRECATED** - legacy file, do not use |
+| `categories.json` | All report categories (shared file) |
+
+### Report Query Files
+
+| File | Description |
+|------|-------------|
+| `query.json` | Query definition from `cms_report_queries` |
+| `query_code.bfy` | Twig code from `query` field |
+| `script.js` | JavaScript from `js_code` field (if exists) |
+
+### Report Spec Files
+
+| File | Description |
+|------|-------------|
+| `spec.json` | Spec definition from `cms_report_specs` |
+| `code.js` | JavaScript from `js_code` field (if exists) |
+
+## Directory Structure
+
+```
+butterfly-resources/
+└── objects/
+    └── [butterfly|app]/
+        └── [table_name]/
+            ├── object.json
+            ├── listing_query.bfy
+            └── [field_name]/
+                ├── spec.json
+                ├── code.bfy            # For calculated
+                ├── template_code.bfy   # For custom (val_1)
+                ├── processing_code.bfy # For custom (val_2)
+                ├── filter_code.bfy     # For filter
+                ├── configuration.yaml  # For nested/nested_single
+                ├── code.js             # If js_code exists
+                └── style.css           # If css_code exists
+```
+
+## Usage Notes
+
+1. **Report specs use the same field types** as object specs. Use the same `type` and `val_*` parameter conventions.
+
+2. **When creating reports**, always use `cms_report_queries` for Twig query code. The `query` field in `cms_reports` is deprecated.
+
+3. **Code files can be uploaded** using `butterfly-cli upload <path>`.

package/docs/field-types/custom.md

@@ -0,0 +1,340 @@
+# Custom Field Type
+
+Custom field with Twig template for display and processing code for form submissions.
+
+## Type
+
+```
+type: "custom"
+```
+
+## Parameters
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `val_1` | string | Template code (Twig) - rendered in form |
+| `val_2` | string | Processing code (Twig) - executed on submit |
+
+## File Export
+
+When downloaded:
+- `val_1` → `template_code.bfy`
+- `val_2` → `processing_code.bfy`
+
+## Basic Example
+
+Button that sets a field value:
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Process",
+  "column_name": "process_action",
+  "type": "custom",
+  "val_1": "<button type=\"submit\" name=\"process\" class=\"btn btn-primary\">Process</button>",
+  "val_2": "{% if _POST.process %}{{ setValue(\"status\", \"processed\") }}{% endif %}"
+}'
+```
+
+## Template Code (val_1)
+
+The template is rendered in the edit form. Available variables:
+
+| Variable | Description |
+|----------|-------------|
+| `info` | Current record data (e.g., `info.title`, `info.status`) |
+| `_user` | Current logged-in user |
+| `id` | Current record ID |
+
+### Display Information
+
+```twig
+<div class="alert alert-info">
+  Created by: {{ info.created_by_name }}<br>
+  Created at: {{ info.created_at|date("d/m/Y H:i") }}
+</div>
+```
+
+### Button with Confirmation
+
+```twig
+<button type="submit" name="approve" class="btn btn-success"
+  onclick="return confirm('Are you sure?')">
+  Approve
+</button>
+```
+
+### Input Masking
+
+```twig
+<input type="text" name="phone" id="phone" class="form-control" value="{{ info.phone }}">
+<script>
+  Inputmask('(599) 999 99 99').mask($('#phone'));
+</script>
+```
+
+## Processing Code (val_2)
+
+Executed when form is submitted. Available functions:
+
+| Function | Description |
+|----------|-------------|
+| `setValue(column, value)` | Set field value |
+| `getValue(column)` | Get field value |
+| `errorMessage(msg)` | Show error and stop |
+| `crud()` | CRUD operations on other tables |
+| `db()` | Database queries |
+
+### Set Value
+
+```twig
+{% if _POST.approve %}
+  {{ setValue('status', 'approved') }}
+  {{ setValue('approved_at', 'now'|date('Y-m-d H:i:s')) }}
+  {{ setValue('approved_by', _user.id) }}
+{% endif %}
+```
+
+### Insert Related Record
+
+```twig
+{% if _POST.create_invoice %}
+  {% set response = crud()
+    .table('invoices')
+    .insert({
+      "order_id": getValue('id'),
+      "amount": getValue('total'),
+      "status": "draft"
+    })
+  %}
+  {% if response.success %}
+    {{ setValue('invoice_id', response.id) }}
+  {% else %}
+    {{ errorMessage(response.message) }}
+  {% endif %}
+{% endif %}
+```
+
+### Update Related Record
+
+```twig
+{% if _POST.update_stock %}
+  {% set response = crud()
+    .table('products')
+    .update({
+      "id": getValue('product_id'),
+      "stock": getValue('new_stock')
+    })
+  %}
+{% endif %}
+```
+
+### Validation
+
+```twig
+{% if _POST.submit %}
+  {% if getValue('quantity') < 1 %}
+    {{ errorMessage('Quantity must be at least 1') }}
+  {% endif %}
+  {% if getValue('price') <= 0 %}
+    {{ errorMessage('Price must be positive') }}
+  {% endif %}
+{% endif %}
+```
+
+### Query and Update
+
+```twig
+{% if _POST.apply_discount %}
+  {% set product = db().table('products').where('id', getValue('product_id')).first() %}
+  {% set discounted = product.price * 0.9 %}
+  {{ setValue('final_price', discounted) }}
+{% endif %}
+```
+
+## Complete Examples
+
+### Approval Button
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Approval",
+  "column_name": "approval_action",
+  "type": "custom",
+  "val_1": "{% if info.status != \"approved\" %}<button type=\"submit\" name=\"approve\" class=\"btn btn-success\">Approve</button>{% else %}<span class=\"badge bg-success\">Approved</span>{% endif %}",
+  "val_2": "{% if _POST.approve %}{{ setValue(\"status\", \"approved\") }}{{ setValue(\"approved_at\", \"now\"|date(\"Y-m-d H:i:s\")) }}{% endif %}"
+}'
+```
+
+### Status Workflow
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Actions",
+  "column_name": "workflow_actions",
+  "type": "custom",
+  "val_1": "{% if info.status == \"draft\" %}<button type=\"submit\" name=\"submit_review\" class=\"btn btn-primary\">Submit for Review</button>{% elseif info.status == \"review\" %}<button type=\"submit\" name=\"approve\" class=\"btn btn-success\">Approve</button> <button type=\"submit\" name=\"reject\" class=\"btn btn-danger\">Reject</button>{% endif %}",
+  "val_2": "{% if _POST.submit_review %}{{ setValue(\"status\", \"review\") }}{% elseif _POST.approve %}{{ setValue(\"status\", \"approved\") }}{% elseif _POST.reject %}{{ setValue(\"status\", \"rejected\") }}{% endif %}"
+}'
+```
+
+## Notes
+
+- Custom fields don't create database columns
+- Use for actions, computed displays, and form submissions
+- Template code runs on every page load
+- Processing code runs only on form submit
+
+> **IMPORTANT - Form Input Naming:** Custom fields use `column_name=1` internally to enable the field. When adding form inputs in `template_code`, you MUST use a different `name` attribute than the field's `column_name`. For example, if the custom field's `column_name` is `my_field`, use `<input name="my_field_value" />` instead of `<input name="my_field" />` to avoid conflicts.
+
+---
+
+## Advanced Processing Code Patterns
+
+### Block After (Post-Save Processing)
+
+By default, `processing_code` runs **BEFORE** form data is saved. If you use `setValue()` on a field that's in the form, the form POST value will override it.
+
+To run code **AFTER** save, use `{% block after %}`:
+
+```twig
+{% block after %}
+  {{ setValue('calculated_total', getValue('quantity') * getValue('price')) }}
+  {{ setValue('updated_at', 'now'|date('Y-m-d H:i:s')) }}
+{% endblock %}
+```
+
+> **Important:** `{% block after %}` is **isolated** - it cannot access variables from the main processing_code block. Use `getValue()` or `db()` queries to get data.
+
+#### Execution Order
+
+1. `processing_code` (main block) - runs BEFORE save
+2. Form POST data is saved to database
+3. `{% block after %}` - runs AFTER save (isolated scope)
+
+#### Wrong vs Correct
+
+```twig
+{# WRONG - variable from main block NOT accessible #}
+{% set myValue = 5 %}
+{% block after %}
+  {{ setValue('test_id', myValue) }} {# ERROR: myValue is undefined #}
+{% endblock %}
+
+{# CORRECT - use getValue() or hardcoded values #}
+{% block after %}
+  {{ setValue('test_id', 5) }}
+  {{ setValue('total', getValue('quantity') * getValue('price')) }}
+
+  {# Fetch data using db() #}
+  {% set related = db().table('other_table').where('id', getValue('related_id')).first() %}
+  {{ setValue('related_name', related.name) }}
+{% endblock %}
+```
+
+### Page Refresh After Save
+
+To refresh the page after save (edit operations only):
+
+```twig
+{{ registry('page_refresh', 1) }}
+```
+
+Use when:
+- Twig conditions in template_code depend on saved values
+- UI elements need to update based on new state
+- Calculated/displayed fields need immediate refresh
+
+> **Note:** Add operations already refresh/redirect by default.
+
+### Accessing Current Record Data
+
+| Context | Method | Example |
+|---------|--------|---------|
+| `template_code` | `info.column` | `{{ info.title }}` |
+| `processing_code` | `getValue('column')` | `{{ getValue('title') }}` |
+
+```twig
+{# In template_code.bfy #}
+{{ info.title }}
+{{ info.status }}
+{% if info.is_active == 1 %}Active{% endif %}
+
+{# In processing_code.bfy #}
+{% set title = getValue('title') %}
+{% if getValue('status') == 'pending' %}
+  {{ setValue('status', 'processed') }}
+{% endif %}
+```
+
+### Getting Request Parameters
+
+```twig
+{# Get POST or GET parameter #}
+{% set userId = getParameter('user_id') %}
+
+{# Conditional logic #}
+{% if getParameter('action') == 'approve' %}
+  {{ setValue('status', 'approved') }}
+{% endif %}
+
+{# Multiple parameters #}
+{% set data = {
+  "name": getParameter('name'),
+  "email": getParameter('email'),
+  "phone": getParameter('phone')
+} %}
+```
+
+### CRUD Operations in Processing Code
+
+#### Insert
+
+```twig
+{% set response = crud()
+  .table('TARGET_TABLE')
+  .insert({
+    "field_name": "value"
+  })
+%}
+
+{% if response.success %}
+  {{ response.id }}
+{% else %}
+  {{ errorMessage(response.message) }}
+{% endif %}
+```
+
+#### Update
+
+```twig
+{% set response = crud()
+  .table('TARGET_TABLE')
+  .update({
+    "id": "RECORD_ID",
+    "field_name": "value"
+  })
+%}
+```
+
+#### Delete
+
+```twig
+{% set response = crud()
+  .table('TARGET_TABLE')
+  .delete({
+    "id": "RECORD_ID"
+  })
+%}
+```
+
+#### For Webservices (No Auth)
+
+```twig
+{% set response = crud('default', false)
+  .table('TARGET_TABLE')
+  .insert({...})
+%}
+```

package/docs/object-specs/README.md

@@ -0,0 +1,136 @@
+# Object Specs
+
+Object specs define the fields (columns) of an object. Each spec represents a form field and database column.
+
+## Table: `object_specs`
+
+## Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `object_id` | int | Parent object ID |
+| `name` | string | Display label |
+| `column_name` | string | Database column name |
+| `type` | string | Field type (see [Field Types](../field-types/README.md)) |
+
+## Common Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `required` | int | `0` | `1` = required field |
+| `list_column` | int | `0` | `1` = show in list view |
+| `search_column` | int | `0` | `1` = searchable |
+| `edit_order_no` | int | null | Order in edit form |
+| `list_order_no` | int | null | Order in list view |
+| `default_value` | string | null | Default value |
+| `description` | string | null | Help text |
+
+## Display Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `width` | int | Field width |
+| `height` | int | Field height (for textarea) |
+| `column_size` | string | Bootstrap column size (e.g., "col-md-6") |
+| `section_title` | string | Section header above field |
+| `edit_position` | int | Position: `0`=main, `1`=sidebar |
+| `edit_place_no` | int | Place number within position |
+
+## Validation Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `validation_type` | string | Validation rule |
+| `manipulation_type` | string | Data manipulation |
+| `is_readonly` | int | `1` = read-only field |
+| `is_sensitive` | int | `1` = sensitive data (masked) |
+
+## Code Fields
+
+| Field | Type | Description | Export File |
+|-------|------|-------------|-------------|
+| `js_code` | string | JavaScript for field behavior | `code.js` |
+| `css_code` | string | Custom CSS styles | `style.css` |
+
+## Type-Specific Value Fields
+
+| Field | Description |
+|-------|-------------|
+| `val_1` | Type-specific parameter 1 |
+| `val_2` | Type-specific parameter 2 |
+| `val_3` | Type-specific parameter 3 |
+| `val_4` | Type-specific parameter 4 |
+| `val_5` | Type-specific parameter 5 |
+
+See [Field Types](../field-types/README.md) for what each `val_*` means per type.
+
+## Creating a Spec
+
+### Basic String Field
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Title",
+  "column_name": "title",
+  "type": "string",
+  "required": 1,
+  "list_column": 1,
+  "edit_order_no": 1
+}'
+```
+
+### Dropdown Field
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Status",
+  "column_name": "status",
+  "type": "from_list",
+  "val_1": "active:Active,inactive:Inactive,pending:Pending",
+  "edit_order_no": 2
+}'
+```
+
+### Foreign Key (dropdown)
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Category",
+  "column_name": "category_id",
+  "type": "dropdown",
+  "val_1": "categories",
+  "val_2": "id",
+  "val_3": "name",
+  "edit_order_no": 3
+}'
+```
+
+## Get Specs for an Object
+
+```bash
+butterfly-cli record get object_specs --column object_id --value 128
+```
+
+## Update a Spec
+
+```bash
+butterfly-cli record edit object_specs --id 1071 --data '{
+  "required": 1,
+  "list_column": 1
+}'
+```
+
+## Delete a Spec
+
+```bash
+butterfly-cli record delete object_specs --id 1071
+```
+
+## Related
+
+- [Creating Specs Guide](./creating.md)
+- [Code Parameters](./code-parameters.md)
+- [Field Types Reference](../field-types/README.md)