Graphic Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require acseo/graphic-bundle:dev-master
   

   Enable the bundle in app/AppKernel.php:

   new ACSEO\Bundle\GraphicBundle\ACSEOGraphicBundle(),
   

2. First Use Case: Generate a basic PieChart in a controller:

   use ACSEO\Bundle\GraphicBundle\Graphic\Flot\Type\Pie;
   
   public function showChartAction()
   {
       $data = ['label' => 'Series 1', 'data' => [3, 5, 7]];
       $pie = new Pie("#chart-container", [$data]);
       return $this->render('template.html.twig');
   }
   

   Include jQuery Flot in your Twig template:

   {{ parent() }}
   <script src="https://cdnjs.cloudflare.com/ajax/libs/flot/0.8.3/jquery.flot.min.js"></script>
   

Implementation Patterns

Core Workflow

1. Data Preparation:

   • Format data as associative arrays (e.g., [['label' => 'Label', 'data' => [1, 2, 3]]]).
   • Use strtotime() for timestamps (e.g., strtotime("01/01/2024") * 1000).

2. Chart Initialization:

   • Instantiate chart types in controllers:

     $timeline = new TimeLine("#domId", $data);
     $pie = new Pie("#domId", $data);
     

   • Pass a DOM ID (e.g., #chart-container) and data array.

3. Twig Integration:

   • Render charts in Twig templates after including Flot:

     <div id="chart-container"></div>
     {{ include('ACSEOGraphicBundle::flot.js') }}  <!-- Auto-renders JS -->
     

4. Dynamic Updates:

   • Re-render charts via AJAX by regenerating the chart object and re-including the JS.

Advanced Patterns

• Custom Styling: Override default Flot options via constructor:

  $pie = new Pie("#domId", $data, [
      'series' => ['shadowSize' => 0],
      'grid' => ['hoverable' => true]
  ]);
  

• Multiple Charts: Instantiate multiple chart types in a single controller:

  $timeline = new TimeLine("#timeline", $timelineData);
  $pie = new Pie("#pie", $pieData);
  

• Reusable Services: Create a service to centralize chart logic:

  # services.yml
  acseo.graphic.service:
      class: AppBundle\Service\GraphicService
      arguments: ['@twig']
  

  // GraphicService.php
  public function generatePie($data, $domId) {
      $pie = new Pie($domId, $data);
      return $this->twig->render('ACSEOGraphicBundle::flot.js', ['chart' => $pie]);
  }
  

Gotchas and Tips

Pitfalls

1. DOM ID Conflicts: Ensure the target DOM ID exists in the Twig template. Flot throws silent errors if the element is missing.

2. Timestamp Formatting: Flot expects timestamps in milliseconds (e.g., strtotime("date") * 1000). Incorrect formatting breaks TimeLine charts.

3. Dependency Order: jQuery and Flot must be loaded before the bundle’s JS. Use Twig’s {{ parent() }} to ensure proper ordering.

4. Dev-Master Dependency: The package is in dev-master. Pin the version in composer.json to avoid breaking changes:

   "acseo/graphic-bundle": "dev-master as 1.0.0"
   

Debugging Tips

• Check Console Errors: Open browser dev tools to verify Flot/Flot initialization errors (e.g., missing data or DOM elements).

• Log Chart Data: Dump chart data before instantiation to validate format:

  var_dump($data); // Ensure structure matches Flot expectations
  

• Inspect Generated JS: The bundle auto-renders JS via Twig. Inspect the rendered output to debug:

  {{ dump(app.request->getContent()) }}  <!-- Debug helper -->
  

Extension Points

1. Custom Chart Types: Extend the bundle by creating new chart classes (e.g., LineChart) in ACSEO\Bundle\GraphicBundle\Graphic\Flot\Type\.

2. Override Templates: Override the flot.js.twig template in your bundle to modify JS output:

   {# app/Resources/ACSEOGraphicBundle/views/flot.js.twig #}
   {{ include('ACSEOGraphicBundle::flot.js') }}
   

3. Add New Providers: The bundle supports multiple providers (e.g., Highcharts). Fork the bundle and extend the GraphicProvider interface to add support.

4. Configuration: Use Symfony’s configuration system to centralize chart defaults:

   # config.yml
   acseo_graphic:
       default_options:
           series: { shadowSize: 0 }
   

   (Note: Requires bundle extension to support this.)