README

Flowforge is a powerful Kanban board package for Laravel Filament 3 that works seamlessly with your existing Eloquent models. This package allows you to transform any model into a Kanban board with minimal configuration, without requiring additional database tables.

📋 Table of Contents

🛠️ Requirements
🔥 Quick Start
🌟 Features
🏗️ Model Preparation
✅ Required Configuration
🔄 Optional Methods
🧩 Optional Configuration
❓ Troubleshooting
👨‍💻 Contributing
📃 License

🛠️ Requirements

PHP 8.3+
Laravel 11+
Filament 3.x

🔥 Quick Start

This guide will help you set up a Kanban board for your Laravel application in just a few minutes.

Step 1: Install Flowforge

composer require relaticle/flowforge

Step 2: Prepare Your Model

For a basic Kanban board, your model needs:

A title field (e.g., title or name)
A status field to determine column placement (e.g., status or state)
An order field for drag & drop (e.g., order_column) - required for drag & drop functionality

Example migration:

Schema::create('tasks', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('description')->nullable();
    $table->string('status')->default('todo');
    $table->integer('order_column')->nullable();
    $table->timestamps();
});

Step 3: Generate a Minimal Kanban Board

Use the provided command to create a basic board:

php artisan flowforge:make-board TasksBoard --model=Task

The command will only ask for:

Board name (if not provided as argument)
Model name (if not provided with --model flag)

This command will:

Create a minimal read-only Kanban board page for your model
Set up default columns (todo, in_progress, completed)
Generate clean, concise code with no unnecessary comments

Step 4: Register the Page

Add your new page to Filament's navigation:

// In app/Providers/Filament/AdminPanelProvider.php

public function panel(Panel $panel): Panel
{
    return $panel
        // ... other configuration
        ->pages([
            // ... other pages
            App\Filament\Pages\TasksBoardPage::class,
        ]);
}

Step 5: Visit Your Board

Go to your Filament admin panel and you should see your new Kanban board in the navigation!

The generated board is intentionally minimal - it gives you a working read-only board to start with. When you're ready to add interactive features, you can manually add the createAction() and editAction() methods following the examples in the Optional Methods section.

🌟 Features

Flowforge offers several powerful features out of the box:

Model Agnostic: Works with any existing Eloquent model
No Additional Tables: Uses your existing models and database structure
Read-Only Option: Create simple view-only boards with minimal code
Drag and Drop: Move cards between columns or reorder them within a column
Optional Create/Edit: Add card creation and editing only if you need it
Order Persistence: Automatically saves card order when dragged
Column Colors: Customize column colors or use auto-generated colors
Responsive Design: Works on all device sizes
Customizable Cards: Display additional model attributes on cards
Search Functionality: Built-in search across specified model fields
Integration Support: Works with other packages like custom fields systems

🏗️ Model Preparation

For your Kanban board to be fully functional, your model should have:

A field for the card title (e.g., title, name)
A field for the column/status (e.g., status, state)
A field for description (e.g., description, content) - optional
A field for order (e.g., order_column, sort_order) - required for drag & drop functionality

For drag and drop ordering to work, you can either:

Add an integer column to your model migration (as shown in the Quick Start section), or
Use a package like spatie/eloquent-sortable

✅ Required Configuration

For a functional Kanban board, you only need to implement two methods:

1. getSubject() - Provides the data source

public function getSubject(): Builder
{
    return Task::query();
}

2. mount() - Configures the board

public function mount(): void
{
    $this
        ->titleField('title');      // Required: Field used for card titles
        ->columnField('status')     // Required: Field that determines column placement
        ->columns([                 // Required: Define your columns
            'todo' => 'To Do',
            'in_progress' => 'In Progress',
            'completed' => 'Completed',
        ])
}

Example: Minimal Read-Only Board

Here's a complete example of a minimal read-only board:

<?php

namespace App\Filament\Pages;

use App\Models\Task;
use Illuminate\Database\Eloquent\Builder;
use Relaticle\Flowforge\Filament\Pages\KanbanBoardPage;

class TasksBoardPage extends KanbanBoardPage
{
    protected static ?string $navigationIcon = 'heroicon-o-view-columns';

    public function getSubject(): Builder
    {
        return Task::query();
    }

    public function mount(): void
    {
        $this
            ->titleField('title');
            ->columnField('status')
            ->columns([
                'todo' => 'To Do',
                'in_progress' => 'In Progress',
                'completed' => 'Completed',
            ])
    }
}

🔄 Optional Methods

These methods are completely optional and only needed if you want specific functionality:

createAction() - For creating new cards

If you want users to be able to add new cards to the board, implement this method:

use Filament\Actions\Action;
use Filament\Forms;

public function createAction(Action $action): Action
{
    return $action
        ->iconButton()
        ->icon('heroicon-o-plus')
        ->modalHeading('Create Task')
        ->modalWidth('xl')
        ->form(function (Forms\Form $form) {
            return $form->schema([
                Forms\Components\TextInput::make('title')
                    ->required()
                    ->placeholder('Enter task title')
                    ->columnSpanFull(),
                Forms\Components\Textarea::make('description')
                    ->columnSpanFull(),
                // Add more form fields as needed
            ]);
        });
}

Note: If this method is not implemented, no "+" button will appear in column headers and users won't be able to create new cards.

editAction() - For editing existing cards

If you want users to be able to edit existing cards, implement this method:

use Filament\Actions\Action;
use Filament\Forms;

public function editAction(Action $action): Action
{
    return $action
        ->modalHeading('Edit Task')
        ->modalWidth('xl')
        ->form(function (Forms\Form $form) {
            return $form->schema([
                Forms\Components\TextInput::make('title')
                    ->required()
                    ->placeholder('Enter task title')
                    ->columnSpanFull(),
                Forms\Components\Textarea::make('description')
                    ->columnSpanFull(),
                Forms\Components\Select::make('status')
                    ->options([
                        'todo' => 'To Do',
                        'in_progress' => 'In Progress',
                        'completed' => 'Completed',
                    ])
                    ->required(),
                // Add more form fields as needed
            ]);
        });
}

Note: If this method is not implemented, cards will be read-only and users won't be able to edit them.

🧩 Optional Configuration

These settings enhance your board but are not required:

descriptionField(string): Field used for card descriptions
orderField(string): Field used to maintain card order (required for drag & drop)
columnColors(array): Key-value pairs defining colors for each column
cardLabel(string): Custom label for cards (defaults to model name)
pluralCardLabel(string): Custom plural label for cards
cardAttributes(array): Additional model attributes to display on cards
cardAttributeColors(array): Key-value pairs defining colors for each card attribute
cardAttributeIcons(array): Key-value pairs defining icons for each card attribute
initialCardsCount(int): Number of cards initially loaded per column (default: 10)
cardsIncrement(int): Number of cards to load when clicking "load more" (default: 5)

Example with optional configuration:

public function mount(): void
{
    $this
        // Required configuration
        ->columnField('status')
        ->columns([
            'todo' => 'To Do',
            'in_progress' => 'In Progress',
            'completed' => 'Completed',
        ])
        ->titleField('title')
        
        // Optional configuration
        ->descriptionField('description')
        ->orderField('order_column')
        ->columnColors([
            'todo' => 'blue',
            'in_progress' => 'yellow',
            'completed' => 'green',
        ])
        ->cardLabel('Task')
        ->pluralCardLabel('Tasks')
        ->cardAttributes([
            'due_date' => 'Due Date',
            'assignee.name' => 'Assigned To',
        ])
        ->cardAttributeColors([
            'due_date' => 'red',
            'assignee.name' => 'yellow',
        ])
        ->cardAttributeIcons([
            'due_date' => 'heroicon-o-calendar',
            'assignee.name' => 'heroicon-o-user',
        ])
        ->initialCardsCount(15)
        ->cardsIncrement(10);
}

Available Column Colors

Flowforge uses Tailwind CSS color classes for column styling. The available color options are:

white
slate
gray
zinc
neutral
stone
red
orange
amber
yellow
lime
green
emerald
teal
cyan
sky
blue
indigo
violet
purple
fuchsia
pink
rose

If you don't specify colors, they will be automatically assigned from this palette in a rotating manner.

Custom Adapters

For complex scenarios (like integration with custom fields), you can create a custom adapter by implementing KanbanAdapterInterface or extending DefaultKanbanAdapter. This is an advanced feature and only needed for special cases.

❓ Troubleshooting

Common Issues and Solutions

Cards not draggable

Issue: You can see cards but can't drag them between columns or reorder them.

Solution:

Ensure your model has an integer field for ordering (e.g., order_column)
Configure this field with orderField('order_column') in your mount() method
Check browser console for JavaScript errors

Empty board or missing columns

Issue: Your board appears empty or has fewer columns than expected.

Solution:

Verify your model has records with the status values matching your column keys
Check that your columnField() matches a real field in your database
Use dd($this->getSubject()->get()) in your page class to debug your model data

Form validation errors

Issue: Form submissions fail with validation errors.

Solution:

Ensure all required model fields are included in your forms
Check for any unique constraints in your model
Look for mutators or observers that might be affecting the data

Can't create or edit cards

Issue: No create/edit options appear.

Solution:

Make sure you've implemented createAction() and/or editAction() methods
Check that you've properly imported and used the Filament Action and Forms classes
Verify that you've returned the action properly from these methods

Cards not saving when dragged

Issue: Cards can be dragged but don't stay in place after reload.

Solution:

Ensure the orderField() method is set in your configuration
Verify your model is properly saving the order value
If using Spatie's Eloquent-Sortable, ensure it's correctly configured

Advanced Troubleshooting

If you're still experiencing issues, try these steps:

Enable debug mode in your Laravel application
Check Laravel logs for errors
Inspect network requests in your browser's developer tools
Verify your Filament and Laravel versions match the requirements
Try a simpler configuration first, then add complexity

👨‍💻 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📃 License

The MIT License (MIT). Please see License File for more information.

relaticle / flowforge

Maintainers

Details

README

📋 Table of Contents

🛠️ Requirements

🔥 Quick Start

Step 1: Install Flowforge

Step 2: Prepare Your Model

Step 3: Generate a Minimal Kanban Board

Step 4: Register the Page

Step 5: Visit Your Board

🌟 Features

🏗️ Model Preparation

✅ Required Configuration

1. getSubject() - Provides the data source

2. mount() - Configures the board

Example: Minimal Read-Only Board

🔄 Optional Methods

createAction() - For creating new cards

editAction() - For editing existing cards

🧩 Optional Configuration

Available Column Colors

Custom Adapters

❓ Troubleshooting

Common Issues and Solutions

Cards not draggable

Empty board or missing columns

Form validation errors

Can't create or edit cards

Cards not saving when dragged

Advanced Troubleshooting

👨‍💻 Contributing

📃 License