Tree Ui Core Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to composer.json:

   composer require dantleech/tree-ui-core-bundle
   

   Enable in config/bundles.php:

   Dantleech\TreeUiCoreBundle\DantleechTreeUiCoreBundle::class => ['all' => true],
   

2. Define a Tree Model Implement Dantleech\TreeUiCoreBundle\Model\TreeNodeInterface for your entity (e.g., PHPCR-ODM, Doctrine ORM, or Filesystem). Example for Filesystem (zero-config):

   use Dantleech\TreeUiCoreBundle\Model\FilesystemTreeNode;
   
   class MyFileNode extends FilesystemTreeNode
   {
       // Extend or override as needed
   }
   

3. Register Metadata Use annotations or YAML to define tree structure. Example via annotation:

   use Dantleech\TreeUiCoreBundle\Metadata\TreeMetadata;
   
   /**
    * @TreeMetadata(
    *     parentField="parent",
    *     childrenField="children",
    *     rootPath="/root"
    * )
    */
   class MyFileNode { ... }
   

   Or via YAML (config/tree_ui/models/my_model.yaml):

   tree_metadata:
       parent_field: parent
       children_field: children
       root_path: "/root"
   

4. First Use Case: Tree Browser Inject the TreeBrowser service in a controller:

   use Dantleech\TreeUiCoreBundle\Service\TreeBrowser;
   
   class TreeController extends AbstractController
   {
       public function browse(TreeBrowser $browser)
       {
           $tree = $browser->load('my_model');
           return $this->render('tree/browser.html.twig', ['tree' => $tree]);
       }
   }
   

   Render with a view bundle (e.g., TreeUiFancyTreeViewBundle).

Implementation Patterns

Core Workflows

1. Model Integration

   • PHPCR-ODM: Use TreeUiPhpcrOdmModelBundle to auto-map nodes.

     use Dantleech\TreeUiPhpcrOdmBundle\Model\PhpcrTreeNode;
     
     class DocumentNode extends PhpcrTreeNode { ... }
     

   • Doctrine ORM: Implement TreeNodeInterface manually or use a base class.
   • Filesystem: Leverage FilesystemTreeNode for testing or static assets.

2. View Integration

   • FancyTreeView: Install TreeUiFancyTreeViewBundle for drag-and-drop.

     composer require dantleech/tree-ui-fancy-tree-view-bundle
     

   • Static HTML: Use the built-in StaticTreeView for debugging (no dependencies).

3. CRUD Routes Configure routes via YAML (config/tree_ui/routes.yaml):

   tree_ui:
       resource: "@TreeUiCoreBundle/Resources/config/routing.yml"
       prefix: /admin/tree
       defaults:
           _controller: TreeUiCoreBundle:Default:tree
   

   Override templates in templates/tree_ui/ to customize rendering.

4. Multi-Select Form Use the TreeMultiSelectType in Symfony forms:

   $builder->add('nodes', TreeMultiSelectType::class, [
       'model' => 'my_model',
       'choice_label' => 'name',
   ]);
   

Integration Tips

• Dependency Injection: Prefer constructor injection for TreeBrowser, TreeManager, and TreeMetadataFactory.
• Event Listeners: Extend functionality via events (e.g., TreeNodePrePersistEvent).
• Caching: Implement TreeNodeInterface::getCacheKey() for performance.
• Security: Use Symfony’s voter system to restrict tree access by node type/level.

Gotchas and Tips

Pitfalls

1. Metadata Configuration

   • Issue: Forgetting to define root_path or children_field causes silent failures.
   • Fix: Validate metadata with:

     $metadata = $metadataFactory->getMetadata('my_model');
     if (!$metadata->isValid()) {
         throw new \RuntimeException('Invalid tree metadata');
     }
     

   • Tip: Use the StaticTreeView for quick metadata testing.

2. Drag-and-Drop Quirks

   • Issue: FancyTreeView requires jQuery and FancyTree JS. Missing dependencies break UI.
   • Fix: Ensure TreeUiFancyTreeViewBundle assets are enqueued:

     {{ encore_entry_link_tags('fancy-tree') }}
     

3. State Management

   • Issue: Tree state (expanded/collapsed nodes) isn’t persisted by default.
   • Workaround: Implement TreeStateStorageInterface or use session storage:

     $browser->setStateStorage(new SessionTreeStateStorage());
     

4. Performance with Large Trees

   • Issue: Loading deep hierarchies may timeout.
   • Fix: Use lazy-loading via TreeBrowser::loadWithChildren() with depth limits:

     $tree = $browser->loadWithChildren('my_model', 0, 3); // Load root + 3 levels
     

5. Model Coupling

   • Issue: Custom models may break if TreeNodeInterface methods are overlooked.
   • Tip: Extend AbstractTreeNode (if available) to reduce boilerplate.

Debugging

• Enable Debug Mode: Set tree_ui.debug: true in config to log metadata and queries.
• Check Metadata: Dump metadata for a model:

  $metadata = $metadataFactory->getMetadata('my_model');
  dump($metadata->getParentField());
  

• View Rendering: Override tree_ui/default/tree.html.twig to debug node data:

  {% for node in tree %}
      {{ dump(node) }}
  {% endfor %}
  

Extension Points

1. Custom Metadata Sources Implement TreeMetadataSourceInterface to load metadata from databases or APIs.

2. New Tree Views Create a custom view by implementing TreeViewInterface:

   class MyTreeView implements TreeViewInterface
   {
       public function render(TreeNodeInterface $node): string
       {
           return '<div>' . htmlspecialchars($node->getName()) . '</div>';
       }
   }
   

3. Event Subscribers Listen to tree events (e.g., TreeNodePostRemoveEvent) to add logic:

   class MyTreeSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               TreeEvents::NODE_POST_REMOVE => 'onNodeRemove',
           ];
       }
   
       public function onNodeRemove(NodePostRemoveEvent $event)
       {
           // Custom logic (e.g., log deletion)
       }
   }
   

4. Custom CRUD Actions Extend the router configuration to add actions like reorder or export:

   tree_ui_crud:
       path: /admin/tree/{model}/reorder
       defaults:
           _controller: TreeUiCoreBundle:Default:reorder
           model: my_model
   

```markdown
### Config Quirks
- **Bundle Order**: Ensure `TreeUiCoreBundle` loads **after** your model bundles (e.g., `TreeUiPhpcrOdmModelBundle`).
- **Route Conflicts**: Prefix routes explicitly to avoid clashes with Symfony’s default routes.
- **Annotation Processing**: Clear the cache after adding new `@TreeMetadata` annotations:
  ```bash
  php bin/console cache:clear