saade/filament-adjacency-list

A Filament package to adjacency lists.

v4.0.0-beta2 2024-10-22 21:15 UTC

Requires

• php: ^8.1
• filament/filament: ^3.0
• illuminate/contracts: ^10.0|^11.0
• spatie/laravel-package-tools: ^1.15.0
• staudenmeir/laravel-adjacency-list: ^1.18

Requires (Dev)

• laravel/pint: ^1.0
• nunomaduro/collision: ^7.0|^8.0
• nunomaduro/larastan: ^2.0.1
• orchestra/testbench: ^8.0|^9.0
• pestphp/pest: ^2.0
• pestphp/pest-plugin-arch: ^2.0
• pestphp/pest-plugin-laravel: ^2.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0
• spatie/laravel-ray: ^1.26

MIT

• Saade

• laravel
• saade
• filament-adjacency-list

README

A Filament package to manage adjacency lists (aka trees).

Installation

You can install the package via composer:

composer require saade/filament-adjacency-list

Usage

use Saade\FilamentAdjacencyList\Forms\Components\AdjacencyList;

AdjacencyList::make('subjects')
    ->form([
        Forms\Components\TextInput::make('label')
            ->required(),
    ])

Configuration

Customizing the label key used to display the item's label

AdjacencyList::make('subjects')
    ->labelKey('name')          // defaults to 'label'

Customizing the children key used to gather the item's children.

Note: This is only used when not using relationships.

AdjacencyList::make('subjects')
    ->childrenKey('children')   // defaults to 'children'

Customizing the MaxDepth of the tree.

AdjacencyList::make('subjects')
    ->maxDepth(2)               // defaults to -1 (unlimited depth)

Creating items without a modal.

AdjacencyList::make('subjects')
    ->modal(false)      // defaults to true

Disabling creation, edition, deletion, and reordering.

AdjacencyList::make('subjects')
    ->addable(false)
    ->editable(false)
    ->deletable(false)
    ->reorderable(false)

Customizing actions

use Filament\Forms\Actions\Action;

AdjacencyList::make('subjects')
    ->addAction(fn (Action $action): Action => $action->icon('heroicon-o-plus')->color('primary'))
    ->addChildAction(fn (Action $action): Action => $action->button())
    ->editAction(fn (Action $action): Action => $action->icon('heroicon-o-pencil'))
    ->deleteAction(fn (Action $action): Action => $action->requiresConfirmation())
    ->reorderAction(fn (Action $action): Action => $action->icon('heroicon-o-arrow-path-rounded-square'))

Important

Reorder Action

If you want to add ->extraAttributes() to the action, you need to add the 'data-sortable-handle' => 'true' to the array, as the action serves as a handle for SortableJS.

By default, clicking on the action will do anything. If you want to trigger some action on click, you need to chain ->livewireClickHandlerEnabled() on the action.

Relationships

In this example, we'll be creating a Ticketing system, where tickets can be assigned to a department, and departments have subjects.

Building the relationship

// App/Models/Department.php

class Department extends Model
{
    public function subjects(): HasMany
    {
        return $this->hasMany(Subject::class)->whereNull('parent_id')->with('children')->orderBy('sort');
    }
}

// App/Models/Subject.php

class Subject extends Model
{
    protected $fillable ['parent_id', 'name', 'sort']; // or whatever your columns are

    public function children(): HasMany
    {
        return $this->hasMany(Subject::class, 'parent_id')->with('children')->orderBy('sort');
    }
}

Now you've created a nested relationship between departments and subjects.

Using the relationship

// App/Filament/Resources/DepartmentResource.php

AdjacencyList::make('subjects')
    ->relationship('subjects')          // Define the relationship
    ->labelKey('name')                  // Customize the label key to your model's column
    ->childrenKey('children')           // Customize the children key to the relationship's method name
    ->form([                            // Define the form
        Forms\Components\TextInput::make('name')
            ->label(__('Name'))
            ->required(),
    ]);

That's it! Now you're able to manage your adjacency lists using relationships.

Working with Staudenmeir's Laravel Adjacency List

This package also supports Staudenmeir's Laravel Adjacency List package.

First, install the package:

composer require staudenmeir/laravel-adjacency-list:"^1.0"

1. Use the HasRecursiveRelationships trait in your model, and override the default path separator.

// App/Models/Department.php

class Department extends Model
{
    use \Staudenmeir\LaravelAdjacencyList\Eloquent\HasRecursiveRelationships;

    public function getPathSeparator()
    {
        return '.children.';
    }
}

If you're already using the HasRecursiveRelationships trait for other parts of your application, it's probably not a good idea to change your model's path separator, since it can break other parts of your application. Instead, you can add as many path separators as you want:

class Department extends Model
{
    use \Staudenmeir\LaravelAdjacencyList\Eloquent\HasRecursiveRelationships;

    public function getCustomPaths()
    {
        return [
            [
                'name' => 'tree_path',
                'column' => 'id',
                'separator' => '.children.',
            ],
        ];
    }
}

1. Use the relationship method to define the relationship:

AdjacencyList::make('subdepartments')
    ->relationship('descendants')   // or 'descendantsAndSelf', 'children' ...
    ->customPath('tree_path')       // if you're using custom paths

That's it! Now you're able to manage your adjacency lists using relationships.

Customizing the query

AdjacencyList::make('subdepartments')
    ->relationship('descendants', fn (Builder $query): Builder => $query->where('enabled', 1))

Ordering

If your application needs to order the items in the list, you can use the orderColumn method:

AdjacencyList::make('subdepartments')
    ->orderColumn('sort')   // or any other column

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Saade
• Ryan Chandler's Navigation Plugin for his work on the tree UI and complex tree actions.
• Hugh for his help on supporting trees/ graphs relationships.
• All Contributors

License

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