Flowforge Documentation

Flowforge is a tool designed to transform any Laravel model into a production-ready, drag-and-drop Kanban board. It is built to work seamlessly within Filament admin panels or as standalone Livewire components.

Key capabilities include:

• Enterprise-Scale Performance: Uses cursor-based pagination to handle unlimited cards per column with optimized position-based ordering.
• Flexible Integration: Supports three patterns: Filament Pages, Resource integration, or standalone Livewire components.
• Rich Card Schemas: Leverages the Filament Schema builder to create complex card layouts containing forms, components, and dynamic content.
• Smart Position Management: Features an advanced ranking algorithm for drag-and-drop ordering with automatic conflict resolution and repair commands.
• Optimistic UI: Provides instant visual feedback, loading states, and smooth scrolling for a responsive user experience.
• Native Filament Integration: Deeply integrates with Filament's table system for filters, search, and actions.

To add a Kanban view to an existing Filament resource (e.g., viewing tasks within a specific Campaign), extend BoardResourcePage.

1. Set the $resource property to your target resource class.
2. Use $this->getRecord() within the board() method to scope the query to the specific resource instance.
3. Register the new page in the resource's getPages() method.

namespace App\Filament\Resources\CampaignResource\Pages;

use App\Filament\Resources\CampaignResource;
use Relaticle\Flowforge\Board;
use Relaticle\Flowforge\BoardResourcePage;
use Relaticle\Flowforge\Column;

class CampaignTaskBoard extends BoardResourcePage
{
    protected static string $resource = CampaignResource::class;
    
    public function board(Board $board): Board
    {
        return $board
            ->query(
                $this->getRecord()
                    ->tasks()
                    ->whereHas('team', fn($q) => $q->where('id', auth()->user()->current_team_id))
                    ->getQuery()
            )
            ->columnIdentifier('status')
            ->positionIdentifier('position')
            ->columns([
                Column::make('backlog')->label('Backlog')->color('gray'),
                Column::make('in_progress')->label('In Progress')->color('blue'),
                Column::make('review')->label('Review')->color('amber'),
                Column::make('completed')->label('Completed')->color('green'),
            ]);
    }
}

// In CampaignResource.php
public static function getPages(): array
{
    return [
        'index' => Pages\ListCampaigns::route('/'),
        'create' => Pages\CreateCampaign::route('/create'),
        'edit' => Pages\EditCampaign::route('/{record}/edit'),
        'tasks' => Pages\CampaignTaskBoard::route('/{record}/tasks'),
    ];
}

To prevent losing the current order of items when migrating from string-based positions (v2.x) to decimal-based positions (v3.x), follow this pattern in a Laravel migration:

1. Add a temporary decimal column (e.g., position_new).
2. Iterate through distinct status groups.
3. For each group, order by the original position column and calculate new decimal positions using DecimalPosition::forEmptyColumn() and DecimalPosition::after($lastPosition).
4. Update the temporary column with these values.
5. Drop the old position column and rename position_new to position.
6. Add a unique constraint on ['status', 'position'].

// Example logic for preserving order
foreach ($statuses as $status) {
    $tasks = DB::table('tasks')
        ->where('status', $status)
        ->orderBy('position')
        ->get();

    $lastPosition = null;
    foreach ($tasks as $task) {
        $newPosition = $lastPosition === null
            ? DecimalPosition::forEmptyColumn()
            : DecimalPosition::after($lastPosition);

        DB::table('tasks')
            ->where('id', $task->id)
            ->update(['position_new' => $newPosition]);

        $lastPosition = $newPosition;
    }
}

Use the BoardPage class to create a dedicated Kanban page within your Filament admin panel. This provides full Filament integration, automatic registration, and built-in actions.

namespace App\Filament\Pages;

use App\Models\Task;
use Relaticle\Flowforge\Board;
use Relaticle\Flowforge\BoardPage;
use Relaticle\Flowforge\Column;

class TaskBoard extends BoardPage
{
    protected static ?string $navigationIcon = 'heroicon-o-view-columns';
    
    public function board(Board $board): Board
    {
        return $board
            ->query(Task::query())
            ->columnIdentifier('status')
            ->positionIdentifier('position')
            ->columns([
                Column::make('todo')->label('To Do')->color('gray'),
                Column::make('in_progress')->label('In Progress')->color('blue'),
                Column::make('completed')->label('Completed')->color('green'),
            ]);
    }
}

Upgrading from v2.x to v3.x involves moving from Lexorank/string-based positions to DecimalPosition/DECIMAL-based positions.

Breaking Changes

• PHP Extension: ext-bcmath is now required.
• Database Schema: The position column type changes from VARCHAR to DECIMAL(20,10).
• Service Replacement: The Rank service is replaced by DecimalPosition.
• Laravel Requirement: Requires Laravel 12+.

Migration Workflow

1. Verify BCMath: Ensure ext-bcmath is installed via php -m | grep bcmath.
2. Update Dependencies: Run composer require relaticle/flowforge:^3.0.
3. Update Database: Create a migration to change the position column type. You can either drop and recreate the column (losing order) or use a custom migration to preserve existing order.
4. Regenerate Positions: Run php artisan flowforge:repair-positions and select the "regenerate" strategy.
5. Update Code: Replace all Relaticle\Flowforge\Services\Rank references with Relaticle\Flowforge\Services\DecimalPosition and update method calls (see API changes).