README

This is an enhanced version of the Filament Tree plugin, maintained by Uber Technologies cc. We've built upon the excellent work of the original authors at Solution Forest to add policy authorization, dedicated tree resources that replace table views, and enhanced Filament v4 compatibility.

Key Enhancements:

Laravel policy authorization with automatic action hiding
Dedicated tree resources that replace table views entirely
Enhanced parent-child relationship management
Improved action system with hooks
Full backward compatibility with original features

Attribution: Originally created by Solution Forest, enhanced and maintained by Uber Technologies cc.

Filament Tree

Filament Tree is a plugin for Filament Admin that creates a model management page with a heritage tree structure view. This plugin can be used to create menus and more.

This plugin creates model management page with heritage tree structure view for Filament Admin. It could be used to create menu, etc.

Supported Filament versions

Filament Version	Plugin Version
v4	4.x.x

Installation

To install the package, run the following command:

composer require ubertech-za/filament-tree-enhanced

Important: Need to publish assets after version 2.x

php artisan filament:assets

Note: Add plugin Blade files to your custom theme tailwind.config.js for dark mode.

To set up your own custom theme, you can visit the official instruction page on the Filament website.

Add the plugin's views and css to your theme.css file.

@import '<path-to-vendor>/ubertech-za/filament-tree-enhanced/resources/css/jquery.nestable.css';
@import '<path-to-vendor>/ubertech-za/filament-tree-enhanced/resources/css/button.css';
@import '<path-to-vendor>/ubertech-za/filament-tree-enhanced/resources/css/custom-nestable-item.css';
@source '<path-to-vendor>/ubertech-za/filament-tree-enhanced/resources/**/*.blade.php';

Then, publish the config file using:

php artisan vendor:publish --tag="filament-tree-enhanced-config"

You can set your preferred options by adding the following code to your config/filament-tree-enhanced.php file:

<?php

return [
    /**
     * Tree model fields
     */
    'column_name' => [
        'order' => 'order',
        'parent' => 'parent_id',
        'title' => 'title',
    ],
    /**
     * Tree model default parent key
     */
    'default_parent_id' => -1,
    /**
     * Tree model default children key name
     */
    'default_children_key_name' => 'children',
];

Usage

Prepare the database and model

To use Filament Tree, follow these table structure conventions:

Tip: The parent_id field must always default to -1!!!

Schema::create('product_categories', function (Blueprint $table) {
    $table->id();
    $table->integer('parent_id')->default(-1);
    $table->integer('order')->default(0)->index();
    $table->string('title');
    $table->timestamps();
});

This plugin provides a convenient method called treeColumns() that you can use to add the required columns for the tree structure to your table more easily. Here's an example:

Schema::create('product_categories', function (Blueprint $table) {
    $table->id();
    $table->treeColumns();
    $table->timestamps();
});

This will automatically add the required columns for the tree structure to your table.

The above table structure contains three required fields: parent_id, order, title, and other fields do not have any requirements.

The corresponding model is app/Models/ProductCategory.php:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use UbertechZa\FilamentTreeEnhanced\Concern\ModelTree;

class ProductCategory extends Model
{
    use ModelTree;

    protected $fillable = ["parent_id", "title", "order"];

    protected $casts = [
        'parent_id' => 'int'
    ];

    protected $table = 'product_categories';
}

The field names of the three fields parent_id, order, and title in the table structure can also be modified:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use UbertechZa\FilamentTreeEnhanced\Concern\ModelTree;

class ProductCategory extends Model
{
    use ModelTree;

    protected $fillable = ["parent_id", "title", "order"];

    protected $table = 'product_categories';

    // Default if you need to override

    // public function determineOrderColumnName(): string
    // {
    //     return "order";
    // }

    // public function determineParentColumnName(): string
    // {
    //     return "parent_id";
    // }

    // public function determineTitleColumnName(): string
    // {
    //     return 'title';
    // }

    // public static function defaultParentKey()
    // {
    //     return -1;
    // }

    // public static function defaultChildrenKeyName(): string
    // {
    //     return "children";
    // }

}

Widget

Filament provides a powerful feature that allows you to display widgets inside pages, below the header and above the footer. This can be useful for adding additional functionality to your resource pages.

To create a Tree Widget and apply it to a resource page, you can follow these steps:

1. Creating a Filament Resource Page

To create a resources page, run the following command:

php artisan make:filament-resource ProductCategory

2. Create Tree Widget

Prepare the filament-tree Widget and show it in Resource page.

php artisan make:filament-tree-widget ProductCategoryWidget

Now you can see the Widget in Filament Folder

<?php

namespace App\Filament\Widgets;

use App\Models\ProductCategory as ModelsProductCategory;
use App\Filament\Widgets;
use Filament\Forms\Components\TextInput;
use UbertechZa\FilamentTreeEnhanced\Widgets\Tree as BaseWidget;

class ProductCategoryWidget extends BaseWidget
{
    protected static string $model = ModelsProductCategory::class;

    // you can customize the maximum depth of your tree
    protected static int $maxDepth = 2;

    protected ?string $treeTitle = 'ProductCategory';

    protected bool $enableTreeTitle = true;

    protected function getFormSchema(): array
    {
        return [
            TextInput::make('title'),
        ];
    }
}

3. Displaying a widget on a resource page

Once you have created the widget, modify the getHeaderWidgets() or getFooterWidgets() methods of the resource page to show the tree view:

<?php

namespace App\Filament\Resources\ProductCategoryResource\Pages;

use App\Filament\Resources\ProductCategoryResource;
use App\Filament\Widgets\ProductCategory;
use Filament\Pages\Actions;
use Filament\Resources\Pages\ListRecords;

class ListProductCategories extends ListRecords
{
    protected static string $resource = ProductCategoryResource::class;

    protected function getActions(): array
    {
        return [
            Actions\CreateAction::make(),
        ];
    }

    protected function getHeaderWidgets(): array
    {
        return [
            ProductCategory::class
        ];
    }
}

Resources

Filament allows you to create a custom pages for resources, you also can create a tree page that display hierarchical data.

Create a Page

To create a tree page for resource, you can use:

php artisan make:filament-tree-page ProductCategoryTree --resource=ProductCategory

Register a Page to the resource

You must register the tree page to a route in the static getPages() methods of your resource. For example:

public static function getPages(): array
{
    return [
        // ...
        'tree-list' => Pages\ProductCategoryTree::route('/tree-list'),
    ];
}

Actions

Define the available "actions" for the tree page using the getActions() and getTreeActions() methods of your page class.

The getActions() method defines actions that are displayed next to the page's heading:

    use Filament\Actions\CreateAction;

    protected function getActions(): array
    {
        return [
            CreateAction::make(),
            // SAMPLE CODE, CAN DELETE
            //\Filament\Pages\Actions\Action::make('sampleAction'),
        ];
    }

The getTreeActions() method defines the actions that are displayed for each record in the tree. For example:

use UbertechZa\FilamentTreeEnhanced\Actions\DeleteAction;
use UbertechZa\FilamentTreeEnhanced\Actions\EditAction;
use UbertechZa\FilamentTreeEnhanced\Actions\ViewAction;

protected function getTreeActions(): array
{
    return [
        ViewAction::make(),
        EditAction::make(),
        DeleteAction::make(),
    ];
}

Alternatively, you can use the hasDeleteAction(), hasEditAction(), and hasViewAction() methods to customize each action individually.

protected function hasDeleteAction(): bool
{
    return false;
}

protected function hasEditAction(): bool
{
    return true;
}

protected function hasViewAction(): bool
{
    return false;
}

Record ICON

To customize the prefix icon for each record in a tree page, you can use the getTreeRecordIcon() method in your tree page class. This method should return a string that represents the name of the icon you want to use for the record. For example:

public function getTreeRecordIcon(?\Illuminate\Database\Eloquent\Model $record = null): ?string
{
    if ($record->parent_id != -1) {
        return null; // no icon for child records
    }

    return match ($record->title) {
        'Top' => 'heroicon-o-arrow-up',
        'Bottom' => 'heroicon-o-arrow-down',
        'Shoes' => 'heroicon-o-shopping-bag',
        'Accessories' => 'heroicon-o-briefcase',
        default => null, // no icon for other records
    };
}

Node collapsed state

You can customize a collapsed state of the node. If you would like to show your tree initially collapsed you can use:

public function getNodeCollapsedState(?\Illuminate\Database\Eloquent\Model $record = null): bool
{
    // All tree nodes will be collapsed by default.
    return true;
}

Record Title

To customize the ttile for each record in a tree page, you can use the getTreeRecordTitle() method in your tree page class. This method should return a string that represents the name of the icon you want to use for the record. For example:

public function getTreeRecordTitle(?\Illuminate\Database\Eloquent\Model $record = null): string
{
    if (! $record) {
        return '';
    }
    $id = $record->getKey();
    $title = $record->{(method_exists($record, 'determineTitleColumnName') ? $record->determineTitleColumnName() : 'title')};
    return "[{$id}] {$title}";
}

Configuring Tree Item Actions

You can customize the behavior and appearance of tree item actions (Delete, Edit, and View) by overriding the configuration methods in your widget or page class. Each action type has its own configuration method:

Configure Delete Action

Override the configureDeleteAction() method to customize the delete action:

protected function configureDeleteAction(DeleteAction $action): DeleteAction
{
    $action
        ->label('Remove Item')
        ->icon('heroicon-o-trash')
        ->color('danger')
        ->requiresConfirmation()
        ->modalHeading('Delete Category')
        ->modalDescription('Are you sure you want to delete this category? This action cannot be undone.')
        ->modalSubmitActionLabel('Yes, delete it');

    return $action;
}

Configure Edit Action

Override the configureEditAction() method to customize the edit action:

protected function configureEditAction(EditAction $action): EditAction
{
    $action
        ->label('Edit Item')
        ->icon('heroicon-o-pencil')
        ->color('primary')
        ->modalHeading('Edit Category')
        ->modalSubmitActionLabel('Save Changes')
        ->slideOver();

    return $action;
}

Configure View Action

Override the configureViewAction() method to customize the view action:

protected function configureViewAction(ViewAction $action): ViewAction
{
    $action
        ->label('View Details')
        ->icon('heroicon-o-eye')
        ->color('secondary')
        ->modalHeading('Category Details')
        ->modalWidth('2xl')
        ->slideOver();

    return $action;
}

Example: Complete Action Configuration

Here's a complete example showing how to configure all three actions in a tree widget:

<?php

namespace App\Filament\Widgets;

use App\Models\ProductCategory;
use Filament\Forms\Components\TextInput;
use UbertechZa\FilamentTreeEnhanced\Actions\DeleteAction;
use UbertechZa\FilamentTreeEnhanced\Actions\EditAction;
use UbertechZa\FilamentTreeEnhanced\Actions\ViewAction;
use UbertechZa\FilamentTreeEnhanced\Widgets\Tree as BaseWidget;

class ProductCategoryWidget extends BaseWidget
{
    protected static string $model = ProductCategory::class;

    protected function getFormSchema(): array
    {
        return [
            TextInput::make('title')->required(),
        ];
    }

    protected function hasDeleteAction(): bool
    {
        return true;
    }

    protected function hasEditAction(): bool
    {
        return true;
    }

    protected function hasViewAction(): bool
    {
        return true;
    }

    protected function configureDeleteAction(DeleteAction $action): DeleteAction
    {
        $action
            ->requiresConfirmation()
            ->modalDescription('This will permanently delete the category and all its subcategories.');

        return $action;
    }

    protected function configureEditAction(EditAction $action): EditAction
    {
        $action
            ->slideOver()
            ->modalWidth('md');

        return $action;
    }

    protected function configureViewAction(ViewAction $action): ViewAction
    {
        $action
            ->slideOver()
            ->disabled(fn ($record) => $record->parent_id === -1); // Disable for root items

        return $action;
    }
}

Pages

This plugin enables you to create tree pages in the admin panel. To create a tree page for a model, use the make:filament-tree-page command. For example, to create a tree page for the ProductCategory model, you can run:

Create a Page

Tip: Note that you should make sure the model contains the required columns or already uses the ModelTree trait

php artisan make:filament-tree-page ProductCategory --model=ProductCategory

Actions, Widgets and Icon for each record

Once you've created the tree page, you can customize the available actions, widgets, and icon for each record. You can use the same methods as for resource pages. See the Resource Page for more information on how to customize actions, widgets, and icons.

Translation

Suggest used with Spatie Translatable https://github.com/lara-zeus/translatable Plugin.

Ensure your model already apply translatable setup. (Refence on https://spatie.be/docs/laravel-translatable/v6/installation-setup)

use Filament\Actions\LocaleSwitcher;
use UbertechZa\FilamentTreeEnhanced\Concern\ModelTree;
use Spatie\Translatable\HasTranslations;

class Category extends Model
{
    use HasTranslations;
    use TreeModel;

    protected $translatable = [
        'title',
    ];
}

You need to add the necessary trait and LocaleSwitcher header action to your tree page:

use App\Models\Category as TreePageModel;
use UbertechZa\FilamentTreeEnhanced\Concern\TreeRecords\Translatable;
use UbertechZa\FilamentTreeEnhanced\Pages\TreePage as BasePage;

class Category extends BasePage
{
    use Translatable;

    protected static string $model = TreePageModel::class;

    public function getTranslatableLocales(): array
    {
        return ['en', 'fr'];
    }

    protected function getActions(): array
    {
        return [
            LocaleSwitcher::make(),
        ];
    }
}

Publishing Views

To publish the views, use:

php artisan vendor:publish --tag="filament-tree-enhanced-views"

Publishing Translations

To publish the translations, use:

php artisan vendor:publish --tag="filament-tree-enhanced-translations"

🆕 Enhanced Features

This enhanced fork includes powerful new features that extend the capabilities of Filament Tree:

1. Tree Resource Generation Command

Create complete tree resources that replace table views with hierarchical tree interfaces:

Command: `make:filament-tree-resource`

# Create a complete tree resource
php artisan make:filament-tree-resource Location --model=Location

# Include form generation (optional, off by default)
php artisan make:filament-tree-resource Category --model=Category --generate-form

Generated Structure (Filament v4 Pattern)

The command creates a complete resource following Filament v4's folder-based organization:

app/Filament/Resources/Locations/
├── LocationResource.php           # Main resource class
├── Pages/
│   ├── ListLocations.php         # Tree view page (replaces table)
│   ├── CreateLocation.php        # Create page with parent_id support
│   ├── EditLocation.php          # Edit page
│   └── ViewLocation.php          # View page  
├── Schemas/
│   └── LocationForm.php          # Reusable form schema
└── Trees/
    └── LocationsTree.php         # Tree configuration and actions

Key Differences from Original Approaches

Tree Resource vs Resource with Tree Widget:

Creates a dedicated tree resource (not a regular resource + tree widget)
The tree view completely replaces the table view
Designed specifically for hierarchical data management

Page-Based Navigation (No Modals):

Uses dedicated pages for Create, Edit, List, and View operations
Matches standard Filament resource behavior
Better UX for complex forms and workflows
Supports deep linking and browser navigation

Enhanced Capabilities:

Relation Manager Support: Add ContactsRelationManager, etc. (not supported in widget/old integration)
Custom Record Actions: Full support for custom actions on tree records
Policy Integration: Complete Laravel policy authorization
Parent ID Auto-Population: Child creation automatically sets parent relationships

Usage Example

// Generated LocationResource.php
class LocationResource extends TreeResource
{
    protected static ?string $model = Location::class;
    protected static ?string $navigationIcon = 'heroicon-o-map';
    
    public static function getRelations(): array
    {
        return [
            ContactsRelationManager::class,
            // Add more relation managers
        ];
    }
}

// Generated LocationsTree.php  
class LocationsTree extends BaseTree
{
    public static function tree(Tree $tree): Tree
    {
        return $tree->maxDepth(4);
    }
    
    public static function getResource(): string
    {
        return LocationResource::class;
    }
    
    // Action configuration (all enabled by default)
    // protected bool $hasCreateAction = true;
    // protected bool $hasAddChildAction = true; 
    // protected bool $hasEditAction = true;
    // protected bool $hasViewAction = true;
    // protected bool $hasDeleteAction = true;
}

2. Laravel Policy Authorization

Automatically hide unauthorized actions based on Laravel policies:

// Enable in config/filament-tree.php
'enable_policy_authorization' => true,

Features:

Actions are completely hidden when unauthorized (not just disabled)
Tree reordering disabled when user lacks update permissions
Works with any Laravel authorization system (Gates, Policies, Spatie)
Configurable ability mapping

Policy Methods Supported:

class LocationPolicy
{
    public function viewAny(User $user): bool
    public function create(User $user): bool  
    public function update(User $user, Location $location): bool
    public function delete(User $user, Location $location): bool
}

3. Enhanced Action System

CreateChildAction with Auto Parent-Child Relationships

use UbertechZa\FilamentTreeEnhanced\Actions\CreateChildAction;

protected function getTreeActions(): array
{
    return [
        CreateChildAction::make()
            ->beforeAction(function ($record, $data) {
                // Customize data before creation
                $data['type'] = match($record->type) {
                    'country' => 'state',
                    'state' => 'city',
                    default => 'district'
                };
                return $data;
            })
            ->afterAction(function ($record, $data, $result) {
                // Log, notify, or perform side effects
                activity()->performedOn($result)->log("Created child under {$record->name}");
                return $result;
            }),
    ];
}

Action Hooks System

All tree actions now support powerful before/after hooks:

use UbertechZa\FilamentTreeEnhanced\Actions\EditAction;
use UbertechZa\FilamentTreeEnhanced\Actions\DeleteAction;

protected function getTreeActions(): array
{
    return [
        EditAction::make()
            ->beforeAction(function ($record, $data) {
                // Validate, prepare, or log before action
                return $data;
            })
            ->afterAction(function ($record, $data, $result) {
                // Clear cache, send notifications, log changes
                return $result;
            }),
            
        DeleteAction::make()
            ->beforeAction(function ($record) {
                // Safety checks
                if ($record->children()->count() > 0) {
                    throw new \Exception('Cannot delete record with children');
                }
                return true;
            }),
    ];
}

4. Enhanced Configuration

The config file now includes additional options:

return [
    // Existing options...
    
    /**
     * Enable Laravel policy authorization
     */
    'enable_policy_authorization' => false,
    
    /**
     * Policy abilities mapping
     */
    'policy_abilities' => [
        'create' => 'create',
        'createChild' => 'create',
        'edit' => 'update',
        'view' => 'view',
        'delete' => 'delete',
    ],
    
    /**
     * TreeResource configuration
     */
    'resources' => [
        'enabled' => true,
        'namespace' => 'App\\Filament\\Resources',
        'path' => app_path('Filament/Resources'),
    ],
];

5. Backward Compatibility

All original functionality remains fully supported:

make:filament-tree-page: Creates standalone tree pages with modal forms
make:filament-tree-widget: Creates tree widgets for dashboards
Resource Integration: Original "create in resource" option still works

The enhanced features are additive and don't break existing implementations.

Testing

To run the tests, run:

composer test

Changelog

See the CHANGELOG for more information on what has changed recently.

Contributing

See CONTRIBUTING for details.

Security Vulnerabilities

If you discover any security related issues, please report them via the GitHub issue tracker or create a private security advisory.

Credits

Original Work: Solution Forest - Carly and contributors

Enhancements: Uber Technologies cc

License

Enhanced Filament Tree is open-sourced software licensed under the MIT license.

ubertech-za / filament-tree-enhanced

Maintainers

Details

README

Filament Tree

Supported Filament versions

Installation

Usage

Prepare the database and model

Widget

1. Creating a Filament Resource Page

2. Create Tree Widget

3. Displaying a widget on a resource page

Resources

Create a Page

Register a Page to the resource

Actions

Record ICON

Node collapsed state

Record Title

Configuring Tree Item Actions

Configure Delete Action

Configure Edit Action

Configure View Action

Example: Complete Action Configuration

Pages

Create a Page

Actions, Widgets and Icon for each record

Translation

Publishing Views

Publishing Translations

🆕 Enhanced Features

1. Tree Resource Generation Command

Command: make:filament-tree-resource

Generated Structure (Filament v4 Pattern)

Key Differences from Original Approaches

Usage Example

2. Laravel Policy Authorization

3. Enhanced Action System

CreateChildAction with Auto Parent-Child Relationships

Action Hooks System

4. Enhanced Configuration

5. Backward Compatibility

Testing

Changelog

Contributing

Security Vulnerabilities

Credits

License

Command: `make:filament-tree-resource`