@rglabs/butterfly 2.0.1

package/docs/object-specs/js-field-updates.md

@@ -0,0 +1,168 @@
+# Updating Form Field Values via JavaScript
+
+When programmatically updating field values in the admin form (e.g., after fetching data via AJAX), use the appropriate method based on the field type.
+
+## Quick Reference
+
+| Field Type | Update Method | Example |
+|------------|---------------|---------|
+| `calculated` | `bfyRefresh_` | `bfyRefresh_total(150.00)` |
+| `custom` | `bfyRefresh_` | `bfyRefresh_custom_field(data)` |
+| `date` | `bfyRefresh_` | `bfyRefresh_due_date('2024-01-15')` |
+| `string` | `.val().trigger('change')` | `$('[name="title"]').val('New Title').trigger('change')` |
+| `integer` | `.val().trigger('change')` | `$('[name="quantity"]').val(10).trigger('change')` |
+| `decimal` | `.val().trigger('change')` | `$('[name="price"]').val(99.99).trigger('change')` |
+| `textarea` | `.val().trigger('change')` | `$('[name="description"]').val('Text').trigger('change')` |
+| `from_list` | `.val().trigger('change')` | `$('[name="status"]').val('active').trigger('change')` |
+| `datetime` | `.val().trigger('change')` | `$('[name="created_at"]').val('2024-01-15 10:30:00').trigger('change')` |
+| `hidden` | `.val().trigger('change')` | `$('[name="hidden_field"]').val('value').trigger('change')` |
+
+## Fields with bfyRefresh_
+
+For `calculated`, `custom`, and `date` field types, use the `bfyRefresh_` function:
+
+```javascript
+bfyRefresh_COLUMN_NAME(value);
+```
+
+### Example
+
+```javascript
+// Calculated field
+bfyRefresh_total(150.00);
+
+// Custom field
+bfyRefresh_custom_display(data);
+
+// Date field
+bfyRefresh_due_date('2024-01-15');
+```
+
+## All Other Fields
+
+For all other field types, use standard jQuery:
+
+```javascript
+$('[name="COLUMN_NAME"]').val(value).trigger('change');
+```
+
+### Example
+
+```javascript
+// String field
+$('[name="title"]').val('New Title').trigger('change');
+
+// Integer field
+$('[name="quantity"]').val(10).trigger('change');
+
+// Dropdown (from_list)
+$('[name="status"]').val('active').trigger('change');
+
+// Datetime field
+$('[name="created_at"]').val('2024-01-15 10:30:00').trigger('change');
+```
+
+## Fetching Data and Updating Fields
+
+Common pattern for fetching data from another table and updating form fields:
+
+```javascript
+%element%.on('change', function() {
+    var id = $(this).val();
+
+    $.post('/admin/ajax/cms_object/get', {
+        "table_name": 'source_table',
+        "column": "id",
+        "value": id
+    }, function(data) {
+        if (data.data && data.data[0]) {
+            var record = data.data[0];
+
+            // For calculated, custom, date fields - use bfyRefresh_
+            bfyRefresh_calculated_total(record.total);
+            bfyRefresh_due_date(record.due_date);
+
+            // For all other fields - use jQuery
+            $('[name="title"]').val(record.title).trigger('change');
+            $('[name="status"]').val(record.status).trigger('change');
+            $('[name="quantity"]').val(record.quantity).trigger('change');
+        }
+    });
+});
+```
+
+> **Important:** When fetching data, the `column` parameter should be the `column_name` in `val_3` of the source field (for dropdowns, this is the value column).
+
+## Alert Dialog
+
+Display an alert with a callback:
+
+```javascript
+rg_alert('Your message here', function() {
+    // Executed after user clicks OK
+    console.log('User acknowledged');
+});
+```
+
+## Input Masking
+
+Apply input masks to format user input:
+
+### Pattern Characters
+
+| Character | Matches |
+|-----------|---------|
+| `9` | Digit (0-9) |
+| `a` | Letter (A-Za-z) |
+| `*` | Alphanumeric |
+| `#` | Hex digit (0-9, A-F) |
+
+### Pattern Modifiers
+
+| Modifier | Description |
+|----------|-------------|
+| `[x]` | Optional character |
+| `{n}` | Repeat n times |
+| `{n,m}` | Repeat n to m times |
+
+### Examples
+
+```javascript
+// Phone number
+%element%.maskInput('(999) 999-9999');
+
+// Date (DD/MM/YYYY)
+%element%.maskInput('99/99/9999');
+
+// SSN
+%element%.maskInput('999-99-9999');
+
+// MAC address
+%element%.maskInput('##:##:##:##:##:##');
+
+// Fixed 4 digits
+%element%.maskInput('9{4}');
+
+// 1-5 letters
+%element%.maskInput('a{1,5}');
+
+// Optional first digit
+%element%.maskInput('[9]99');
+```
+
+## Conditional Show/Hide Fields
+
+For `from_list` fields, conditionally show/hide other fields:
+
+```javascript
+%element%.condition({
+    "1": ["field_a", "field_b"],  // Show these when value is "1"
+    "2": ["field_c"]               // Show this when value is "2"
+});
+```
+
+## Notes
+
+- `%element%` is automatically replaced with the jQuery selector for the current field
+- Always trigger 'change' event after setting values to ensure form state updates
+- Use `bfyRefresh_` functions for calculated/custom/date fields to properly re-render them

package/docs/objects/README.md

@@ -0,0 +1,89 @@
+# Objects
+
+Objects in Butterfly represent database tables with their configurations, menus, and behaviors.
+
+## Table: `objects`
+
+## Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Display name |
+| `table_name` | string | Database table name (lowercase, underscores) |
+
+## Optional Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `database_alias` | string | `"default"` | Database connection |
+| `auto_increment_column_name` | string | `"id"` | Primary key column |
+| `is_cms_object` | int | `0` | `1` = CMS/system object, `0` = App object |
+| `has_trash` | int | `0` | Enable soft delete |
+| `has_order` | int | `0` | Enable ordering |
+| `has_draft` | int | `0` | Enable draft mode |
+| `description` | string | null | Object description |
+| `section_title` | string | null | Section title in forms |
+| `protect_schema` | int | `0` | Prevent schema modifications |
+
+## Menu Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `main_menu_id` | int | Top-level menu ID |
+| `sub_menu_id` | int | Sub-menu ID |
+| `menu_id` | int | Direct menu ID |
+
+## Creating an Object
+
+```bash
+butterfly-cli record add objects --data '{
+  "name": "Products",
+  "table_name": "products",
+  "description": "Product catalog",
+  "is_cms_object": 0,
+  "has_trash": 1
+}'
+```
+
+## Get Object by ID
+
+```bash
+butterfly-cli record get objects --id 128
+```
+
+## Get Object by Table Name
+
+```bash
+butterfly-cli record get objects --column table_name --value "products"
+```
+
+## Update Object
+
+```bash
+butterfly-cli record edit objects --id 128 --data '{
+  "description": "Updated description"
+}'
+```
+
+## Full Example
+
+```bash
+# Create a Products object
+butterfly-cli record add objects --data '{
+  "name": "Products",
+  "table_name": "products",
+  "database_alias": "default",
+  "auto_increment_column_name": "id",
+  "is_cms_object": 0,
+  "has_trash": 1,
+  "has_order": 0,
+  "description": "Product management"
+}'
+
+# Response: SUCCESS: add operation completed (ID: 150)
+```
+
+## Related
+
+- [Creating Objects Step-by-Step](./creating.md)
+- [Object Specs](../object-specs/README.md) - Add fields to objects

package/docs/objects/creating.md

@@ -0,0 +1,127 @@
+# Creating Objects
+
+Step-by-step guide to creating a new object (table) in Butterfly.
+
+## Step 1: Plan Your Object
+
+Before creating, determine:
+- **Table name**: lowercase, underscores (e.g., `order_items`)
+- **Display name**: Human readable (e.g., "Order Items")
+- **Type**: App object (`is_cms_object: 0`) or CMS object (`is_cms_object: 1`)
+
+## Step 2: Create the Object
+
+### Minimal Object
+
+```bash
+butterfly-cli record add objects --data '{
+  "name": "Order Items",
+  "table_name": "order_items"
+}'
+```
+
+### Full Object with Options
+
+```bash
+butterfly-cli record add objects --data '{
+  "name": "Order Items",
+  "table_name": "order_items",
+  "database_alias": "default",
+  "auto_increment_column_name": "id",
+  "is_cms_object": 0,
+  "has_trash": 1,
+  "has_order": 0,
+  "has_draft": 0,
+  "description": "Items in customer orders",
+  "section_title": "Order Item"
+}'
+```
+
+## Step 3: Add Fields (Object Specs)
+
+After creating the object, add fields using the returned ID:
+
+```bash
+# Get the object ID from the response
+# SUCCESS: add operation completed (ID: 150)
+
+# Add a Name field
+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
+}'
+
+# Add a Price field
+butterfly-cli record add object_specs --data '{
+  "object_id": 150,
+  "name": "Price",
+  "column_name": "price",
+  "type": "decimal",
+  "edit_order_no": 2
+}'
+
+# Add a Status dropdown
+butterfly-cli record add object_specs --data '{
+  "object_id": 150,
+  "name": "Status",
+  "column_name": "status",
+  "type": "from_list",
+  "val_1": "active:Active,inactive:Inactive",
+  "edit_order_no": 3
+}'
+```
+
+## Step 4: Verify
+
+```bash
+# Get the object
+butterfly-cli record get objects --id 150
+
+# Get all specs for the object
+butterfly-cli record get object_specs --column object_id --value 150
+```
+
+## Common Patterns
+
+### E-commerce Product
+
+```bash
+# Create object
+butterfly-cli record add objects --data '{
+  "name": "Products",
+  "table_name": "products",
+  "has_trash": 1
+}'
+
+# Add fields (assuming object_id is 150)
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Title","column_name":"title","type":"string","required":1,"list_column":1,"edit_order_no":1}'
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"SKU","column_name":"sku","type":"string","edit_order_no":2}'
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Price","column_name":"price","type":"decimal","edit_order_no":3}'
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Description","column_name":"description","type":"textarea","edit_order_no":4}'
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Status","column_name":"status","type":"from_list","val_1":"draft:Draft,active:Active,archived:Archived","edit_order_no":5}'
+```
+
+### User Profile
+
+```bash
+# Create object
+butterfly-cli record add objects --data '{
+  "name": "User Profiles",
+  "table_name": "user_profiles"
+}'
+
+# Add fields
+butterfly-cli record add object_specs --data '{"object_id":151,"name":"User","column_name":"user_id","type":"dropdown","val_1":"users","val_2":"id","val_3":"name","required":1,"edit_order_no":1}'
+butterfly-cli record add object_specs --data '{"object_id":151,"name":"Bio","column_name":"bio","type":"textarea","edit_order_no":2}'
+butterfly-cli record add object_specs --data '{"object_id":151,"name":"Avatar","column_name":"avatar","type":"image","edit_order_no":3}'
+```
+
+## Next Steps
+
+- [Object Specs Reference](../object-specs/README.md)
+- [Field Types](../field-types/README.md)