Dashboard2 Bundle Laravel Package

Getting Started

First Steps

1. Installation:

   composer require 2lenet/dashboard2-bundle
   

   Add the bundle to config/bundles.php (if not auto-discovered) and register routes in config/routes.yaml:

   dashboard_widgets:
       resource: "@LleDashboardBundle/Resources/config/routes.yaml"
   

   Run migrations to create the widgets table:

   php bin/console make:migration
   php bin/console doctrine:migrations:migrate
   

2. First Widget: Use the maker command to scaffold a basic widget:

   php bin/console make:widget
   

   Follow prompts to define a name (e.g., user_stats). The command generates:

   • A widget class extending AbstractWidget (e.g., src/Widget/UserStatsWidget.php).
   • A Twig template (templates/widgets/user_stats.html.twig).

3. Register the Widget: Add your widget to the dashboard configuration in config/packages/lle_dashboard.yaml:

   lle_dashboard:
       widgets:
           - Lle\DashboardBundle\Widget\UserStatsWidget
   

4. Access the Dashboard: Visit /dashboard (or your configured route) to see the widget rendered.

Implementation Patterns

Core Workflows

1. Widget Development Cycle:

   • Design: Sketch the widget’s purpose (e.g., "Display active users").
   • Scaffold: Use make:widget to generate boilerplate.
   • Customize:
     • Override render() to fetch data (e.g., via repository or API).
     • Style with Twig (pass variables via getData()).
   • Test: Verify rendering and data logic in isolation.

2. Data Fetching:

   • Use getData() to return structured data for the template:

     public function getData(): array
     {
         return [
             'users' => $this->userRepository->findActiveUsers(),
         ];
     }
     

   • Cache data with @cache in Twig or AbstractWidget's built-in caching.

3. Dynamic Widgets:

   • For workflow-specific widgets, use make:workflow-widget to integrate with Symfony’s workflow component.
   • Example: A "Pending Approval" widget tied to a publish workflow transition.

4. Configuration:

   • Define widget-specific settings in config/packages/lle_dashboard.yaml:

     widgets:
         - { class: App\Widget\UserStatsWidget, options: { limit: 10 } }
     

   • Access options in the widget via getOptions():

     $limit = $this->getOptions()['limit'] ?? 5;
     

5. Templating:

   • Use Twig to render dynamic content. Example (user_stats.html.twig):

     {% for user in data.users %}
         <div>{{ user.username }} ({{ user.lastLogin|date('Y-m-d') }})</div>
     {% endfor %}
     

   • Extend base templates (@LleDashboard/widget.html.twig) for consistent styling.

6. Role-Based Visibility:

   • Restrict widgets to roles by implementing supportsRole():

     public function supportsRole(string $role): bool
     {
         return $role === 'ROLE_ADMIN';
     }
     

   • Configure roles in config/packages/lle_dashboard.yaml:

     widgets:
         - { class: App\Widget\AdminWidget, roles: ['ROLE_ADMIN'] }
     

Gotchas and Tips

Common Pitfalls

1. Migration Warnings:

   • Issue: Forgetting to run migrations after installation causes WidgetNotFoundException.
   • Fix: Always run php bin/console doctrine:migrations:migrate post-install.

2. Caching Quirks:

   • Issue: Widget data not updating due to aggressive caching.
   • Fix:
     • Disable caching for development:

       # config/packages/lle_dashboard.yaml
       cache: false
       

     • Use invalidateCache() in widgets that need real-time data:

       public function render(): string
       {
           $this->invalidateCache(); // Force refresh
           // ...
       }
       

3. Template Paths:

   • Issue: Twig templates not found if placed in non-standard locations.
   • Fix: Ensure templates are in templates/widgets/{widget_name}.html.twig or configure custom paths in AbstractWidget.

4. Dependency Injection:

   • Issue: Services not available in widgets (e.g., repositories).
   • Fix: Inject dependencies via constructor or getService():

     public function __construct(private UserRepository $userRepository) {}
     

5. Route Conflicts:

   • Issue: Dashboard routes clashing with existing routes.
   • Fix: Customize routes in config/routes.yaml:

     dashboard:
         path: /admin/dashboard
         controller: LleDashboardBundle:Dashboard:index
     

Pro Tips

1. Widget Reusability:

   • Create abstract base widgets for shared logic (e.g., AbstractChartWidget).
   • Extend in child widgets to avoid duplication.

2. Performance:

   • Lazy-load heavy data in render() instead of getData() if caching is enabled.
   • Use AbstractWidget::isCacheValid() to skip expensive operations when cached.

3. Testing:

   • Test widgets in isolation with PHPUnit:

     public function testRender()
     {
         $widget = new UserStatsWidget($this->entityManager);
         $html = $widget->render();
         $this->assertStringContainsString('Active Users', $html);
     }
     

   • Mock dependencies (e.g., repositories) for unit tests.

4. Debugging:

   • Enable debug mode in config/packages/dev/lle_dashboard.yaml:

     debug: true
     

   • Check widget logs with php bin/console debug:widgets (if supported).

5. Extending the Bundle:

   • Override default templates by copying them from vendor/lle/dashboard-bundle/templates/ to your project’s templates/ directory.
   • Extend AbstractWidget to add custom methods (e.g., getWidgetType() for categorization).

6. Static Dashboards:

   • For non-dynamic dashboards, use the StaticDashboard component:

     # config/packages/lle_dashboard.yaml
     static_dashboard:
         enabled: true
         widgets:
             - { template: 'widgets/static_home.html.twig' }