@rglabs/butterfly 2.0.1

package/docs/page-layout.md

@@ -0,0 +1,361 @@
+# Object Page Layout
+
+This document explains how to organize object add/edit page layouts using tabs and sections.
+
+## Overview
+
+Object pages can be organized into groups (tabs) to better structure fields in the add/edit forms. Despite being called "tabs", these are actually visual groups within the page that organize related fields together.
+
+## Tables Involved
+
+| Table | Purpose |
+|-------|---------|
+| `object_tabs` | Defines groups/tabs for organizing fields |
+| `object_sections` | Defines sections (higher-level grouping) |
+| `object_specs` | Fields assigned to tabs via `edit_place_no` |
+
+## Object Tabs
+
+### Table: `object_tabs`
+
+| Column | Type | Required | Description |
+|--------|------|----------|-------------|
+| `object_id` | int | Yes | The parent object ID |
+| `title` | string | Yes | Display title of the tab/group |
+| `position` | int | No | `0` = Left, `1` = Right |
+| `object_section_id` | int | No | Parent section ID (`0` for no section) |
+
+### Creating a Tab
+
+Use the API to create a new tab:
+
+```
+POST /admin/ajax/cms_object/operation?do=object_tabs__add
+Content-Type: application/x-www-form-urlencoded
+
+object_id=<OBJECT_ID>&title=<TAB_TITLE>&position=0&object_section_id=0
+```
+
+> **Important:** Set `object_section_id=0` when creating tabs without a parent section.
+
+**Example:**
+```
+POST /admin/ajax/cms_object/operation?do=object_tabs__add
+Content-Type: application/x-www-form-urlencoded
+
+object_id=128&title=Basic Information&position=0&object_section_id=0
+```
+
+### Editing a Tab
+
+```
+POST /admin/ajax/cms_object/operation?do=object_tabs__edit
+Content-Type: application/x-www-form-urlencoded
+
+id=<TAB_ID>&title=<NEW_TITLE>&position=<POSITION>
+```
+
+## Assigning Fields to Tabs
+
+Fields (`object_specs`) are assigned to tabs using the `edit_place_no` column, which references the `object_tabs.id`.
+
+### Object Specs Tab Assignment
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `edit_place_no` | int | References `object_tabs.id` - assigns field to a tab |
+| `edit_position` | int | `0` = Left column, `1` = Right column (within the tab) |
+| `edit_order_no` | int | Order of the field within its position |
+
+### Assigning a Field to a Tab
+
+To assign an existing field to a tab, update the `edit_place_no`:
+
+```
+POST /admin/ajax/cms_object/operation?do=object_specs__edit
+Content-Type: application/x-www-form-urlencoded
+
+id=<SPEC_ID>&edit_place_no=<TAB_ID>
+```
+
+**Example:**
+```
+POST /admin/ajax/cms_object/operation?do=object_specs__edit
+Content-Type: application/x-www-form-urlencoded
+
+id=1071&edit_place_no=5
+```
+
+## Object Sections (Optional)
+
+Sections provide a higher-level grouping above tabs.
+
+### Table: `object_sections`
+
+| Column | Type | Required | Description |
+|--------|------|----------|-------------|
+| `object_id` | int | No | Parent object ID |
+| `title` | string | No | Section display title |
+| `slug` | string | No | URL-friendly identifier |
+
+## Layout Example
+
+```
+Object Edit Page
+├── Section: "Product Details" (object_sections)
+│   ├── Tab: "Basic Info" (object_tabs, position=0)
+│   │   ├── Left Column (edit_position=0)
+│   │   │   ├── Name (edit_order_no=1)
+│   │   │   └── SKU (edit_order_no=2)
+│   │   └── Right Column (edit_position=1)
+│   │       ├── Price (edit_order_no=1)
+│   │       └── Stock (edit_order_no=2)
+│   └── Tab: "Description" (object_tabs, position=0)
+│       └── Full Description (edit_order_no=1)
+└── Tab: "Settings" (object_tabs, position=1)
+    └── Is Active (edit_order_no=1)
+```
+
+## Workflow
+
+### 1. Create Tabs for an Object
+
+First, identify the object ID and create the tabs needed:
+
+```
+# Create "Basic Information" tab
+POST /admin/ajax/cms_object/operation?do=object_tabs__add
+object_id=128&title=Basic Information&position=0&object_section_id=0
+
+# Create "Additional Details" tab
+POST /admin/ajax/cms_object/operation?do=object_tabs__add
+object_id=128&title=Additional Details&position=0&object_section_id=0
+
+# Create "Settings" tab (right side)
+POST /admin/ajax/cms_object/operation?do=object_tabs__add
+object_id=128&title=Settings&position=1&object_section_id=0
+```
+
+### 2. Assign Fields to Tabs
+
+Update each field's `edit_place_no` to assign it to the appropriate tab:
+
+```
+# Assign "name" field (spec_id=1071) to "Basic Information" tab (tab_id=5)
+POST /admin/ajax/cms_object/operation?do=object_specs__edit
+id=1071&edit_place_no=5
+
+# Assign "description" field (spec_id=1072) to "Additional Details" tab (tab_id=6)
+POST /admin/ajax/cms_object/operation?do=object_specs__edit
+id=1072&edit_place_no=6
+```
+
+### 3. Update Tab and Field Order (Bulk)
+
+After creating tabs and assigning fields, use the CLI or API to set the complete layout order.
+
+#### Using CLI (Recommended)
+
+```bash
+# From a JSON file
+butterfly-cli layout -f layout.json
+
+# Inline JSON data
+butterfly-cli layout -d '[{"id":0,"tabs":[{"id":0,"specs":[{"id":1323,"order_no":1}],"order_no":1}]}]'
+```
+
+#### Using API
+
+```
+POST /admin/ajax/cms_object_specs/edit_order
+Content-Type: application/json
+
+[
+  {
+    "id": 0,
+    "tabs": [
+      {
+        "id": 0,
+        "specs": [
+          {"id": 1323, "order_no": 1},
+          {"id": 1329, "order_no": 2},
+          {"id": 1331, "order_no": 3}
+        ],
+        "order_no": 1
+      },
+      {
+        "id": 159,
+        "specs": [
+          {"id": 1328, "order_no": 10}
+        ],
+        "order_no": 2
+      }
+    ]
+  },
+  {
+    "id": 1,
+    "tabs": [
+      {
+        "id": -1,
+        "specs": [],
+        "order_no": 4
+      },
+      {
+        "id": 160,
+        "specs": [],
+        "order_no": 5
+      }
+    ]
+  }
+]
+```
+
+**Structure explanation:**
+
+| Level | Field | Description |
+|-------|-------|-------------|
+| Root array | `id` | Position: `0` = Left, `1` = Right |
+| Root array | `tabs` | Array of tabs in this position |
+| Tab | `id` | Tab ID (`0` = default/no tab, `-1` = empty placeholder) |
+| Tab | `order_no` | Order of the tab within the position |
+| Tab | `specs` | Array of specs (fields) in this tab |
+| Spec | `id` | Spec ID (from `object_specs.id`) |
+| Spec | `order_no` | Order of the field within the tab |
+
+> **Note:** This endpoint updates all tab orders and field orders in a single request. Use this after creating tabs to organize the complete page layout.
+
+### 4. Set Field Order (Individual)
+
+Alternatively, control the order of individual fields using `edit_order_no`:
+
+```
+POST /admin/ajax/cms_object/operation?do=object_specs__edit
+id=1071&edit_place_no=5&edit_order_no=1&edit_position=0
+
+POST /admin/ajax/cms_object/operation?do=object_specs__edit
+id=1073&edit_place_no=5&edit_order_no=2&edit_position=0
+```
+
+## Field Positioning Summary
+
+| Property | Values | Description |
+|----------|--------|-------------|
+| `edit_place_no` | Tab ID | Which tab the field belongs to |
+| `edit_position` | `0` (left), `1` (right) | Column within the tab |
+| `edit_order_no` | Integer | Order within the column |
+| `column_size` | Size value | Field width (see below) |
+| `section_title` | String | Visual section header above field |
+
+## Column Sizes
+
+### Object Left Column Size (`left_column_size`)
+
+Controls the width of the left column area in the object edit page. Set on the `objects` table.
+
+| Value | Description |
+|-------|-------------|
+| `null` | Default width |
+| `"1"` | Full width |
+| `"1/3"` | One-third width |
+| `"1/4"` | Quarter width |
+
+**Example:**
+```
+POST /admin/ajax/cms_object/operation?do=objects__edit
+Content-Type: application/x-www-form-urlencoded
+
+id=128&left_column_size=1/4
+```
+
+### Field Column Size (`column_size`)
+
+Controls the width of individual fields within their container. Set on `object_specs` table.
+
+| Value | Description |
+|-------|-------------|
+| `null` or `""` | Default width (auto) |
+| `"1"` | Full width (100%) |
+| `"1/2"` | Half width (50%) |
+| `"1/3"` | One-third width (33%) |
+| `"1/4"` | Quarter width (25%) |
+
+**Example:**
+```
+POST /admin/ajax/cms_object/operation?do=object_specs__edit
+Content-Type: application/x-www-form-urlencoded
+
+id=1071&column_size=1/2
+```
+
+### Visual Layout Example
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Object Edit Page (left_column_size=1/4)                     │
+├───────────────┬─────────────────────────────────────────────┤
+│ Left Column   │ Main Content Area                           │
+│ (1/4 width)   │                                             │
+│               │ ┌─────────────────┬─────────────────┐       │
+│ - Status      │ │ Name (1/2)      │ SKU (1/2)       │       │
+│ - Category    │ ├─────────────────┴─────────────────┤       │
+│               │ │ Description (1)                    │       │
+│               │ ├───────────┬───────────┬───────────┤       │
+│               │ │ Price     │ Stock     │ Weight    │       │
+│               │ │ (1/3)     │ (1/3)     │ (1/3)     │       │
+│               │ └───────────┴───────────┴───────────┘       │
+└───────────────┴─────────────────────────────────────────────┘
+```
+
+## CLI Commands
+
+### Layout Command
+
+Update object page layout (tab and field ordering) using the `layout` command:
+
+```bash
+butterfly-cli layout [options]
+```
+
+**Options:**
+- `-f, --file <path>` - Path to JSON file with layout data
+- `-d, --data <json>` - Inline JSON layout data
+
+**Examples:**
+
+```bash
+# Update layout from a JSON file
+butterfly-cli layout -f layout.json
+
+# Update layout with inline JSON
+butterfly-cli layout -d '[{"id":0,"tabs":[{"id":0,"specs":[{"id":1323,"order_no":1},{"id":1329,"order_no":2}],"order_no":1}]},{"id":1,"tabs":[]}]'
+```
+
+**Layout JSON Structure:**
+
+```json
+[
+  {
+    "id": 0,
+    "tabs": [
+      {
+        "id": 159,
+        "specs": [
+          {"id": 1323, "order_no": 1},
+          {"id": 1329, "order_no": 2}
+        ],
+        "order_no": 1
+      }
+    ]
+  },
+  {
+    "id": 1,
+    "tabs": []
+  }
+]
+```
+
+## Related
+
+- [Object Specs Reference](./object-specs/README.md)
+- [Objects Reference](./objects/README.md)
+- [Creating Object Specs](./object-specs/creating.md)

package/docs/permissions.md

@@ -0,0 +1,260 @@
+# Object Permissions
+
+This guide covers how to configure default permissions for objects and manage user group permissions.
+
+## Object Default Permissions
+
+Objects have a `usergroup_id` field that sets the default (maximum possible) permissions for that object across the entire system.
+
+### Setting Default Permissions on an Object
+
+To assign a user group as the default permission template for an object:
+
+```bash
+butterfly-cli record edit objects --id <object_id> --data '{"usergroup_id": <usergroup_id>}'
+```
+
+**What this does:**
+- Sets the maximum possible permissions that any user can have for this object
+- Acts as a system-wide permission ceiling
+- Individual user/group permissions cannot exceed this default
+
+> **Important:** If `usergroup_id` is set on an object but no matching permission record exists in `object_permissions`, users will receive a **404 error**. Always create corresponding permission records after setting the object's `usergroup_id`.
+
+### Example
+
+```bash
+# Set user group 5 as the default permission template for object 123
+butterfly-cli record edit objects --id 123 --data '{"usergroup_id": 5}'
+```
+
+## User Groups
+
+User groups are the main permission system in Butterfly.
+
+### LDAP Integration
+
+If LDAP integration is enabled, user groups are automatically synced for users through the `ldap_id` column in the `usergroups` table.
+
+## User Permission Assignment
+
+Users are assigned to groups via two columns in the `users` table:
+
+| Column | Description |
+|--------|-------------|
+| `role_id` | Main user group ID (references `usergroups.id`) |
+| `usergroup_ids` | Comma-separated list of additional group IDs |
+
+### How Permissions Work
+
+- `role_id` is the user's primary group but has **no additional power** over groups in `usergroup_ids`
+- All groups (primary + additional) contribute equally to the user's permissions
+- **Exception:** `role_id = 1` grants access to everything (superadmin)
+- **Important:** Even superadmin (`role_id = 1`) is limited by the `usergroup_id` set on an object, which defines the maximum possible permissions
+
+### Example: Assigning User to Groups
+
+```bash
+# Set primary group and additional groups for a user
+butterfly-cli record edit users --id <user_id> --data '{"role_id": 5, "usergroup_ids": "3,7,12"}'
+```
+
+### Permission Hierarchy
+
+```
+Object's usergroup_id (ceiling)
+         ↓
+    Sets maximum possible permissions
+         ↓
+User's role_id + usergroup_ids (combined)
+         ↓
+    Actual permissions = intersection of user groups and object ceiling
+```
+
+## Permission Levels
+
+Butterfly has two levels of permissions:
+
+### Level 1: Object-Based Generic Permissions
+
+The `object_permissions` table defines generic CRUD permissions for a user group on an object.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `object_id` | int | Target object ID |
+| `usergroup_id` | int | User group ID |
+| `add_permission` | bool | Can add records |
+| `edit_permission` | bool | Can edit records |
+| `delete_permission` | bool | Can delete records |
+| `approve_permission` | bool | Can approve records |
+| `view_permission` | bool | Can view records |
+| `object_spec_ids` | string | Comma-separated field IDs (empty = all fields) |
+
+**Field-Level Access (`object_spec_ids`):**
+- If empty: User has access to all fields
+- If defined: User can only see/access the specified field IDs
+
+#### Example: Create Object Permission
+
+```bash
+# Grant view and edit permissions to user group 5 for object 123
+butterfly-cli record add object_permissions --data '{
+  "object_id": 123,
+  "usergroup_id": 5,
+  "add_permission": 0,
+  "edit_permission": 1,
+  "delete_permission": 0,
+  "approve_permission": 0,
+  "view_permission": 1
+}'
+
+# Grant access to only specific fields (IDs 45, 46, 47)
+butterfly-cli record add object_permissions --data '{
+  "object_id": 123,
+  "usergroup_id": 5,
+  "view_permission": 1,
+  "object_spec_ids": "45,46,47"
+}'
+```
+
+### Level 2: Permission Exceptions
+
+The `cms_permission_exceptions` table provides granular control over field and record-level permissions.
+
+**Common Fields:**
+
+| Column | Description |
+|--------|-------------|
+| `usergroup_id` | User group ID |
+| `object_id` | Target object ID |
+| `permission_type` | Type of exception: `default_value`, `fields`, or `condition` |
+| `description` | Description of the exception |
+
+> **Note:** `permission_type` is a `from_list` field. Always use the string keys (`default_value`, `fields`, `condition`) in CLI commands.
+
+---
+
+#### Default Value (`permission_type: "default_value"`)
+
+Forces a field value on add and prevents editing.
+
+| Column | Description |
+|--------|-------------|
+| `object_spec_id` | Field ID to control |
+| `default_value` | Value to force |
+
+**Behavior:**
+- On **add**: Field is set to `default_value` automatically
+- On **edit**: Field becomes read-only (cannot be changed)
+
+```bash
+# Force status field (ID 50) to "pending" for user group 5
+butterfly-cli record add cms_permission_exceptions --data '{
+  "usergroup_id": 5,
+  "object_id": 123,
+  "permission_type": "default_value",
+  "object_spec_id": 50,
+  "default_value": "pending",
+  "description": "Force pending status for this group"
+}'
+```
+
+---
+
+#### Field Restriction (`permission_type: "fields"`)
+
+Field-based restrictions for hiding or making fields read-only.
+
+| Column | Description |
+|--------|-------------|
+| `restriction_type` | `only_fields` (whitelist), `hide_fields` (blacklist), or `readonly` |
+| `restriction_condition` | Twig condition - call `{{ valid() }}` to enable exception |
+| `object_specs` | Comma-separated field IDs the rule applies to |
+
+**Restriction Types:**
+
+| Value | Description |
+|-------|-------------|
+| `only_fields` | Whitelist - show ONLY these fields |
+| `hide_fields` | Blacklist - hide these specific fields |
+| `readonly` | Make these fields read-only |
+
+**Condition:**
+- Has access to `{{ info.COLUMN_NAME }}` for current record data
+- Call `{{ valid() }}` to activate the exception
+- If `valid()` is not called, the exception does not apply
+
+```bash
+# Hide fields 45,46 when status is "closed"
+butterfly-cli record add cms_permission_exceptions --data '{
+  "usergroup_id": 5,
+  "object_id": 123,
+  "permission_type": "fields",
+  "restriction_type": "hide_fields",
+  "restriction_condition": "{% if info.status == \"closed\" %}{{ valid() }}{% endif %}",
+  "object_specs": "45,46",
+  "description": "Hide sensitive fields when closed"
+}'
+
+# Make all fields read-only except 10,11,12
+butterfly-cli record add cms_permission_exceptions --data '{
+  "usergroup_id": 5,
+  "object_id": 123,
+  "permission_type": "fields",
+  "restriction_type": "only_fields",
+  "object_specs": "10,11,12",
+  "description": "Only allow editing these fields"
+}'
+```
+
+---
+
+#### Record Condition (`permission_type: "condition"`)
+
+Record-based restriction that filters which records users can see/edit/delete.
+
+| Column | Description |
+|--------|-------------|
+| `object_spec_id` | Field ID to filter on |
+| `condition_value` | Value(s) to match (comma-separated). Supports Twig with `{{ info.XXX }}` |
+
+**Behavior:**
+- Filters listing, edit, and delete actions
+- Only records matching the condition are accessible
+- `condition_value` can be static or dynamic (Twig)
+
+```bash
+# User group 5 can only see records where department_id = 3
+butterfly-cli record add cms_permission_exceptions --data '{
+  "usergroup_id": 5,
+  "object_id": 123,
+  "permission_type": "condition",
+  "object_spec_id": 55,
+  "condition_value": "3",
+  "description": "Restrict to department 3"
+}'
+
+# User can only see their own records (using current user ID)
+butterfly-cli record add cms_permission_exceptions --data '{
+  "usergroup_id": 5,
+  "object_id": 123,
+  "permission_type": "condition",
+  "object_spec_id": 60,
+  "condition_value": "{{ info.created_by }}",
+  "description": "Users see only their own records"
+}'
+
+# Allow multiple values
+butterfly-cli record add cms_permission_exceptions --data '{
+  "usergroup_id": 5,
+  "object_id": 123,
+  "permission_type": "condition",
+  "object_spec_id": 55,
+  "condition_value": "1,2,3",
+  "description": "Restrict to departments 1, 2, or 3"
+}'
+```
+
+## See Also
+
+- [docs/CLAUDE.md](CLAUDE.md) - Quick reference