Handorgel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require contao-components/handorgel
   

   Ensure your Laravel app meets Handorgel’s PHP requirements (PHP 8.1+ recommended).

2. Basic Usage Handorgel is a JavaScript-based package for creating interactive, animated SVG diagrams (e.g., flowcharts, org charts). To integrate:

   • Include the Handorgel JS/CSS in your Blade template:

     @vite(['resources/js/handorgel.js', 'resources/css/handorgel.css'])
     

   • Initialize with a minimal SVG structure:

     <div id="handorgel-container"></div>
     <script>
         const handorgel = new Handorgel({
             container: '#handorgel-container',
             data: {
                 nodes: [{ id: '1', label: 'Node 1' }],
                 edges: []
             }
         });
     </script>
     

3. First Use Case Visualize a simple workflow (e.g., user signup flow) with nodes/edges. Use Laravel’s Blade to pass dynamic data:

   @php
       $workflowData = [
           'nodes' => ['auth' => ['label' => 'Authentication'], 'profile' => ['label' => 'Profile Setup']],
           'edges' => [['from' => 'auth', 'to' => 'profile']]
       ];
   @endphp
   <script>
       new Handorgel({ container: '#workflow', data: @json($workflowData) });
   </script>
   

Implementation Patterns

Data-Driven Integration

• Laravel Eloquent ↔ Handorgel Data Map database models to Handorgel’s nodes/edges format. Example:

  $nodes = User::with('roles')->get()->map(fn ($user) => [
      'id' => $user->id,
      'label' => $user->name,
      'data' => ['role' => $user->roles->first()->name] // Custom attributes
  ]);
  

  Pass to Handorgel via @json($nodes->toArray()).

• API Endpoints Create a Laravel API route to fetch Handorgel data dynamically:

  Route::get('/handorgel-data', function () {
      return response()->json([
          'nodes' => Node::all()->toHandorgelFormat(),
          'edges' => Edge::all()->toHandorgelFormat()
      ]);
  });
  

Workflow Patterns

1. Real-Time Updates Use Laravel Echo + Pusher to push Handorgel data changes (e.g., node additions) to clients:

   Echo.channel('handorgel-updates')
       .listen('NodeAdded', (data) => {
           handorgel.addNode(data.node);
       });
   

2. Server-Side Rendering (SSR) For SPAs, pre-render Handorgel diagrams on the server (Laravel) and hydrate client-side:

   // In a controller
   return inertia('HandorgelPage', [
       'initialData' => $handorgelData
   ]);
   

   // Inertia page
   const { initialData } = props;
   const handorgel = new Handorgel({ data: initialData });
   

3. Custom Interactions Extend Handorgel with Laravel-backed actions:

   handorgel.on('nodeClick', (nodeId) => {
       axios.post(`/nodes/${nodeId}/actions`, { action: 'archive' });
   });
   

Gotchas and Tips

Pitfalls

1. SVG Scaling Issues

   • Handorgel renders SVGs, which can break with dynamic resizing. Use CSS viewBox or set a fixed container height:

     #handorgel-container {
         height: 600px;
         width: 100%;
     }
     

2. Data Format Strictness

   • Handorgel expects strict JSON schemas for nodes/edges. Validate with Laravel’s Form Requests:

     public function rules() {
         return [
             'nodes.*.id' => 'required|string',
             'edges.*.from' => 'required|exists:nodes,id'
         ];
     }
     

3. JavaScript Initialization Race Conditions

   • Ensure Handorgel’s container exists before initialization. Use defer or DOMContentLoaded:

     <script defer>
         document.addEventListener('DOMContentLoaded', () => {
             new Handorgel({ container: '#handorgel-container' });
         });
     </script>
     

Debugging Tips

• Console Logs: Handorgel emits events (e.g., nodeAdded). Listen in browser console:

  handorgel.on('*', (event) => console.log(event));
  

• Laravel Logs: Log Handorgel data before passing to JS to catch serialization issues:

  \Log::debug('Handorgel data:', $handorgelData);
  

Extension Points

1. Custom Node Templates Override Handorgel’s default node rendering via CSS/JS:

   handorgel.setNodeTemplate((node) => `
       <div class="custom-node ${node.data.type}">
           ${node.label}
       </div>
   `);
   

2. Laravel Service Provider Bind Handorgel to Laravel’s container for dependency injection:

   // app/Providers/AppServiceProvider.php
   $this->app->singleton(Handorgel::class, function () {
       return new Handorgel(config('handorgel.defaults'));
   });
   

3. Testing Use Laravel’s Livewire or Alpine.js to test Handorgel interactions:

   // Example with Alpine
   <div x-data="{ handorgel: null }" x-init="
       handorgel = new Handorgel({ container: '#container' });
       handorgel.on('nodeClick', () => alert('Test passed!'));
   ">