@rglabs/butterfly 2.0.1

package/docs/object-specs/code-parameters.md

@@ -0,0 +1,151 @@
+# Code Parameters
+
+Object specs support custom JavaScript and CSS for field behavior and styling.
+
+## JavaScript (js_code)
+
+The `js_code` field adds client-side behavior to fields.
+
+### Placeholder: `%element%`
+
+Use `%element%` as a placeholder for the current field's jQuery selector. It gets replaced with the actual selector at runtime.
+
+### Conditional Field Display
+
+Show/hide fields based on dropdown selection:
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Type",
+  "column_name": "type",
+  "type": "from_list",
+  "val_1": "1:Physical,2:Digital",
+  "js_code": "%element%.condition({\"1\": [\"weight\", \"dimensions\"], \"2\": [\"download_url\"]})"
+}'
+```
+
+This shows `weight` and `dimensions` fields when "Physical" is selected, and `download_url` when "Digital" is selected.
+
+### On Change Handler
+
+Fetch data from another table when field changes:
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Customer",
+  "column_name": "customer_id",
+  "type": "dropdown",
+  "val_1": "customers",
+  "val_2": "id",
+  "val_3": "name",
+  "js_code": "%element%.on(\"change\", function() { var id = $(this).val(); $.post(\"/admin/ajax/cms_object/get\", {\"table_name\": \"customers\", \"column\": \"id\", \"value\": id}, function(data) { $(\"[name=email]\").val(data.data[0].email); }); })"
+}'
+```
+
+### Auto-populate Fields
+
+```javascript
+// js_code value (formatted for readability)
+%element%.on('change', function() {
+  var id = $(this).val();
+
+  $.post('/admin/ajax/cms_object/get', {
+    "table_name": "products",
+    "column": "id",
+    "value": id
+  }, function(data) {
+    // For dynamic fields (date, dropdown, etc.)
+    bfyRefresh_price(data.data[0].price);
+
+    // For static fields (string, integer, textarea)
+    $('[name="sku"]').val(data.data[0].sku).trigger('change');
+  });
+});
+```
+
+### Input Masking
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Phone",
+  "column_name": "phone",
+  "type": "string",
+  "js_code": "Inputmask(\"(999) 999-9999\").mask(%element%)"
+}'
+```
+
+## CSS (css_code)
+
+The `css_code` field adds custom styles.
+
+### Basic Styling
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Important Note",
+  "column_name": "note",
+  "type": "textarea",
+  "css_code": ".field-note textarea { background-color: #fff3cd; border-color: #ffc107; }"
+}'
+```
+
+### Hide Label
+
+```bash
+--data '{
+  "css_code": ".field-hidden_field label { display: none; }"
+}'
+```
+
+## File Export
+
+When downloading objects, code fields are exported to separate files:
+
+```
+butterfly-resources/objects/app/table_name/
+├── object.json
+└── field_name/
+    ├── spec.json
+    ├── code.js      # js_code content
+    └── style.css    # css_code content
+```
+
+## Examples
+
+### Complete Dropdown with Conditions
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Payment Method",
+  "column_name": "payment_method",
+  "type": "from_list",
+  "val_1": "credit_card:Credit Card,bank_transfer:Bank Transfer,cash:Cash",
+  "js_code": "%element%.condition({\"credit_card\": [\"card_number\", \"expiry_date\"], \"bank_transfer\": [\"bank_name\", \"account_number\"]})",
+  "edit_order_no": 5
+}'
+```
+
+### Auto-fill from Related Record
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Product",
+  "column_name": "product_id",
+  "type": "dropdown",
+  "val_1": "products",
+  "val_2": "id",
+  "val_3": "name",
+  "js_code": "%element%.on(\"change\", function() { var id = $(this).val(); if(id) { $.post(\"/admin/ajax/cms_object/get\", {\"table_name\": \"products\", \"column\": \"id\", \"value\": id}, function(data) { if(data.data[0]) { $(\"[name=unit_price]\").val(data.data[0].price).trigger(\"change\"); $(\"[name=sku]\").val(data.data[0].sku).trigger(\"change\"); } }); } })"
+}'
+```
+
+## Related
+
+- [Field Types Reference](../field-types/README.md)
+- [Custom Field Type](../field-types/custom.md) - For complex template/processing code

package/docs/object-specs/creating.md

@@ -0,0 +1,203 @@
+# Creating Object Specs
+
+Step-by-step guide to adding fields to objects.
+
+## Prerequisites
+
+You need an object ID. Get it by:
+
+```bash
+# By table name
+butterfly-cli record get objects --column table_name --value "products"
+
+# Or list all app objects
+butterfly-cli record get objects --column is_cms_object --value 0
+```
+
+## Basic Field Creation
+
+### Syntax
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": <OBJECT_ID>,
+  "name": "<Display Name>",
+  "column_name": "<column_name>",
+  "type": "<field_type>",
+  ...additional options
+}'
+```
+
+### Simple Text Field
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Title",
+  "column_name": "title",
+  "type": "string",
+  "required": 1,
+  "list_column": 1,
+  "search_column": 1,
+  "edit_order_no": 1
+}'
+```
+
+## Field Ordering
+
+Use `edit_order_no` to control form layout:
+
+```bash
+# First field
+--data '{"object_id":128,"name":"Name","column_name":"name","type":"string","edit_order_no":1}'
+
+# Second field
+--data '{"object_id":128,"name":"Email","column_name":"email","type":"string","edit_order_no":2}'
+
+# Third field
+--data '{"object_id":128,"name":"Status","column_name":"status","type":"from_list","edit_order_no":3}'
+```
+
+## Field Positioning
+
+### Main Content vs Sidebar
+
+```bash
+# Main content area (default)
+--data '{"object_id":128,"name":"Description","column_name":"description","type":"textarea","edit_position":0}'
+
+# Sidebar
+--data '{"object_id":128,"name":"Status","column_name":"status","type":"from_list","edit_position":1}'
+```
+
+### Column Sizing
+
+```bash
+# Half width
+--data '{"object_id":128,"name":"First Name","column_name":"first_name","type":"string","column_size":"col-md-6"}'
+
+# Full width (default)
+--data '{"object_id":128,"name":"Bio","column_name":"bio","type":"textarea","column_size":"col-md-12"}'
+```
+
+## Section Headers
+
+Group fields with section titles:
+
+```bash
+# Basic Info section
+--data '{"object_id":128,"name":"Name","column_name":"name","type":"string","section_title":"Basic Information","edit_order_no":1}'
+--data '{"object_id":128,"name":"Email","column_name":"email","type":"string","edit_order_no":2}'
+
+# Contact section
+--data '{"object_id":128,"name":"Phone","column_name":"phone","type":"string","section_title":"Contact Details","edit_order_no":3}'
+```
+
+## Common Field Types
+
+### String (Text Input)
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Title",
+  "column_name": "title",
+  "type": "string"
+}'
+```
+
+### Integer
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Quantity",
+  "column_name": "quantity",
+  "type": "integer",
+  "default_value": "0"
+}'
+```
+
+### Textarea
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Description",
+  "column_name": "description",
+  "type": "textarea",
+  "height": 200
+}'
+```
+
+### Dropdown (from_list)
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Status",
+  "column_name": "status",
+  "type": "from_list",
+  "val_1": "draft:Draft,published:Published,archived:Archived"
+}'
+```
+
+### 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"
+}'
+```
+
+### Date
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Due Date",
+  "column_name": "due_date",
+  "type": "date"
+}'
+```
+
+### Checkbox
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Is Active",
+  "column_name": "is_active",
+  "type": "checkbox",
+  "default_value": "1"
+}'
+```
+
+## Batch Creation
+
+Create multiple fields efficiently:
+
+```bash
+# Using a JSON file
+echo '[
+  {"object_id":128,"name":"Name","column_name":"name","type":"string","required":1,"edit_order_no":1},
+  {"object_id":128,"name":"Email","column_name":"email","type":"string","edit_order_no":2},
+  {"object_id":128,"name":"Status","column_name":"status","type":"from_list","val_1":"active:Active,inactive:Inactive","edit_order_no":3}
+]' > /tmp/specs.json
+
+# Create each (loop in shell)
+for spec in $(cat /tmp/specs.json | jq -c '.[]'); do
+  butterfly-cli record add object_specs --data "$spec" -y
+done
+```
+
+## Next Steps
+
+- [Code Parameters](./code-parameters.md) - Adding js_code and css_code
+- [Field Types Reference](../field-types/README.md) - All field types and parameters

package/docs/object-specs/js-code-examples.md

@@ -0,0 +1,208 @@
+# JavaScript Code Examples for Object Specs
+
+The `js_code` field in object specs allows custom JavaScript functionality. Code is exported as `code.js` in the field directory.
+
+## File Location
+
+```
+butterfly-resources/
+└── objects/
+    └── [butterfly|app]/
+        └── [table_name]/
+            └── [field_name]/
+                ├── spec.json
+                └── code.js    # JavaScript code
+```
+
+## The %element% Placeholder
+
+`%element%` is automatically replaced with the jQuery selector for the current field element. Use it to access the field's methods and events.
+
+```javascript
+// %element% becomes something like $('[name="field_name"]')
+%element%.on('change', function() {
+    // Handle change
+});
+```
+
+## Common Patterns
+
+### Conditional Field Visibility
+
+Show/hide fields based on dropdown selection:
+
+```javascript
+%element%.condition({
+    "1": ["field_a", "field_b"],  // Show when value is "1"
+    "2": ["field_c"],              // Show when value is "2"
+    "3": []                        // Hide all when value is "3"
+});
+```
+
+### Fetch Data from Another Table
+
+Load related data when field changes:
+
+```javascript
+%element%.on('change', function() {
+    var id = $(this).val();
+
+    if (!id) return;
+
+    $.post('/admin/ajax/cms_object/get', {
+        "table_name": 'source_table',
+        "column": "id",
+        "value": id
+    }, function(response) {
+        if (response.data && response.data[0]) {
+            var record = response.data[0];
+
+            // Update calculated/custom/date fields
+            bfyRefresh_total(record.total);
+            bfyRefresh_due_date(record.due_date);
+
+            // Update other fields
+            $('[name="title"]').val(record.title).trigger('change');
+            $('[name="status"]').val(record.status).trigger('change');
+        }
+    });
+});
+```
+
+> **Note:** The `column` parameter should match `val_3` of the source field (the value column for dropdowns).
+
+### Alert Dialog
+
+Show alert with callback:
+
+```javascript
+%element%.on('click', function(e) {
+    e.preventDefault();
+
+    rg_alert('Are you sure you want to proceed?', function() {
+        // User clicked OK
+        console.log('Confirmed');
+    });
+});
+```
+
+### Input Masking
+
+Format user input automatically:
+
+```javascript
+// Phone number
+%element%.maskInput('(999) 999-9999');
+
+// Date
+%element%.maskInput('99/99/9999');
+
+// Custom format
+%element%.maskInput('AAA-999');
+```
+
+#### Mask Pattern Reference
+
+| Character | Description |
+|-----------|-------------|
+| `9` | Digit (0-9) |
+| `a` | Letter (A-Za-z) |
+| `*` | Alphanumeric |
+| `#` | Hex digit (0-9, A-F) |
+| `[x]` | Optional character |
+| `{n}` | Repeat n times |
+| `{n,m}` | Repeat n to m times |
+
+### Validation on Change
+
+```javascript
+%element%.on('change', function() {
+    var value = $(this).val();
+
+    if (value && value.length < 3) {
+        rg_alert('Value must be at least 3 characters');
+        $(this).val('').trigger('change');
+    }
+});
+```
+
+### Disable Field Based on Condition
+
+```javascript
+$('[name="status"]').on('change', function() {
+    var status = $(this).val();
+
+    if (status === 'locked') {
+        %element%.prop('disabled', true);
+    } else {
+        %element%.prop('disabled', false);
+    }
+});
+```
+
+### Auto-Calculate Value
+
+```javascript
+$('[name="quantity"], [name="unit_price"]').on('change', function() {
+    var qty = parseFloat($('[name="quantity"]').val()) || 0;
+    var price = parseFloat($('[name="unit_price"]').val()) || 0;
+    var total = qty * price;
+
+    bfyRefresh_total(total.toFixed(2));
+});
+```
+
+### Load Options Dynamically
+
+```javascript
+%element%.on('focus', function() {
+    var $select = $(this);
+
+    if ($select.data('loaded')) return;
+
+    $.get('/admin/ajax/cms_object/list', {
+        table_name: 'categories'
+    }, function(response) {
+        $select.empty().append('<option value="">Select...</option>');
+
+        response.data.forEach(function(item) {
+            $select.append('<option value="' + item.id + '">' + item.name + '</option>');
+        });
+
+        $select.data('loaded', true);
+    });
+});
+```
+
+## Field Type Update Methods
+
+Remember to use the correct update method:
+
+| Field Types | Method |
+|-------------|--------|
+| `calculated`, `custom`, `date` | `bfyRefresh_COLUMN_NAME(value)` |
+| All others | `$('[name="COLUMN_NAME"]').val(value).trigger('change')` |
+
+## Creating JavaScript Code via CLI
+
+```bash
+# The js_code goes in the spec record
+butterfly-cli record add object_specs --data '{
+  "object_id": 128,
+  "name": "Category",
+  "column_name": "category_id",
+  "type": "from_list",
+  "val_1": "categories",
+  "val_3": "id",
+  "val_4": "name",
+  "js_code": "%element%.on(\"change\", function() { console.log(\"Changed to:\", $(this).val()); });"
+}'
+```
+
+Or edit the `code.js` file directly after downloading:
+
+```bash
+butterfly-cli download -t objects -n my_table
+# Edit butterfly-resources/objects/app/my_table/category_id/code.js
+butterfly-cli upload butterfly-resources/objects/app/my_table/category_id/
+```