@rglabs/butterfly 2.0.2 → 2.1.0

package/.claude/commands/docs-page-layout.md

@@ -0,0 +1,12 @@
+Read the page layout documentation from docs/page-layout.md.
+
+Provide guidance on organizing object add/edit page layouts including:
+- Creating and managing object_tabs (groups/tabs)
+- Creating object_sections (higher-level grouping)
+- Assigning fields to tabs via edit_place_no
+- Field positioning (edit_position, edit_order_no)
+- Column sizes (left_column_size, column_size)
+- Bulk layout ordering via API or butterfly-cli layout command
+- section_title for visual section headers within tabs
+
+Focus on the specific layout task the user asks about, or provide an overview if no specific task is mentioned.

package/CLAUDE.md

@@ -109,6 +109,46 @@ See [docs/translations.md](docs/translations.md) for full documentation.
 
 See [docs/twig-helpers.md](docs/twig-helpers.md) for full documentation.
 
+## Email Sending (Quick Reference)
+
+```twig
+{# Send email directly #}
+{{ sendEmail('recipient@example.com', 'Subject', '<p>HTML body</p>') }}
+
+{# Send using cms_email_templates (recommended pattern) #}
+{% set tpl = db().table('cms_email_templates').where('alias', 'template-alias').first() %}
+{% set replacements = {} %}
+{% for key, val in vars %}
+  {% set replacements = replacements|merge({('{{ ' ~ key ~ ' }}'): val}) %}
+{% endfor %}
+{{ sendEmail(recipient, tpl.subject|replace(replacements), tpl.content|replace(replacements)) }}
+```
+
+**Email Templates (`cms_email_templates`):**
+- Store HTML email templates with `{{ variable_name }}` placeholders in subject and content
+- Use `alias` field for programmatic lookup
+- `test_data` field: JSON with sample values for preview
+- `preview` field: calculated field that renders content with test_data, shown in edit page
+- Templates should use **inline CSS** (not classes) for email client compatibility
+- Link to state machine via `bfy_state_machine_id` for organization
+
+**Important:** Twig `|replace` filter requires a **mapping** (associative array), NOT individual string arguments. Build replacements map with `|merge`.
+
+## Settings (Quick Reference)
+
+```twig
+{# Get single setting value #}
+{% set value = setting('group_alias', 'setting_alias') %}
+
+{# Get all settings in a group #}
+{% set all = setting('group_alias') %}
+{{ all.setting_alias.value }}
+```
+
+**Tables:** `cms_setting_groups` (groups by alias) → `cms_settings` (individual settings)
+
+See [docs/twig-helpers.md](docs/twig-helpers.md#settings) for full documentation.
+
 ## JavaScript Field Updates (Quick Reference)
 
 | Field Types | Method |
@@ -124,13 +164,34 @@ See [docs/object-specs/js-field-updates.md](docs/object-specs/js-field-updates.m
 /admin/SINGULAR_TABLE_NAME/list
 /admin/SINGULAR_TABLE_NAME/add
 /admin/SINGULAR_TABLE_NAME/edit/ID
+/admin/cms_report/view/REPORT_ID
 ```
 
 For non-default database: `/admin/DATABASE_ALIAS/SINGULAR_TABLE_NAME/...`
 
 ## Object Menu Placement
 
-Format: `MainMenu>SubMenu>MenuItemName` or with icons: `MainMenu::icon>SubMenu::icon>Item::icon`
+Admin menus have 3 levels. Levels 1-2 are created in `cms_admin_menus`, level 3 is set on the object itself.
+
+### Step 1: Create Main Menu (Level 1) and Sub Menu (Level 2) in `cms_admin_menus`
+
+```bash
+# Level 1 - Main menu
+butterfly-cli record add cms_admin_menus --data '{"title":"Menu Name","parent_id":0,"icon":"b-icon-icon-name"}'
+# Returns ID, e.g. 67
+
+# Level 2 - Sub menu (parent_id = main menu ID)
+butterfly-cli record add cms_admin_menus --data '{"title":"Sub Menu","parent_id":67,"icon":"b-icon-icon-name"}'
+# Returns ID, e.g. 68
+```
+
+### Step 2: Assign Object to Menu (Level 3) via `main_menu_id` + `sub_menu_id`
+
+```bash
+butterfly-cli record edit objects --id <object_id> --data '{"main_menu_id":<main_menu_id>,"sub_menu_id":<sub_menu_id>}'
+```
+
+**Do NOT** create level 3 entries in `cms_admin_menus`. The object itself becomes the menu item when `main_menu_id` and `sub_menu_id` are set.
 
 ## Object Default Permissions
 
@@ -159,6 +220,46 @@ butterfly-cli record add <table_name> --data '{"bfy_workspace_id": <workspace_id
 
 See [docs/workspaces.md](docs/workspaces.md) for full documentation.
 
+## Page Generation Guidelines
+
+When a task requires generating a page:
+
+- **Simple pages** (single table, basic CRUD): Use standard Butterfly object pages.
+- **Complex pages** (multiple table relations, complex design, custom layouts): Use **custom report pages** with Butterfly endpoints and objects for data operations.
+
+### Custom Report Page Approach
+
+For complex pages, create a custom report page with HTML/Twig template and use Butterfly's AJAX endpoints to save/update data:
+
+```
+POST /admin/ajax/cms_object/operation?do=TABLE_NAME__OPERATION
+Content-Type: application/x-www-form-urlencoded; charset=UTF-8
+X-Requested-With: XMLHttpRequest
+```
+
+**Example - saving page data via AJAX:**
+```javascript
+$.ajax({
+    url: '/admin/ajax/cms_object/operation?do=TABLE_NAME__edit',
+    type: 'POST',
+    data: {
+        csrf_token: csrfToken,
+        id: recordId,
+        field1: value1,
+        field2: value2
+    },
+    success: function(response) { /* handle response */ }
+});
+```
+
+**Key points:**
+- Use `?do=TABLE_NAME__add` for creating new records
+- Use `?do=TABLE_NAME__edit` for updating existing records
+- Always include `csrf_token` in the request data
+- Use `X-Requested-With: XMLHttpRequest` header
+- Content type should be `application/x-www-form-urlencoded`
+- For employee/user-related forms, auto-populate fields (department, role, sicil no, location, email) from the `employees` table using the logged-in user context
+
 ## Project-Specific Instructions
 
 Always check if `docs/PROJECT_SPECIFIC.md` exists and prioritize those instructions.
@@ -187,6 +288,9 @@ Always check if `docs/PROJECT_SPECIFIC.md` exists and prioritize those instructi
 - [docs/bfy-splitting.md](docs/bfy-splitting.md) - BFY file splitting for large files
 - [docs/translations.md](docs/translations.md) - Translations and i18n
 - [docs/WORKFLOW_API.md](docs/WORKFLOW_API.md) - Workflow node types
+- [docs/butterfly_upload_api_docs-2.md](docs/butterfly_upload_api_docs-2.md) - File upload (admin panel & REST API)
+- [docs/pdf-generation.md](docs/pdf-generation.md) - PDF generation from templates
+- [docs/IMPLEMENTATION_PROMPT.md](docs/IMPLEMENTATION_PROMPT.md) - Process module implementation template
 
 **Slash Commands:**
 
@@ -199,3 +303,65 @@ Always check if `docs/PROJECT_SPECIFIC.md` exists and prioritize those instructi
 | `/docs-webservice` | When creating API endpoints or webservices using reports with `custom_seo` |
 
 > **AI INSTRUCTION:** Always use the relevant slash command before working on any task related to that topic. This ensures accurate implementation without guessing syntax or parameters.
+
+## Custom Report Page Best Practices
+
+### Turkish Characters
+Always use proper Turkish characters in UI text (not ASCII equivalents):
+- ç, ş, ü, ö, ğ, ı, İ (not c, s, u, o, g, i, I)
+- Examples: Seçiniz, Bütçe, Açıklama, Bölümü, Görevi, Değişiklikleri, Düzenleme
+
+### Child Record Duplication Prevention
+When a custom report page saves a parent record + child records (e.g., expense items, team members):
+- **On edit/update**: Always **delete existing child records first**, then re-add all current rows. Otherwise each save duplicates all children.
+- **There is NO `delete_where` endpoint.** Delete each record individually: `?do=TABLE__delete` with `id` parameter.
+- Pass existing child record IDs from Twig to JS via `window._data.existingIds` JSON. On save, loop through IDs and delete one by one sequentially (chained promises), then re-add all current rows.
+- **Chain deletes sequentially** (not parallel) to avoid race conditions — use `.then()` chaining.
+- **On add**: Save parent first, get the returned `response.id`, then save children with that ID.
+
+### Reserved Parameter Names
+The following parameter names are reserved by Butterfly and must NOT be used in custom report pages:
+- `id` — reserved by the system (page/report internal ID)
+
+Use alternative names like `form_id`, `record_id`, etc. Example:
+```twig
+{% set editId = getParameter('form_id') %}
+```
+```javascript
+window.location.href = url + '?form_id=' + recordId;
+```
+
+### Current User Access
+- Use `currentUser('field')` to access user fields — NOT `app.user.username` or `app.user.*`.
+- Example: `currentUser('sicil_no')`, `currentUser('id')`, `currentUser('email')`
+
+### Twig Functions That DO NOT Exist
+- `csrf_token()` — does NOT exist in Butterfly Twig. Get CSRF token via JavaScript: `$('meta[name="csrf-token"]').attr('content')`.
+
+### UI Dialog Functions
+- **Deletions/destructive actions**: Use `rg_confirm('message', callback)` instead of native `confirm()`.
+- **Error/info messages**: Use `rg_alert('message')` instead of native `alert()`.
+- Never use native browser `alert()` or `confirm()` dialogs.
+
+### State Machine Transitions
+- The role field on transitions is `bfy_state_machine_role_ids` (plural), NOT `bfy_state_machine_role_id`.
+- Transition display name field is `button_title`, not `name`.
+
+### State Machine `state` Column vs Manual `status`
+- When an object has a `state` type field bound to a state machine, the state machine manages the `state` column automatically.
+- **Do NOT create a separate `status` field** or manually set status values. Use the `state` column everywhere (queries, filters, conditions).
+- State values are the `system_name` from `bfy_state_machine_states` (e.g., `created`, `taslak`, `onay_bekliyor`).
+- In custom report pages, check `record.state` for readonly/edit logic, NOT a manual `status` field.
+- For new records, the state machine auto-assigns the initial state on creation — do not set it manually in JS.
+
+### Rendering Dynamic Table Rows
+- Render existing data rows via JavaScript (from a `window._data` JSON object set in Twig), NOT via Twig `{% for %}` loops in `<tbody>`.
+- This prevents duplication issues: JS owns all row rendering, Twig only provides the initial data as JSON.
+- Pattern: `{% set dataJson = records|json_encode %}` then `<script>window._data = {{ dataJson|raw }};</script>`
+
+### Tailwind CSS for Modern UI
+- Use Tailwind CDN: `<link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css" rel="stylesheet">`
+- Prefer Tailwind utility classes over custom CSS in report pages.
+
+### Report Download Type
+- Use `butterfly-cli download -t reports` (NOT `-t cms_reports`) to download reports.

package/dist/commands/setup.js

@@ -1,5 +1,6 @@
 import React from 'react';
 import { render, Box, Text } from 'ink';
+import { spawn } from 'child_process';
 import { SetupForm } from '../components/SetupForm.js';
 import { saveAuthConfig } from '../utils/auth.js';
 import { ButterflyAPI } from '../utils/api.js';
@@ -24,7 +25,19 @@ const SetupCommand = ({ onExit }) => {
             }
             await copyDocs();
             setStatus('success');
-            setTimeout(() => onExit(0), 2000);
+            setTimeout(() => {
+                setStatus('downloading');
+                const child = spawn('butterfly-cli', ['download'], {
+                    stdio: 'inherit',
+                    shell: true,
+                });
+                child.on('close', (code) => {
+                    onExit(code || 0);
+                });
+                child.on('error', () => {
+                    onExit(1);
+                });
+            }, 1000);
         }
         catch (error) {
             setErrorMessage(error instanceof Error ? error.message : 'Unknown error');
@@ -36,6 +49,7 @@ const SetupCommand = ({ onExit }) => {
         status === 'input' && React.createElement(SetupForm, { onSubmit: handleSubmit }),
         status === 'testing' && React.createElement(Text, { color: "yellow" }, "Testing connection..."),
         status === 'success' && React.createElement(Text, { color: "green" }, "\u2713 Configuration saved successfully in .butterfly/config.json, docs copied to docs/ and commands to .claude/commands/"),
+        status === 'downloading' && React.createElement(Text, { color: "yellow" }, "Starting download..."),
         status === 'error' && React.createElement(Text, { color: "red" },
             "\u2717 Error: ",
             errorMessage)));

package/dist/commands/view-report.d.ts

@@ -0,0 +1,8 @@
+interface ViewReportOptions {
+    id?: string;
+    alias?: string;
+    raw?: boolean;
+}
+export default function viewReportCommand(options: ViewReportOptions): Promise<void>;
+export {};
+//# sourceMappingURL=view-report.d.ts.map

package/dist/commands/view-report.js

@@ -0,0 +1,89 @@
+import { loadAuthConfig } from '../utils/auth.js';
+import { ButterflyAPI } from '../utils/api.js';
+function stripHtmlToText(html) {
+    let text = html;
+    text = text.replace(/<head[\s\S]*?<\/head>/gi, '');
+    text = text.replace(/<script[\s\S]*?<\/script>/gi, '');
+    text = text.replace(/<style[\s\S]*?<\/style>/gi, '');
+    text = text.replace(/<br\s*\/?>/gi, '\n');
+    text = text.replace(/<hr\s*\/?>/gi, '\n---\n');
+    text = text.replace(/<\/(?:p|div|h[1-6]|li|tr|section|article|header|footer|blockquote)>/gi, '\n');
+    text = text.replace(/<\/(?:th|td)>\s*<(?:th|td)[^>]*>/gi, '\t');
+    text = text.replace(/<[^>]+>/g, '');
+    text = text.replace(/&amp;/g, '&');
+    text = text.replace(/&lt;/g, '<');
+    text = text.replace(/&gt;/g, '>');
+    text = text.replace(/&quot;/g, '"');
+    text = text.replace(/&#39;/g, "'");
+    text = text.replace(/&nbsp;/g, ' ');
+    text = text.replace(/\n{3,}/g, '\n\n');
+    text = text
+        .split('\n')
+        .map(line => line.trim())
+        .filter((line, i, arr) => {
+        if (line === '')
+            return i > 0 && arr[i - 1] !== '';
+        return true;
+    })
+        .join('\n')
+        .trim();
+    return text;
+}
+export default async function viewReportCommand(options) {
+    try {
+        if (!options.id && !options.alias) {
+            console.error('ERROR: Either --id or --alias is required');
+            process.exit(1);
+        }
+        if (options.id && options.alias) {
+            console.error('ERROR: Cannot use both --id and --alias together');
+            process.exit(1);
+        }
+        const config = await loadAuthConfig();
+        if (!config) {
+            console.error('ERROR: No authentication configured. Run "butterfly-cli setup" first.');
+            process.exit(1);
+        }
+        const api = new ButterflyAPI(config);
+        await api.authenticate();
+        let reportId;
+        if (options.id) {
+            reportId = options.id;
+        }
+        else {
+            const records = await api.fetchTableAdvanced('cms_reports', {
+                column: 'alias',
+                value: options.alias
+            });
+            if (records.length === 0) {
+                console.error(`ERROR: Report not found with alias "${options.alias}"`);
+                process.exit(1);
+            }
+            reportId = records[0].id;
+        }
+        const viewPath = `/admin/cms_report/view/${reportId}?bfy_focus_content=true`;
+        const response = await api.httpClient.get(viewPath, {
+            responseType: 'text',
+            headers: {
+                'Accept': 'text/html'
+            }
+        });
+        const html = response.data;
+        if (!html || html.length === 0) {
+            console.error('ERROR: Empty response from report view');
+            process.exit(1);
+        }
+        if (options.raw) {
+            console.log(html);
+        }
+        else {
+            console.log(stripHtmlToText(html));
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`ERROR: ${error.message}`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=view-report.js.map

package/dist/index.js

@@ -12,6 +12,7 @@ import codeCommand from './commands/code.js';
 import layoutCommand from './commands/layout.js';
 import syncDocsCommand from './commands/sync-docs.js';
 import translateCommand from './commands/translate.js';
+import viewReportCommand from './commands/view-report.js';
 config();
 program
     .name('butterfly-cli')
@@ -113,5 +114,12 @@ program
     .option('--format <format>', 'Output format: json or table (default: table)')
     .option('--limit <count>', 'Limit number of results')
     .action(translateCommand);
+program
+    .command('view-report')
+    .description('Run a report and display the rendered result')
+    .option('--id <id>', 'Report ID')
+    .option('--alias <alias>', 'Report alias')
+    .option('--raw', 'Output full HTML instead of plain text')
+    .action(viewReportCommand);
 program.parse();
 //# sourceMappingURL=index.js.map

package/docs/IMPLEMENTATION_PROMPT.md

@@ -0,0 +1,252 @@
+# Süreç Yönetimi Modülü - Implementation Prompt
+
+Bu prompt, çok tablolu bir form sistemi, onay akışı (state machine), e-posta bildirimleri, dashboard ve admin menü içeren eksiksiz bir süreç yönetimi modülünü sıfırdan oluşturmak için kullanılır.
+
+---
+
+## Prompt
+
+Aşağıdaki adımları sırasıyla uygula. Her adımda CLAUDE.md'deki kurallara uy. Proje gereksinim dokümanını referans al.
+
+### Faz 1: Object'leri Oluştur
+
+`butterfly-cli record add` ile gereksinim dokümanındaki object'leri ve field'larını oluştur.
+
+**Genel kurallar:**
+- Her object için tablo adı, field'lar ve field tipleri gereksinim dokümanında belirtilir
+- Parent-child ilişkilerinde child tablolarda parent'a `dropdown` tipinde referans field oluştur
+- **`status` alanı oluşturMA** — state machine `state` alanını yönetecek
+- Tarih formatı JS'den custom format gelecekse (`dd.mm.YYYY HH:mm` gibi), `datetime` DEĞİL `string` tipi kullan
+
+### Faz 2: State Machine (Onay Akışı)
+
+Gereksinim dokümanındaki onay akışına göre state machine oluştur.
+
+**Genel yapı:**
+- State'ler: Gereksinime göre tanımla (system_name + görünen ad)
+- Roller: Süreçteki rol gruplarını tanımla
+- Geçişler: From → To, buton adı ve yetkili rol
+
+**ÖNEMLİ:**
+- Transition role alanı `bfy_state_machine_role_ids` (çoğul), `bfy_state_machine_role_id` DEĞİL
+- Transition görünen ad alanı `button_title`, `name` DEĞİL
+
+**Ana object'e `state` tipi field ekle:** `val_1` = state machine ID
+
+### Faz 3: E-posta Şablonları
+
+**`cms_email_templates` nesnesine 2 yeni field ekle:**
+- `test_data` (textarea) — JSON format örnek veri
+- `preview` (calculated) — content + test_data'yı birleştirip önizleme gösteren alan
+
+**Preview calculated kodu:**
+- `test_data` JSON'ını parse et, varsayılan değerlerle birleştir
+- `|replace(replacements)` ile placeholderları değiştir (replace **mapping** alır, string DEĞİL)
+- Subject + body'yi rendered olarak göster
+
+**E-posta şablonlarını oluştur (`cms_email_templates`):**
+- Her state geçişi için uygun şablon tanımla (onay, red, bildirim vb.)
+- Alias formatı: `process-alias-action` (örn: `surec-onay-bekliyor`)
+
+**Şablon içeriği:** Inline CSS ile modern e-posta tasarımı. Değişkenler `{{ variable_name }}` formatında.
+
+**Her geçişin `action_code`'unda:**
+```twig
+{% set tpl = db().table('cms_email_templates').where('alias', 'ALIAS').first() %}
+{% set replacements = {} %}
+{% for key, val in vars %}
+  {% set replacements = replacements|merge({('{{ ' ~ key ~ ' }}'): val}) %}
+{% endfor %}
+{{ sendEmail(recipient, tpl.subject|replace(replacements), tpl.content|replace(replacements)) }}
+```
+
+### Faz 4: Custom Report — Detay Formu
+
+Report oluştur, tek query ile tam form HTML'i.
+
+**Kritik kurallar:**
+- `form_id` parametresi kullan (`id` RESERVED)
+- `currentUser('sicil_no')` ile çalışan bilgisi al (`app.user.username` YOK)
+- CSRF token JS ile al: `$('meta[name="csrf-token"]').attr('content')` (`csrf_token()` Twig fonksiyonu YOK)
+- Tailwind CSS CDN kullan
+- `rg_confirm()` / `rg_alert()` kullan (native alert/confirm DEĞİL)
+- Mevcut satırları Twig `{% for %}` ile DEĞİL, JS ile render et (window._data JSON'ından)
+- `state` alanını kontrol et (manual `status` DEĞİL)
+
+**Form bölümleri (gereksinime göre uyarla):**
+1. Header — tarih, referans no
+2. Talep eden bilgileri — employee/user tablosundan otomatik
+3. Form bilgileri — gereksinime özel alanlar
+4. Tekrarlanabilir satırlar (child records) — otomatik toplam, ondalık 2 basamak
+5. Ekler — dosya yükleme (varsa)
+6. Durum badge'i — `record.state` ile renk kodlu
+7. Aksiyon butonları — isDraft kontrolü ile koşullu
+
+**JS (script.js) mimarisi:**
+- `saveForm()` → Promise döner, requestId ile resolve olur
+- Add: Ana kayıt ekle → response.id al → child kayıtları ekle
+- Edit: Ana kayıt düzenle → mevcut child'ları sil (tek tek sequential `__delete`) → yeniden ekle
+- `triggerTransition(requestId, transitionId)` — state alanına JSON gönder
+- Save butonu: saveForm → redirect
+- Submit butonu: rg_confirm → saveForm → triggerTransition → redirect
+- Delete butonu: rg_confirm → child'ları sil → ana kaydı sil → dashboard'a redirect
+- **Read-only modu:** `isReadonly` flag ile tüm input'ları disable et, ekleme/silme butonlarını gizle
+
+### Faz 5: Dashboard
+
+İkinci report oluştur.
+
+**Bölümler:**
+1. **Taleplerim** — Giriş yapan kullanıcının tüm talepleri (taslak dahil), `state` alanına göre durum badge'leri
+2. **Onay Bekleyenler** — İlgili state'teki talepler
+3. **Yeni Talep** butonu → form report'una link
+
+**ÖNEMLİ:** Tüm durum filtreleri ve etiketleri `state` alanını kullanmalı (`status` DEĞİL).
+
+### Faz 6: Admin Menü
+
+**`cms_admin_menus` tablosunda Level 1 + Level 2 oluştur:**
+```
+Ana Menü (parent_id: 0)                     ← Level 1
+├── Alt Menü 1 (parent_id: main_menu_id)    ← Level 2
+├── Alt Menü 2                               ← Level 2
+└── Alt Menü 3                               ← Level 2
+```
+
+**Object'lere `main_menu_id` + `sub_menu_id` ata (Level 3):**
+- Her object'i uygun alt menüye bağla
+
+**3. seviye menü öğelerini `cms_admin_menus`'e ekleME** — object üzerinden `main_menu_id` + `sub_menu_id` ile yapılır.
+
+### Faz 7: Örnek Veri
+
+Test için örnek kayıtlar ekle (gereksinime göre).
+
+---
+
+## Sık Yapılan Hatalar (Bunları YAPMA)
+
+| Hata | Doğrusu |
+|------|---------|
+| `status: 'draft'` manual set etmek | State machine `state` alanını otomatik yönetir |
+| `record.status` kontrol etmek | `record.state` kullan (state machine system_name'leri) |
+| `csrf_token()` Twig'de kullanmak | JS'de `$('meta[name="csrf-token"]').attr('content')` |
+| `app.user.username` kullanmak | `currentUser('sicil_no')` |
+| `id` parametresi kullanmak | `form_id` kullan (`id` reserved) |
+| `alert()` / `confirm()` kullanmak | `rg_alert()` / `rg_confirm()` |
+| `bfy_state_machine_role_id` (tekil) | `bfy_state_machine_role_ids` (çoğul) |
+| Transition name alanı | `button_title` alanı kullan |
+| Custom format tarih datetime type | string type kullan (custom format dd.mm.YYYY HH:mm) |
+| `|replace('old', 'new')` string ile | `|replace({'old': 'new'})` mapping ile |
+| Child satırları Twig for loop ile render | JS'den render et (window._data JSON) |
+| Edit'te child'ları tekrar add etmek | Önce mevcut child'ları tek tek sil, sonra yeniden ekle |
+| `delete_where` endpoint kullanmak | Yok. Tek tek `__delete` ile sil (sequential promise chain) |
+| `butterfly-cli download -t cms_reports` | `-t reports` kullan |
+| 3. seviye menüyü cms_admin_menus'e eklemek | Object üzerinden main_menu_id + sub_menu_id ile yap |
+| jQuery UI'ı head'e koymak | jQuery yüklendikten sonra body sonuna koy |
+| PDF template'te `db().table()` kullanmak | `db('default', false).table()` kullan (permission bypass) |
+| Dosyayı doğrudan `cms_object/operation` ile yüklemek | Önce `file_helper/upload_file` ile yükle, sonra filename'i kaydet |
+| `file_upload` field input name'ini column adı yapmak | Input name mutlaka `file_upload` olmalı |
+| REST API kullanarak admin içi dosya yüklemek | Admin panel endpoint (`/admin/ajax/file_helper/upload_file`) kullan |
+| Fonksiyonları `$(document).ready()` içinde tanımlamak | Global scope'ta tanımla, sadece init kodu ready içinde olsun |
+| `employees` tablosu varsaymak | `currentUser('email')`, `currentUser('name')` kullan |
+
+---
+
+## Dosya Yükleme Entegrasyonu
+
+Custom report sayfalarında dosya yükleme **iki aşamalı** yapılır:
+
+### Adım 1: Dosyayı Yükle
+
+```javascript
+function uploadFile(file) {
+  return new Promise(function(resolve, reject) {
+    var fd = new FormData();
+    fd.append('file_upload', file);           // input name mutlaka 'file_upload'
+    fd.append('uuid', 'upload-' + Date.now());
+    fd.append('original_filename', file.name);
+    fd.append('total_file_size', file.size);
+
+    $.ajax({
+      url: '/admin/ajax/file_helper/upload_file?alias=import',  // alias URL param olarak
+      type: 'POST',
+      data: fd,
+      processData: false,
+      contentType: false,
+      headers: { 'X-Requested-With': 'XMLHttpRequest' },
+      success: function(response) {
+        if (response.success && response.filename) {
+          resolve(response.filename);
+        } else {
+          rg_alert(response.message || 'Dosya yüklenemedi.');
+          reject('Upload failed');
+        }
+      },
+      error: function() { reject('Upload error'); }
+    });
+  });
+}
+```
+
+### Adım 2: Kaydı filename ile oluştur
+
+```javascript
+var filename = await uploadFile(fileInput.files[0]);
+$.ajax({
+  url: '/admin/ajax/cms_object/operation?do=tablo__add',
+  type: 'POST',
+  data: { csrf_token: csrfToken, parent_id: parentId, dosya: filename }
+});
+```
+
+### Storage Alias Ayarları
+
+- Alias'lar `cms_file_uploads` tablosunda tanımlıdır
+- `extensions` alanı izin verilen uzantıları belirler (virgülle ayrılmış)
+- Object spec'teki `file_upload` field'ın `val_1` parametresi alias adını belirtir
+- Yeni uzantı eklemek: `butterfly-cli record edit cms_file_uploads --id <id> --data '{"extensions":"mevcut,yeni"}'`
+
+Detaylı dokümantasyon: [docs/butterfly_upload_api_docs-2.md](butterfly_upload_api_docs-2.md)
+
+---
+
+## JS Scope ve Mimari Kuralları
+
+### Fonksiyon Tanımlama
+
+Custom report sayfalarında **tüm fonksiyonlar global scope'ta** tanımlanmalı. `$(document).ready()` içinde sadece init kodu olmalı:
+
+```javascript
+// ✅ DOĞRU: Global scope'ta
+function calculateTotal() { /* ... */ }
+function addRow() { /* ... */ }
+function saveForm() { /* ... */ }
+
+$(document).ready(function() {
+  // Sadece init: değişken atamaları, ilk render, event listener'lar
+  var csrfToken = $('meta[name="csrf-token"]').attr('content');
+  renderExistingRows();
+});
+```
+
+```javascript
+// ❌ YANLIŞ: ready() içinde tanımlama
+$(document).ready(function() {
+  function calculateTotal() { /* ... */ }  // onclick'ten erişilemez!
+  window.calculateTotal = calculateTotal;  // race condition riski
+});
+```
+
+**Neden?** HTML `onclick` attributeleri global scope'taki fonksiyonları çağırır. `$(document).ready()` içindeki fonksiyonlar closure'da kalır ve erişilemez. `window.XXX =` ataması ise timing sorunlarına yol açabilir (fonksiyon henüz atanmadan çağrılabilir).
+
+### Tailwind CSS Select Reset Sorunu
+
+Tailwind CSS `select` elementlerinin görünümünü sıfırlar. Custom select'ler için:
+
+```css
+.form-select, .data-table select {
+  appearance: auto;
+  background-color: #fff;
+}
+```

package/docs/butterfly_upload_api_docs-2.md

@@ -0,0 +1,255 @@
+# Butterfly Dosya Yükleme Dokümantasyonu
+
+## Genel Bakış
+
+Butterfly DXP'de dosya yükleme iki yöntemle yapılabilir:
+
+1. **Admin Panel Endpoint (Önerilen)** — Session-based auth, custom report sayfalarında ve admin panelinde kullanılır
+2. **REST API Endpoint** — Token-based auth, harici sistemler ve mobil uygulamalar için
+
+---
+
+## Yöntem 1: Admin Panel File Helper (Önerilen)
+
+Custom report sayfaları veya admin panelindeki JavaScript kodlarından dosya yüklemek için bu yöntem kullanılır. Kullanıcı zaten admin paneline giriş yaptığı için ek authentication gerekmez.
+
+### Endpoint
+
+```
+POST /admin/ajax/file_helper/upload_file?alias=ALIAS
+```
+
+### Parametreler
+
+| Parametre | Tip | Zorunlu | Açıklama |
+|-----------|-----|---------|----------|
+| `file_upload` | File | Evet | Yüklenecek dosya (input name **mutlaka** `file_upload` olmalı) |
+| `uuid` | String | Evet | Benzersiz tanımlayıcı (örn: `upload-` + timestamp) |
+| `original_filename` | String | Evet | Orijinal dosya adı |
+| `total_file_size` | Number | Evet | Dosya boyutu (bytes) |
+| `alias` | String | Evet | Storage alias (URL query parameter olarak gönderilir) |
+
+### Storage Alias Yapılandırması
+
+Alias'lar `cms_file_uploads` tablosunda tanımlıdır. Her alias şunları kontrol eder:
+- İzin verilen dosya uzantıları (`extensions` alanı, virgülle ayrılmış)
+- Maksimum dosya boyutu
+- Depolama konumu
+
+**Alias yönetimi:** Admin panel → File Storage menüsü veya `cms_file_uploads` tablosu üzerinden.
+
+**Yaygın alias'lar:**
+- `content` — Genel içerik (görsel, medya)
+- `import` — İçe aktarma dosyaları (varsayılan: json, xlsx, xls; ihtiyaca göre genişletilebilir)
+
+**Yeni uzantı eklemek için:**
+```bash
+butterfly-cli record edit cms_file_uploads --id <alias_id> --data '{"extensions": "mevcut,yeni,uzantilar"}'
+```
+
+### JavaScript Örneği (Custom Report Sayfası)
+
+```javascript
+function uploadFile(file) {
+  return new Promise(function(resolve, reject) {
+    var fd = new FormData();
+    fd.append('file_upload', file);
+    fd.append('uuid', 'upload-' + Date.now());
+    fd.append('original_filename', file.name);
+    fd.append('total_file_size', file.size);
+
+    $.ajax({
+      url: '/admin/ajax/file_helper/upload_file?alias=import',
+      type: 'POST',
+      data: fd,
+      processData: false,
+      contentType: false,
+      headers: { 'X-Requested-With': 'XMLHttpRequest' },
+      success: function(response) {
+        if (response.success && response.filename) {
+          resolve(response.filename);
+        } else {
+          rg_alert(response.message || 'Dosya yüklenemedi.');
+          reject('Upload failed');
+        }
+      },
+      error: function() {
+        rg_alert('Dosya yükleme sırasında hata oluştu.');
+        reject('Upload error');
+      }
+    });
+  });
+}
+```
+
+### Yanıt Formatı
+
+**Başarılı:**
+```json
+{
+  "success": true,
+  "filename": "dosya_adi_islenmis.jpg",
+  "full_path": "/storage/path/dosya_adi_islenmis.jpg"
+}
+```
+
+**Hata:**
+```json
+{
+  "success": false,
+  "message": "Dosya tipi izin verilmiyor."
+}
+```
+
+### Dosya Kaydı ile Entegrasyon (İki Aşamalı)
+
+Dosya yükleme ve kayıt oluşturma iki ayrı adımda yapılır:
+
+```javascript
+// 1. Dosyayı yükle → filename al
+var filename = await uploadFile(file);
+
+// 2. Kaydı oluştur, filename'i veri olarak gönder
+$.ajax({
+  url: '/admin/ajax/cms_object/operation?do=tablo_adi__add',
+  type: 'POST',
+  data: {
+    csrf_token: csrfToken,
+    parent_id: parentId,
+    dosya: filename,        // file_upload field'ın column adı
+    aciklama: 'Açıklama'
+  }
+});
+```
+
+### Object Spec Yapılandırması
+
+`file_upload` tipindeki field'ın `val_1` parametresi alias adını belirtir:
+
+```json
+{
+  "type": "file_upload",
+  "val_1": "import"
+}
+```
+
+### Dosya Önizleme Linki Oluşturma
+
+Upload edilen dosyalar veritabanında sadece **relative path** olarak saklanır (örn: `26-03/08/dosya.png`). Tam URL oluşturmak için alias'ın `path` değeri gerekir.
+
+**Twig'de base path'i al:**
+```twig
+{% set importAlias = db().table('cms_file_uploads').where('alias', 'import').first() %}
+{% set importBasePath = importAlias ? importAlias.path : '/static/import/' %}
+```
+
+**JS'e aktar:**
+```html
+<script>
+window._data = {
+  importBasePath: '{{ importBasePath }}'
+};
+</script>
+```
+
+**JS'de tam URL oluştur:**
+```javascript
+var basePath = data.importBasePath || '/static/import/';
+var fullUrl = basePath + record.dosya;
+// Örnek: /static/import/26-03/08/dosya.png
+```
+
+**Path yapısı:**
+- `cms_file_storages.base_url` → Storage base URL (örn: `/static`)
+- `cms_file_uploads.path` → Alias path (örn: `/static/import/`)
+- Veritabanındaki `dosya` değeri → Relative path (örn: `26-03/08/dosya.png`)
+- **Tam URL** = `cms_file_uploads.path` + `dosya` değeri
+
+### Önemli Notlar
+
+- **Input name:** Mutlaka `file_upload` olmalı, field'ın column adı (örn: `dosya`) DEĞİL
+- **Authentication:** Admin session cookie'leri otomatik gönderilir, ek header gerekmez
+- **Alias zorunlu:** URL'de `?alias=ALIAS` belirtilmeli, yoksa hata verir
+- **Tek dosya:** Bu endpoint tek seferde bir dosya yükler, birden fazla dosya için döngü kullanın
+- **Dosya uzantısı kontrol:** Alias'ta tanımlı uzantılarla eşleşmeyen dosyalar reddedilir
+- **Dosya linki:** Veritabanında sadece relative path saklanır, görüntülemek için alias path'i ile birleştirin
+
+---
+
+## Yöntem 2: REST API (Harici Sistemler İçin)
+
+Harici uygulamalar, mobil uygulamalar veya otomatik süreçler için REST API kullanılır.
+
+### Ön Gereksinimler
+
+1. **API Erişimi:** Admin panelinde kullanıcı profilinde "API Access" aktif edilmeli
+2. **API Key:** `/admin/user_auth/list` sayfasından API key oluşturulmalı
+
+### Authentication
+
+```bash
+# Token oluştur
+curl -X POST /rest/auth/generateToken \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "api_key=YOUR_API_KEY&password=YOUR_PASSWORD"
+```
+
+**Yanıt:**
+```json
+{
+  "success": true,
+  "token": "session_token",
+  "expires_at": "2024-12-31 23:59:59"
+}
+```
+
+### Dosya Yükleme
+
+```bash
+curl -X POST /rest/upload/image \
+  -H "BUTTERFLY_API_KEY: api-key-here" \
+  -H "BUTTERFLY_ACCESS_TOKEN: access-token-here" \
+  -F "files[]=@/path/to/image.jpg" \
+  -F "alias=content" \
+  -F "sub_folder=gallery"
+```
+
+**Parametreler:**
+- `files[]` (file array, zorunlu): Yüklenecek dosyalar
+- `alias` (string, opsiyonel): Storage alias (varsayılan: 'content')
+- `sub_folder` (string, opsiyonel): Alt klasör
+
+**Yanıt:**
+```json
+{
+  "success": true,
+  "result": [
+    {
+      "full_path": "https://cdn.example.com/content/gallery/image.jpg",
+      "filename": "image.jpg",
+      "webp": "https://cdn.example.com/content/gallery/image.webp"
+    }
+  ]
+}
+```
+
+### REST API Hata Durumları
+
+| Hata | Açıklama |
+|------|----------|
+| `"invalid request"` | api_key veya password eksik |
+| `"invalid parameters"` | API key bulunamadı, API erişimi kapalı, yanlış şifre |
+| 401 Unauthorized | Geçersiz veya süresi dolmuş token |
+| 422 Unprocessable | Dosya tipi veya boyut sınırı aşıldı |
+
+---
+
+## Hangi Yöntemi Kullanmalı?
+
+| Senaryo | Yöntem |
+|---------|--------|
+| Custom report sayfasında dosya yükleme | Admin Panel (Yöntem 1) |
+| Object edit sayfasında file_upload field | Otomatik (Butterfly yönetir) |
+| Harici uygulama / mobil uygulama | REST API (Yöntem 2) |
+| Cron job / workflow / otomasyon | REST API (Yöntem 2) |
+| Admin paneli içi JavaScript | Admin Panel (Yöntem 1) |

package/docs/objects/listing-query.md

@@ -0,0 +1,78 @@
+# Object Listing Query
+
+Each object can have a `listing_query.bfy` file that customizes the listing page behavior and appearance.
+
+## File Location
+
+```
+butterfly-resources/objects/[butterfly|app]/[table_name]/listing_query.bfy
+```
+
+## Header Block
+
+Use the `{% block header %}` to display custom content at the top of the listing page, above the data table.
+
+### Basic Usage
+
+```twig
+{% block header %}
+  <div class="alert alert-info">
+    Custom content displayed at the top of the listing page
+  </div>
+{% endblock %}
+```
+
+### Example with Statistics
+
+```twig
+{% block header %}
+  {% set stats = db().table('orders').selectRaw('COUNT(*) as total, SUM(amount) as sum').first() %}
+  <div class="row mb-3">
+    <div class="col-md-4">
+      <div class="card">
+        <div class="card-body text-center">
+          <h5 class="card-title">Total Orders</h5>
+          <p class="display-6">{{ stats.total }}</p>
+        </div>
+      </div>
+    </div>
+    <div class="col-md-4">
+      <div class="card">
+        <div class="card-body text-center">
+          <h5 class="card-title">Total Amount</h5>
+          <p class="display-6">{{ stats.sum|number_format(2) }} TL</p>
+        </div>
+      </div>
+    </div>
+  </div>
+{% endblock %}
+```
+
+### Example with Filters
+
+```twig
+{% block header %}
+  <div class="card mb-3">
+    <div class="card-body">
+      <form method="get" class="row g-3">
+        <div class="col-md-3">
+          <label class="form-label">Status</label>
+          <select name="status" class="form-select">
+            <option value="">All</option>
+            <option value="active">Active</option>
+            <option value="inactive">Inactive</option>
+          </select>
+        </div>
+        <div class="col-md-3 d-flex align-items-end">
+          <button type="submit" class="btn btn-primary">Filter</button>
+        </div>
+      </form>
+    </div>
+  </div>
+{% endblock %}
+```
+
+## Related
+
+- [Objects Overview](./README.md)
+- [Creating Objects](./creating.md)

package/docs/pdf-generation.md

@@ -0,0 +1,376 @@
+# Butterfly PDF Oluşturma Dokümantasyonu
+
+## Genel Bakış
+
+Butterfly DXP, `pdf_templates` tablosundaki Twig şablonlarından PDF dosyaları oluşturmak için yerleşik bir PDF sistemi sunar. Sistem arka planda `https://pdf.butterfly.dev/get` adresindeki PDF sunucusunu kullanır.
+
+## Mimari
+
+```
+[İstek] → /pdf/create veya /pdf/view
+    → pdf_templates tablosundan şablon çek (system_name ile)
+    → Twig render (Input parametreleri değişken olarak geçer)
+    → HTML'i PDF sunucusuna gönder
+    → /create: PDF'i storage'a kaydet, dosya bilgisi dön
+    → /view: PDF'i tarayıcıda inline göster
+```
+
+## Endpoint'ler
+
+### 1. PDF Oluştur ve Kaydet (`/pdf/create`)
+
+PDF oluşturur, storage alias'a kaydeder, dosya bilgisi döner.
+
+**URL:** `POST /pdf/create`
+
+**Parametreler:**
+
+| Parametre | Tip | Zorunlu | Açıklama |
+|-----------|-----|---------|----------|
+| `template_name` | string | Evet | `pdf_templates.system_name` değeri |
+| `filename` | string | Hayır | Çıktı dosya adı (varsayılan: `document.pdf`) |
+| `alias` | string | Hayır | Storage alias (varsayılan: `pdf`) |
+| *diğer parametreler* | any | Hayır | Template'e değişken olarak geçer |
+
+**Başarılı Yanıt:**
+```json
+{
+  "success": true,
+  "full_path": "https://butterfly.rg/static/pdf/26-03/08/harcama-3.pdf",
+  "filename": "26-03/08/harcama-3.pdf"
+}
+```
+
+**Hata Yanıtları:**
+```json
+{"success": false, "message": "PDF tasarımı seçiniz."}
+{"success": false, "message": "PDF tasarımı bulunamadı."}
+{"success": false, "message": "Hata: ...twig render hatası..."}
+{"success": false, "message": "PDF oluşturulurken bir hata oluştu..."}
+```
+
+### 2. PDF Önizleme (`/pdf/view`)
+
+PDF oluşturur ve tarayıcıda inline gösterir (kaydetmez). Yazdır/önizleme için idealdir.
+
+**URL:** `GET /pdf/view`
+
+**Parametreler:** `/pdf/create` ile aynı. Ek olarak template'e `preview: true` değişkeni geçer.
+
+**Yanıt:** `Content-Type: application/pdf` ile doğrudan PDF binary.
+
+## pdf_templates Tablosu
+
+| Kolon | Açıklama |
+|-------|----------|
+| `system_name` | Şablonun benzersiz tanımlayıcısı (endpoint'ten `template_name` ile eşleşir) |
+| `name` | Şablon görünen adı |
+| `template` | Twig + HTML şablon içeriği |
+
+## Storage Alias Yapılandırması
+
+PDF dosyaları `cms_file_uploads` tablosundaki alias ayarına göre kaydedilir.
+
+**`pdf` alias yoksa oluştur:**
+```bash
+butterfly-cli record add cms_file_uploads --data '{
+  "alias": "pdf",
+  "path": "/static/pdf/",
+  "extensions": "pdf",
+  "cms_file_storage_id": 1
+}'
+```
+
+Kayıtlı PDF'lerin tam URL'i: `cms_file_uploads.path` + `response.filename`
+Örnek: `/static/pdf/` + `26-03/08/harcama-3.pdf` = `/static/pdf/26-03/08/harcama-3.pdf`
+
+## Şablon Yazma Kuralları
+
+### Permission Bypass (KRİTİK)
+
+`/pdf/create` ve `/pdf/view` endpoint'leri admin context dışında çalışır. Standart `db().table()` çağrıları permission hatası verir:
+
+```
+"You don't have permission to view TABLE_NAME object"
+```
+
+**Çözüm:** `db('default', false)` kullan — ikinci parametre `false` permission kontrolünü devre dışı bırakır.
+
+```twig
+{# ❌ YANLIŞ — permission hatası verir #}
+{% set r = db().table('tablo').where('id', id).first() %}
+
+{# ✅ DOĞRU — permission bypass #}
+{% set r = db('default', false).table('tablo').where('id', id).first() %}
+```
+
+> **Not:** Bu sadece PDF template'lerinde kullanılmalıdır. Normal report/object kodlarında standart `db()` kullanmaya devam edin.
+
+### Değişken Erişimi
+
+Template'e gönderilen tüm parametreler doğrudan Twig değişkeni olarak erişilebilir:
+
+```
+POST /pdf/create?template_name=sablonAdi&id=5&extra_param=deger
+```
+
+Template içinde:
+```twig
+{{ id }}          {# 5 #}
+{{ extra_param }} {# deger #}
+```
+
+### Inline CSS Zorunluluğu
+
+PDF sunucusu harici CSS dosyalarını yüklemez. **Tüm stiller `<style>` etiketi içinde veya inline olmalıdır.**
+
+```html
+{# ❌ YANLIŞ — PDF'te çalışmaz #}
+<link href="https://cdn.jsdelivr.net/npm/tailwindcss..." rel="stylesheet">
+
+{# ✅ DOĞRU #}
+<style>
+  body { font-family: Arial, sans-serif; font-size: 12px; }
+  .section { background: #f3f4f6; padding: 6px 12px; font-weight: 700; }
+  table { width: 100%; border-collapse: collapse; }
+</style>
+```
+
+### Temel Şablon Yapısı
+
+```html
+<html>
+<head>
+  <meta charset="utf-8">
+  <style>
+    body { font-family: Arial, sans-serif; font-size: 12px; color: #333; margin: 20px 40px; }
+    h1 { font-size: 18px; text-align: center; }
+    .section { background: #f3f4f6; padding: 6px 12px; font-weight: 700; font-size: 13px;
+               border-left: 4px solid #ef4444; margin: 14px 0 8px; }
+    table { width: 100%; border-collapse: collapse; margin-bottom: 10px; }
+    .info-table td { padding: 4px 8px; font-size: 12px; }
+    .info-table .lbl { font-weight: 600; width: 140px; color: #555; }
+    .data-table th { background: #f3f4f6; padding: 6px 8px; text-align: left; font-size: 11px;
+                     font-weight: 700; border: 1px solid #d1d5db; }
+    .data-table td { padding: 5px 8px; border: 1px solid #d1d5db; font-size: 11px; }
+    .footer { margin-top: 20px; border-top: 1px solid #d1d5db; padding-top: 8px;
+              font-size: 10px; color: #999; text-align: center; }
+  </style>
+</head>
+<body>
+  {% set r = db('default', false).table('ana_tablo').where('id', id).first() %}
+  {% if r is empty %}
+    <p>Kayıt bulunamadı.</p>
+  {% else %}
+    {% set children = db('default', false).table('child_tablo').where('parent_id', id).get() %}
+
+    <h1>BAŞLIK</h1>
+
+    <div class="section">Bilgiler</div>
+    <table class="info-table">
+      <tr><td class="lbl">Alan Adı</td><td>{{ r.alan_adi }}</td></tr>
+    </table>
+
+    {% if children|length > 0 %}
+      <div class="section">Alt Kayıtlar</div>
+      <table class="data-table">
+        <tr><th>Kolon 1</th><th>Kolon 2</th></tr>
+        {% for c in children %}
+          <tr><td>{{ c.kolon1 }}</td><td>{{ c.kolon2 }}</td></tr>
+        {% endfor %}
+      </table>
+    {% endif %}
+
+    <div class="footer">Bu belge sistem tarafından otomatik oluşturulmuştur.</div>
+  {% endif %}
+</body>
+</html>
+```
+
+## Entegrasyon Örnekleri
+
+### Custom Report Sayfasından Yazdır Butonu
+
+**HTML (query_code.bfy):**
+```html
+{% if isEdit %}
+  <button onclick="printPdf()">
+    <i class="fas fa-print mr-1"></i> Yazdır
+  </button>
+{% endif %}
+```
+
+**JS (script.js):**
+```javascript
+function printPdf() {
+  if (!data.isEdit || !data.recordId) {
+    rg_alert('Lütfen önce formu kaydediniz.');
+    return;
+  }
+  window.open('/pdf/view?template_name=SABLON_ADI&id=' + data.recordId
+    + '&filename=dosya-' + data.recordId + '.pdf', '_blank');
+}
+```
+
+### PDF Oluştur ve Kayda Yaz
+
+Formu göndermeden önce PDF oluşturup dosya yolunu ana kayda yazmak için:
+
+```javascript
+function createPdf(recordId) {
+  return new Promise(function(resolve, reject) {
+    $.ajax({
+      url: '/pdf/create',
+      type: 'POST',
+      data: {
+        template_name: 'SABLON_ADI',
+        id: recordId,
+        filename: 'dosya-' + recordId + '.pdf',
+        alias: 'pdf'
+      },
+      headers: { 'X-Requested-With': 'XMLHttpRequest' },
+      success: function(response) {
+        if (response.success && response.filename) {
+          var pdfPath = response.full_path || '/static/pdf/' + response.filename;
+          // PDF yolunu ana kayda yaz
+          $.ajax({
+            url: '/admin/ajax/cms_object/operation?do=TABLO__edit',
+            type: 'POST',
+            data: { csrf_token: csrfToken, id: recordId, pdf_dosya: pdfPath },
+            headers: { 'X-Requested-With': 'XMLHttpRequest' },
+            success: function() { resolve(pdfPath); },
+            error: function() { resolve(pdfPath); }
+          });
+        } else {
+          rg_alert(response.message || 'PDF oluşturulamadı.');
+          reject('PDF failed');
+        }
+      },
+      error: function() {
+        rg_alert('PDF oluşturma sırasında hata oluştu.');
+        reject('PDF error');
+      }
+    });
+  });
+}
+```
+
+### State Machine Transition ile PDF Link'ini E-postaya Ekle
+
+PDF dosyası JS tarafında oluşturulup `pdf_dosya` field'ına yazıldıktan sonra, transition action_code'unda bu değer okunabilir:
+
+```twig
+{# action_code.bfy #}
+{% set tpl = db().table('cms_email_templates').where('alias', 'template-alias').first() %}
+{% set pdfDosya = getValue('pdf_dosya') %}
+{% set vars = {
+  'talep_no': getValue('talep_no'),
+  'ad_soyad': getValue('ad_soyad'),
+  'pdf_link': pdfDosya
+    ? '<p><strong>PDF Doküman:</strong> <a href="' ~ pdfDosya ~ '" style="color:#3b82f6;">Formu İndir</a></p>'
+    : ''
+} %}
+{% set replacements = {} %}
+{% for key, val in vars %}
+  {% set replacements = replacements|merge({('{{ ' ~ key ~ ' }}'): val}) %}
+{% endfor %}
+{{ sendEmail(recipient, tpl.subject|replace(replacements), tpl.content|replace(replacements)) }}
+```
+
+E-posta template'ine `{{ pdf_link }}` placeholder'ı eklemeyi unutmayın.
+
+### Tipik Akış (Kaydet → PDF → Gönder)
+
+```javascript
+function submitForm() {
+  rg_confirm('Göndermek istediğinize emin misiniz?', function() {
+    saveForm().then(function(recordId) {           // 1. Formu kaydet
+      return createPdf(recordId).then(function() { // 2. PDF oluştur + kayda yaz
+        return triggerTransition(recordId, transitionId); // 3. Transition tetikle
+      });
+    }).then(function() {
+      window.location.href = '/admin/cms_report/view/DASHBOARD_ID';
+    });
+  });
+}
+```
+
+## Sıfırdan PDF Entegrasyonu Adımları
+
+### 1. Storage Alias Oluştur (bir kez)
+
+```bash
+butterfly-cli record add cms_file_uploads --data '{
+  "alias": "pdf",
+  "path": "/static/pdf/",
+  "extensions": "pdf",
+  "cms_file_storage_id": 1
+}'
+```
+
+### 2. pdf_templates Objesi Oluştur (bir kez)
+
+Eğer `pdf_templates` objesi yoksa:
+
+```bash
+# Object
+butterfly-cli record add objects --data '{
+  "table_name": "pdf_templates",
+  "name": "PDF Şablonları",
+  "has_item": 0,
+  "auto_increment_column_name": "id"
+}'
+# Object ID'yi not al, aşağıda OBJECT_ID olarak kullan
+
+# Field'lar
+butterfly-cli record add object_specs --data '{"object_id":OBJECT_ID,"name":"System Name","column_name":"system_name","type":"string","required":1,"list_column":1,"edit_order_no":1}'
+butterfly-cli record add object_specs --data '{"object_id":OBJECT_ID,"name":"Şablon Adı","column_name":"name","type":"string","required":1,"list_column":1,"edit_order_no":2}'
+butterfly-cli record add object_specs --data '{"object_id":OBJECT_ID,"name":"HTML Şablon","column_name":"template","type":"code","edit_order_no":3}'
+```
+
+### 3. Şablon Kaydı Ekle
+
+```bash
+butterfly-cli record add pdf_templates --data '{
+  "system_name": "sablonun-adi",
+  "name": "Şablonun Görünen Adı",
+  "template": "<html>...şablon HTML...</html>"
+}'
+```
+
+### 4. Ana Tabloya `pdf_dosya` Field Ekle (opsiyonel)
+
+PDF dosya yolunu kayıtta saklamak istiyorsan:
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": ANA_OBJECT_ID,
+  "name": "PDF Dosya",
+  "column_name": "pdf_dosya",
+  "type": "string",
+  "edit_order_no": 99
+}'
+```
+
+### 5. JS Fonksiyonlarını Ekle
+
+`printPdf()` ve `createPdf()` fonksiyonlarını script.js'e ekle (yukarıdaki örneklere bakın).
+
+### 6. Yazdır Butonunu Forma Ekle
+
+```html
+{% if isEdit %}
+  <button onclick="printPdf()"><i class="fas fa-print mr-1"></i> Yazdır</button>
+{% endif %}
+```
+
+## Sık Karşılaşılan Hatalar
+
+| Hata | Neden | Çözüm |
+|------|-------|-------|
+| `"PDF tasarımı bulunamadı."` | `template_name` ile eşleşen `system_name` yok | `pdf_templates` tablosunu kontrol et |
+| `"You don't have permission to view X object"` | Template'te `db()` kullanılmış | `db('default', false)` kullan |
+| PDF oluştu ama değerler boş | Template'e parametre geçilmemiş veya `db()` sorgusu hatalı | `id` parametresinin gönderildiğini ve sorgunun doğru olduğunu kontrol et |
+| PDF sunucu hatası (HTTP != 200) | HTML geçersiz veya PDF sunucusu erişilemiyor | HTML'i `/pdf/view` ile test et, hata mesajını incele |
+| Stiller PDF'te görünmüyor | Harici CSS kullanılmış | Tüm stilleri `<style>` etiketi içine al, inline CSS kullan |
+| `"Sayfa Bulunamadı"` | `/admin/pdf/create` veya `/admin/ajax/pdf/create` kullanılmış | Doğru URL: `/pdf/create` (admin prefix'siz) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rglabs/butterfly",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "CLI tool to download resources from the Butterfly platform",
   "type": "module",
   "main": "dist/index.js",