🤖 ArtFlow Table - AI Usage Guide (Non-Technical)

For AI Agents: Simple, practical guide to using ArtFlow Table in Blade views

⚡ Quick Summary for AI

The ArtFlow Table is a Livewire datatable component that displays data with automatic:

Sorting
Searching
Pagination
Eager loading (no N+1 queries)
Count aggregations

Version: 1.6.0 | Site: https://artflow.pk

Use it in Blade views with: [@livewire](https://github.com/livewire)('aftable', [...])

🎯 Basic Usage Pattern

Minimal Example

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Item',
    'columns' => [
        ['key' => 'title', 'label' => 'Item Name'],
        ['key' => 'code', 'label' => 'Code'],
        ['key' => 'amount', 'label' => 'Amount'],
    ],
])

What This Does

Fetches all items from database
Shows them in a table with pagination
Allows clicking column headers to sort
Allows searching in the search box
Everything is automatic! ✨

🔧 Common Configuration Options

Model & Data

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Item',             # Your Eloquent model
    'records' => 25,                          # Items per page (default: 50)
    'customQuery' => $query,                  # Optional: custom query builder
    'data' => $collection,                    # Optional: pre-fetched data
])

Columns Configuration

Simple Column (Automatic Everything!)

['key' => 'title', 'label' => 'Item Name']

Sorting: ✅ Enabled
Searching: ✅ Enabled (text only)
Eager loading: ✅ Enabled

Relationship Column (Shows Related Data)

['key' => 'category_name', 'label' => 'Category', 'relation' => 'category:name']

Fetches category.name for each item
Auto eager loads (no N+1!)
Fully sortable and searchable

Count Column (Shows Count of Related Items)

['key' => 'subitems_count', 'label' => 'Sub-items']

Uses Subitem relationship auto-detected from model
Shows count of sub-items per item
Must match relation name + _count
Example: If model has subitems() relation, use subitems_count

Hidden Column (Not Displayed, But Sortable)

['key' => 'id', 'hidden' => true]

Column exists for data but not shown
Can still sort by it if needed

Raw/HTML Column

['key' => 'actions', 'raw' => '<button onclick="...">Edit</button>']

Display custom HTML (buttons, links, etc.)
Use carefully - HTML is not escaped

Column with Custom Formatter

[
    'key' => 'price',
    'label' => 'Price',
    'value_type' => 'price'  # Formats as $X,XXX.XX
]

🎨 Styling & Display

Set Custom CSS Classes

[@livewire](https://github.com/livewire)('aftable', [
    'tableClass' => 'w-full border-collapse',
    'theadClass' => 'bg-gray-100',
    'rowClass' => 'hover:bg-gray-50',
])

Show/Hide Elements

[@livewire](https://github.com/livewire)('aftable', [
    'showPagination' => true,        # Show pagination controls
    'showSearch' => true,            # Show search box
    'showColumnVisibility' => true,  # Show column toggle
    'showExport' => true,            # Show export button
])

🔍 Filtering & Searching

Search Box

[@livewire](https://github.com/livewire)('aftable', [
    'searchable' => true,  # Enable search (default: true)
])

User types in search box
Automatically searches text columns
Automatically searches relationship columns (if configured with relation)

Multiple Columns Example

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Item',
    'columns' => [
        ['key' => 'title', 'label' => 'Title'],
        ['key' => 'description', 'label' => 'Description'],
        ['key' => 'category_name', 'label' => 'Category', 'relation' => 'category:name'],
        ['key' => 'department_name', 'label' => 'Department', 'relation' => 'department:name'],
    ],
])

Search searches ALL these columns
Includes relationship columns
All automatic!

🔗 Working with Relationships

Eager Load Related Data (No N+1!)

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Item',
    'columns' => [
        ['key' => 'title', 'label' => 'Title'],
        ['key' => 'category_name', 'label' => 'Category', 'relation' => 'category:name'],
        ['key' => 'department_name', 'label' => 'Department', 'relation' => 'department:name'],
        ['key' => 'supplier_name', 'label' => 'Supplier', 'relation' => 'supplier:name'],
    ],
])

What Happens:

System detects 3 relationships
Auto eager loads all 3 (single query!)
No N+1 problem - shows 100+ items with 1 query

Relationship Format: 'relation' => 'relationName:columnName'

relationName = method name on model (e.g., category())
columnName = column to display (e.g., name)

Count Aggregations (Show Related Count)

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Item',
    'columns' => [
        ['key' => 'title', 'label' => 'Title'],
        ['key' => 'subitems_count', 'label' => 'Sub-items'],
        ['key' => 'related_count', 'label' => 'Related Items'],
        ['key' => 'attachments_count', 'label' => 'Attachments'],
    ],
])

What Happens:

System detects _count suffix
Extracts relation name: subitems, related, attachments
Auto adds withCount() to query
Shows count without loading all related items
Single query! No N+1!

Rules:

Column key must be: relationName_count
Model must have the relationship defined
Example: Model has subitems() → use subitems_count

💾 Actions (Buttons)

Simple Button Action

[
    'key' => 'actions',
    'label' => 'Actions',
    'actions' => [
        [
            'type' => 'button',
            'label' => 'Edit',
            'href' => '/items/{id}/edit',
            'class' => 'btn btn-primary btn-sm',
        ],
        [
            'type' => 'button',
            'label' => 'Delete',
            'href' => '/items/{id}',
            'method' => 'DELETE',
            'confirm' => 'Are you sure?',
            'class' => 'btn btn-danger btn-sm',
        ],
    ]
]

Toggle Action

[
    'type' => 'toggle',
    'label' => 'Active',
    'href' => '/items/{id}/toggle-active',
    'method' => 'POST',
    'activeExpression' => 'is_active === true',
    'activeClass' => 'bg-green-500',
    'inactiveClass' => 'bg-red-500',
]

Raw HTML Action (Custom)

[
    'type' => 'raw',
    'content' => '<span class="badge">{{ status }}</span>',
]

📊 Export Data

Enable Export

[@livewire](https://github.com/livewire)('aftable', [
    'showExport' => true,
    'exportFormats' => ['csv', 'excel', 'pdf'],
])

Export Formats

CSV - Plain text, opens in Excel
Excel - Formatted spreadsheet
PDF - Printable document

User clicks Export button → Downloads file → Done!

🎮 Advanced Examples

Items Inventory Table

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Item',
    'records' => 50,
    'columns' => [
        ['key' => 'id', 'label' => 'ID', 'hidden' => true],
        ['key' => 'title', 'label' => 'Item Name'],
        ['key' => 'code', 'label' => 'Code'],
        ['key' => 'category_name', 'label' => 'Category', 'relation' => 'category:name'],
        ['key' => 'supplier_name', 'label' => 'Supplier', 'relation' => 'supplier:name'],
        ['key' => 'amount', 'label' => 'Amount', 'value_type' => 'price'],
        ['key' => 'subitems_count', 'label' => 'Sub-items'],
        ['key' => 'quantity', 'label' => 'Quantity'],
        [
            'key' => 'actions',
            'label' => 'Actions',
            'actions' => [
                ['type' => 'button', 'label' => 'Edit', 'href' => '/items/{id}/edit', 'class' => 'btn btn-sm'],
                ['type' => 'button', 'label' => 'Delete', 'href' => '/items/{id}', 'method' => 'DELETE', 'confirm' => 'Sure?'],
            ]
        ],
    ],
])

User Management Table

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\User',
    'records' => 25,
    'columns' => [
        ['key' => 'name', 'label' => 'Name'],
        ['key' => 'email', 'label' => 'Email'],
        ['key' => 'department_name', 'label' => 'Department', 'relation' => 'department:name'],
        ['key' => 'organization_name', 'label' => 'Organization', 'relation' => 'organization:name'],
        ['key' => 'is_active', 'label' => 'Status', 'value_type' => 'boolean'],
        ['key' => 'created_at', 'label' => 'Joined', 'value_type' => 'date'],
        [
            'key' => 'actions',
            'label' => '',
            'actions' => [
                ['type' => 'toggle', 'label' => 'Active', 'href' => '/users/{id}/toggle', 'method' => 'POST', 'activeExpression' => 'is_active === true'],
            ]
        ],
    ],
])

❓ Troubleshooting

"Component not found" Error

Problem: [@livewire](https://github.com/livewire)('aftable', [...] doesn't work Solution: Make sure package is installed: composer require artflow-studio/table

Sorting Doesn't Work

Problem: Column headers not sortable Solution: Ensure column is a database field (not a formula). Sorting only works on actual database columns.

Search Doesn't Find Anything

Problem: Search returns no results Solution: Make sure you're searching text columns. Numbers, dates, and boolean fields won't search.

N+1 Query Problem (Slow Page)

Problem: Slow loading, many queries in DevTools Solution: Use 'relation' for related data (e.g., 'relation' => 'category:name')

Related Data Shows "null"

Problem: Relationship column shows blank/null Solution:

Ensure relation name is correct (e.g., category() method exists on model)
Ensure column name exists (e.g., category.name exists)
Use format: 'relation' => 'category:name'

Count Shows 0 or Wrong Value

Problem: Counts wrong Solution:

Use correct column name with _count suffix
Column must match relationship name
Example: If model has variants() relation, column must be variants_count

💡 Best Practices

✅ DO

Use 'relation' => 'relationName:columnName' for related data
Use columnName_count for relationship counts
Keep column keys simple (no spaces, use snake_case)
Use 'hidden' => true for ID columns you don't need to show
Test on sample data first

❌ DON'T

Don't use complex formulas in 'key' (must be database fields)
Don't mix manual sorting config with auto-sort (system handles it)
Don't use 'raw' HTML unless you control the content (XSS risk)
Don't put component logic in Blade (only configuration)
Don't overload with 50+ columns (keep it to 10-15)

🔄 Real-World Workflow for AI

When an AI needs to use ArtFlow Table:

Identify the Model
- What Eloquent model? (e.g., Product, User)
List Needed Fields
- What fields to display? (e.g., name, email)
Identify Relationships
- What related data? (e.g., category, brand)
- Format: 'relation' => 'relationName:columnName'
Check for Counts
- Any relationship counts? (e.g., variants, reviews)
- Format: columnName_count (e.g., variants_count)
Add Actions
- Any buttons? (edit, delete, toggle)
- Format: Simple button config

Render in Blade

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\YourModel',
    'columns' => [...all columns...],
])

📞 Common Questions

Q: Can I use this in a Livewire component? A: No, only in Blade views. The component IS the Livewire component.

Q: How many records can it handle? A: Tested with 1M+ records. Pagination keeps it fast.

Q: Can I customize the appearance? A: Yes, use Tailwind CSS classes. See "Styling" section.

Q: Is it real-time? A: Yes! Livewire makes it reactive. Changes update instantly.

Q: Can I add custom filters? A: Yes, advanced filters available. See advanced guide.

Q: How do I handle soft deletes? A: Use withTrashed() or onlyTrashed() in custom query.

🚀 Next Steps

Copy a working example from "Advanced Examples" section
Replace model name with your Eloquent model
Add your columns (start simple)
Test in browser - should work immediately
Add more columns as needed
Customize styling with CSS classes

That's it! You now have a fully-featured datatable with sorting, searching, pagination, and more!

Version: 1.6.0
Last Updated: July 2025
For: AI Agents & Developers
Status: Production Ready ✅

🆕 v1.6.0 New Features

Static / Foreach Mode

Pass any PHP array or Laravel Collection — no Eloquent model needed:

[@php](https://github.com/php)
$employees = [
    ['name' => 'Alice', 'dept' => 'Engineering', 'salary' => 5000],
    ['name' => 'Bob',   'dept' => 'Design',      'salary' => 4500],
];
[@endphp](https://github.com/endphp)

[@livewire](https://github.com/livewire)('aftable', [
    'data'    => $employees,
    'vars'    => ['currency' => 'USD'],
    'columns' => [
        ['key' => 'name',   'label' => 'Name'],
        ['key' => 'dept',   'label' => 'Department'],
        ['key' => 'salary', 'label' => 'Salary',
         'raw' => '{{ $currency }} {{ number_format($row->salary, 2) }}'],
    ],
])

Closure / Callable Raw Columns (faster — no Blade overhead)

[@livewire](https://github.com/livewire)('aftable', [
    'model'   => App\Models\User::class,
    'vars'    => ['currency' => 'USD'],
    'columns' => [
        ['key' => 'name', 'label' => 'Name'],
        // Closure receives ($row, $vars)
        ['key' => 'status', 'label' => 'Status',
         'raw' => fn($row) => $row->active
             ? '<span class="badge bg-success">Active</span>'
             : '<span class="badge bg-danger">Inactive</span>'],
        ['key' => 'salary', 'label' => 'Salary',
         'raw' => fn($row, $vars) => e($vars['currency']).' '.number_format($row->salary, 2)],
    ],
])

Custom Table Template — `[@aftable](https://github.com/aftable)` / `[@endaftable](https://github.com/endaftable)`

Wrap your own <table> markup to apply your app's theme to the table:

[@aftable](https://github.com/aftable)(['model' => App\Models\User::class, 'columns' => [
    ['key' => 'name',  'label' => 'Name'],
    ['key' => 'email', 'label' => 'Email'],
]])
    <table class="table table-hover table-striped my-theme">
        <thead class="bg-dark text-white"><tr></tr></thead>
        <tbody></tbody>
    </table>
[@endaftable](https://github.com/endaftable)

Or pass it directly:

[@livewire](https://github.com/livewire)('aftable', [
    'model'          => App\Models\User::class,
    'columns'        => [...],
    'customTemplate' => '<table class="table table-hover my-theme" id="myTable">',
])

`classCondition` — no `eval()` (security fix)

'classCondition' => [
    // Closure — most flexible
    'text-success fw-bold' => fn($row) => $row->active,
    // String shorthand — truthy check on field
    'border-primary'       => 'featured',
    // Negation shorthand — !$row->active
    'text-muted'           => '!active',
    // Equality shorthand — $row->status === 'inactive'
    'text-danger'          => 'status:inactive',
],

Table Laravel Package