Skip to content

Commit 27a1cbc

Browse files
ManukMinasyanManukMinasyan
committed
Enhance README and add .gitignore for better project setup and management
1 parent 4cfcb2f commit 27a1cbc

File tree

1 file changed

+112
-98
lines changed

1 file changed

+112
-98
lines changed

‎README.md‎

Lines changed: 112 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
# Flowforge - Laravel Filament Kanban Board
22

3-
Flowforge is a lightweight Kanban board package for Filament 3 that works with existing Eloquent models. This package allows developers to transform any model into a Kanban board with minimal configuration, without requiring additional database tables.
3+
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.
44

55
> [!IMPORTANT]
6-
> This package is a work in progress and is not yet ready for production use. It is currently in the alpha stage and may have bugs or incomplete features.
6+
> This package is a work in progress and is not yet ready for production use. It is currently in the alpha stage and may have bugs or incomplete
7+
features.
78

89
## Requirements
910

@@ -13,154 +14,167 @@ Flowforge is a lightweight Kanban board package for Filament 3 that works with e
1314

1415
## Installation
1516

17+
You can install the package via composer:
18+
1619
```bash
1720
composer require relaticle/flowforge
1821
```
1922

20-
Then publish the configuration and assets:
23+
After installing the package, you should publish and run the migrations:
2124

2225
```bash
23-
php artisan vendor:publish --tag="flowforge-config"
24-
php artisan vendor:publish --tag="flowforge-assets"
26+
php artisan flowforge:install
27+
php artisan migrate
2528
```
2629

27-
## Usage
28-
29-
### Quick Start
30+
## Basic Usage
3031

31-
Create a Filament page that extends `KanbanBoardPage`:
32+
To create a Kanban board for your model, create a new Filament page that extends `KanbanBoardPage`:
3233

3334
```php
3435
<?php
3536

3637
namespace App\Filament\Pages;
3738

3839
use App\Models\Task;
40+
use Illuminate\Database\Eloquent\Builder;
3941
use Relaticle\Flowforge\Filament\Pages\KanbanBoardPage;
4042

41-
class TaskBoard extends KanbanBoardPage
43+
class TasksBoardPage extends KanbanBoardPage
4244
{
45+
protected static ?string $navigationIcon = 'heroicon-o-view-columns';
46+
protected static ?string $navigationParentItem = 'Tasks';
47+
4348
public function mount(): void
4449
{
4550
$this
46-
->for(Task::query()->where('user_id', auth()->id()))
51+
->titleField('title')
4752
->columnField('status')
53+
->descriptionField('description')
54+
->orderField('order_column')
4855
->columns([
4956
'todo' => 'To Do',
5057
'in_progress' => 'In Progress',
58+
'review' => 'In Review',
5159
'done' => 'Completed',
5260
])
53-
->titleField('title')
54-
->descriptionField('description')
55-
->withSearchable(['title', 'description']);
61+
->columnColors([
62+
'todo' => 'gray',
63+
'in_progress' => 'blue',
64+
'review' => 'yellow',
65+
'done' => 'green',
66+
]);
67+
}
68+
69+
protected function getSubject(): Builder
70+
{
71+
return Task::query();
5672
}
5773
}
5874
```
5975

60-
Register the page in your Filament panel:
76+
## Configuration Options
6177

62-
```php
63-
public function getPages(): array
64-
{
65-
return [
66-
'tasks' => \App\Filament\Pages\TaskBoard::class,
67-
];
68-
}
69-
```
78+
You can customize your Kanban board using these configuration methods:
79+
80+
- `titleField(string)`: Field used for card titles
81+
- `descriptionField(string)`: Field used for card descriptions
82+
- `columnField(string)`: Field used to determine which column a card belongs to
83+
- `orderField(string)`: Field used to maintain card order (requires a sortable model)
84+
- `columns(array)`: Key-value pairs defining columns (key as identifier, value as display label)
85+
- `columnColors(array)`: Key-value pairs defining colors for each column
86+
- `cardLabel(string)`: Custom label for cards (defaults to model name)
7087

71-
### Advanced Configuration
88+
## Custom Adapters
7289

73-
The Kanban board is fully configurable:
90+
For more complex scenarios, you can create a custom adapter by extending `DefaultKanbanAdapter`:
7491

7592
```php
76-
$this
77-
->for(Task::query())
78-
->columnField('status')
79-
->columns([
80-
'todo' => 'To Do',
81-
'in_progress' => 'In Progress',
82-
'done' => 'Completed',
83-
])
84-
->titleField('title')
85-
->descriptionField('description')
86-
->cardAttributes([
87-
'due_date' => 'Due Date',
88-
'priority' => 'Priority',
89-
])
90-
->columnColors([
91-
'todo' => 'blue',
92-
'in_progress' => 'yellow',
93-
'done' => 'green',
94-
])
95-
->orderField('sort_order')
96-
->cardLabel('Task')
97-
->pluralCardLabel('Tasks')
98-
->createForm(function (Form $form, $activeColumn) {
99-
return $form
100-
->schema([
101-
TextInput::make('title')
102-
->required(),
103-
Textarea::make('description'),
104-
Select::make('priority')
105-
->options([
106-
'low' => 'Low',
107-
'medium' => 'Medium',
108-
'high' => 'High',
109-
]),
110-
]);
111-
});
112-
```
93+
<?php
11394

114-
### Custom Adapter
95+
namespace App\Adapters;
11596

116-
You can provide a custom adapter for special use cases:
97+
use App\Models\Opportunity;
98+
use Filament\Forms;
99+
use Filament\Forms\Form;
100+
use Illuminate\Database\Eloquent\Builder;
101+
use Illuminate\Database\Eloquent\Model;
102+
use Illuminate\Support\Collection;
103+
use Relaticle\Flowforge\Adapters\DefaultKanbanAdapter;
104+
use Relaticle\Flowforge\Contracts\KanbanAdapterInterface;
117105

118-
```php
119-
$this
120-
->for(Task::query())
121-
->withCustomAdapter(new MyCustomAdapter($config))
122-
->withAdapterCallback(function (KanbanAdapterInterface $adapter) {
123-
// Modify the adapter here
124-
return $adapter;
125-
});
126-
```
106+
class OpportunitiesKanbanAdapter extends DefaultKanbanAdapter
107+
{
108+
// Customize forms
109+
public function getCreateForm(Form $form, mixed $currentColumn): Form
110+
{
111+
return $form->schema([
112+
Forms\Components\TextInput::make('title')
113+
->required()
114+
->placeholder('Enter opportunity title')
115+
->columnSpanFull(),
116+
// Add more form fields as needed
117+
]);
118+
}
127119

128-
### Multiple Configuration
120+
// Custom create logic
121+
public function createRecord(array $attributes, mixed $currentColumn): ?Model
122+
{
123+
// Custom creation logic
124+
$opportunity = Opportunity::create($attributes);
125+
126+
// Set the column/status value
127+
$opportunity->status = $currentColumn;
128+
$opportunity->save();
129+
130+
return $opportunity;
131+
}
132+
}
133+
```
129134

130-
You can set multiple configuration values at once:
135+
Then in your page class, override the `getAdapter()` method:
131136

132137
```php
133-
$this
134-
->for(Task::query())
135-
->withConfiguration([
136-
'columnField' => 'status',
137-
'titleField' => 'title',
138-
'descriptionField' => 'description',
139-
'columnValues' => [
140-
'todo' => 'To Do',
141-
'in_progress' => 'In Progress',
142-
'done' => 'Completed',
143-
],
144-
]);
138+
public function getAdapter(): KanbanAdapterInterface
139+
{
140+
return new OpportunitiesKanbanAdapter($this->getSubject(), $this->config);
141+
}
145142
```
146143

147-
## Architecture
144+
## Integration with Custom Fields
148145

149-
Flowforge uses a clean architecture with three main components:
146+
Flowforge can be integrated with custom field systems, as shown in the Opportunities board example:
150147

151-
1. **KanbanConfig**: The immutable configuration object that stores all settings
152-
2. **KanbanAdapterInterface**: The interface that defines data operations
153-
3. **KanbanBoardPage**: The Filament page that provides the UI
148+
```php
149+
class OpportunitiesBoardPage extends KanbanBoardPage
150+
{
151+
public function mount(): void
152+
{
153+
$columns = $this->stageCustomField()->options->pluck('name', 'id');
154+
$columnColors = OpportunityStage::getColors();
154155

155-
### Adapters
156+
$this
157+
->titleField('title')
158+
->columnField('status')
159+
->descriptionField('description')
160+
->orderField('order_column')
161+
->cardLabel('Opportunity')
162+
->columns($columns->toArray())
163+
->columnColors($columns->map(fn($name) => $columnColors[$name] ?? 'gray')->toArray());
164+
}
156165

157-
The package provides two adapter implementations:
166+
// Use a custom adapter
167+
public function getAdapter(): KanbanAdapterInterface
168+
{
169+
return new OpportunitiesKanbanAdapter(Opportunity::query(), $this->config);
170+
}
171+
}
172+
```
158173

159-
- **EloquentModelAdapter**: For working with model class references (`Task::class`)
160-
- **EloquentQueryAdapter**: For working with query builders (`Task::query()->where(...)`)
174+
## Contributing
161175

162-
The appropriate adapter is automatically selected based on the subject type passed to the `for()` method.
176+
Contributions are welcome! Please feel free to submit a Pull Request.
163177

164178
## License
165179

166-
This package is open-source software licensed under the MIT license.
180+
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

0 commit comments

Comments
 (0)