Filament Nestable Tree Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require solution-forest/filament-nestable-tree
   

   Publish the config (if needed):

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

2. Basic Usage For an Eloquent model (e.g., Category using kalnoy/nestedset):

   use SolutionForest\FilamentNestableTree\Components\Tree;
   
   Tree::make('Categories')
       ->model(\App\Models\Category::class)
       ->columns([
           TextColumn::make('name'),
           TextColumn::make('slug'),
       ])
       ->actions([
           Action::make('edit')->url(fn ($record) => route('admin.categories.edit', $record)),
       ]);
   

3. First Use Case Replace a Filament Table with a Tree for hierarchical data (e.g., categories, menus, or org charts). Test drag-and-drop reordering immediately.

Implementation Patterns

Core Workflows

1. Eloquent Integration

   • NestedSet: Auto-detects kalnoy/nestedset traits; no extra config needed.
   • Custom Hierarchies: Use ->treeColumn('parent_id') to specify a non-standard foreign key.
   • Lazy Loading: Enable with ->lazy() and define ->getChildrenQuery() for async child fetching.

2. Static Data For non-database arrays (e.g., config menus):

   Tree::make('Menu')
       ->records($menuItems) // Array of associative arrays
       ->recordIdPath('id')  // Key to identify nodes
       ->recordParentPath('parent_id');
   

3. Multi-Tree Pages Combine multiple trees in a single page:

   Tree::make('Primary Categories')
       ->model(\App\Models\Category::class)
       ->treeColumn('parent_id');
   
   Tree::make('Secondary Categories')
       ->model(\App\Models\Category::class)
       ->treeColumn('alternate_parent_id');
   

4. Cross-Tree Drag-and-Drop Allow nodes from one tree to be dragged into another:

   Tree::make('Tree A')
       ->crossTreeDragEnabled()
       ->crossTreeTargetTrees(['tree-b-slug']);
   

Advanced Patterns

• Per-Node Actions: Dynamically add actions based on node depth or metadata:

  ->actions([
      Action::make('publish')
          ->visible(fn ($record) => $record->depth === 1),
  ]);
  

• Custom Rendering: Override node templates via ->recordTemplate() or ->emptyStateTemplate().
• Bulk Operations: Use Filament’s built-in bulk actions (e.g., delete, restore) with ->bulkActions().

Gotchas and Tips

Pitfalls

1. NestedSet vs. Closure Tables

   • The package auto-detects NestedSet, but closure tables (e.g., laravel-nestedset’s alternative) require manual getChildrenQuery() overrides.
   • Example for closure tables:

     ->getChildrenQuery(function (Builder $query, $record) {
         return $query->where('parent_id', $record->id);
     });
     

2. Lazy Loading Performance

   • Avoid N+1 queries: Always define ->getChildrenQuery() for lazy-loaded trees to optimize child fetching.
   • Debounce Async Calls: Use ->lazyDebounce(300) to reduce rapid-fire API calls during drag-and-drop.

3. Cross-Tree Drag-and-Drop Quirks

   • Model Validation: Ensure target trees accept the dragged model’s type (e.g., same parent_id column type).
   • Permissions: Restrict cross-tree actions with ->crossTreeDragVisible() guards.

4. State Persistence

   • Expanded/collapsed states aren’t saved by default. Use Filament’s useState() or a custom cookie handler for persistence:

     ->useState()
     ->statePath('tree_expanded_nodes');
     

Debugging Tips

• Console Logs: Enable debug mode in config/filament-nestable-tree.php to log tree events:

  'debug' => env('FILAMENT_NESTABLE_TREE_DEBUG', false),
  

• Drag-and-Drop Issues: Check browser console for filament-nestable-tree errors. Common fixes:
  • Ensure recordIdPath and recordParentPath match your data structure.
  • Verify kalnoy/nestedset is properly installed if using Eloquent.
• Lazy Loading Failures: Test getChildrenQuery() with dd() to confirm it returns the expected query.

Extension Points

1. Custom Tree Views Override the default Blade template by publishing assets:

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

   Then modify resources/views/vendor/filament-nestable-tree/....

2. Event Listeners Listen for tree events (e.g., TreeNodeMoved) to trigger side effects:

   event(new TreeNodeMoved($tree, $node, $newParent, $newPosition));
   

3. Styling Extend SCSS variables in resources/css/filament-nestable-tree.scss:

   @import "filament-nestable-tree/variables";
   $tree-node-bg: #f0f0f0;
   

4. Testing Use the TreeTestCase helper for unit tests:

   use SolutionForest\FilamentNestableTree\Testing\TreeTestCase;
   
   public function testTreeDragAndDrop()
   {
       $this->actingAs($user)
            ->tree('categories')
            ->dragNode($nodeId, $targetId)
            ->assertNodeMoved($nodeId, $newParentId);
   }