Raphael Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation: Run composer require bmatzner/raphael-bundle in your Symfony2 project. Add new Bmatzner\RaphaelBundle\BmatznerRaphaelBundle() to app/AppKernel.php under registerBundles().

2. Asset Setup: Execute php app/console assets:install web (or --symlink for development). Verify Raphael.js is available at web/bundles/bmatznerraphael/js/raphael.min.js.

3. First Use Case: Include Raphael in a Twig template:

   {% block javascripts %}
       {{ parent() }}
       <script src="{{ asset('bundles/bmatznerraphael/js/raphael.min.js') }}"></script>
       <script>
           var paper = Raphael("canvas", 500, 300); // Basic canvas initialization
           paper.circle(250, 150, 40).attr({ fill: "#f00" }); // Draw a red circle
       </script>
   {% endblock %}
   

   Add a <div id="canvas"></div> to your HTML where the visualization will render.

Implementation Patterns

Common Workflows

1. Dynamic Data Visualization: Fetch data via Symfony controllers (e.g., JSON API) and render interactive charts with Raphael. Example:

   // src/AppBundle/Controller/DataController.php
   public function getChartDataAction()
   {
       return new JsonResponse(['data' => [10, 20, 30, 40]]);
   }
   

   // Twig template
   <script>
       $.get('/data', function(data) {
           var paper = Raphael("chart", 500, 300);
           data.data.forEach(function(value, i) {
               paper.rect(50 + i * 30, 250 - value * 5, 20, value * 5).attr({ fill: "#0f0" });
           });
       });
   </script>
   

2. Reusable Components: Create a custom Twig extension or service to encapsulate Raphael logic. Example Twig extension:

   // src/AppBundle/Twig/RaphaelExtension.php
   class RaphaelExtension extends \Twig_Extension
   {
       public function getFunctions()
       {
           return [
               new \Twig_SimpleFunction('raphael_canvas', [$this, 'renderCanvas']),
           ];
       }
       public function renderCanvas($id, $width, $height)
       {
           return $this->env->render('BmatznerRaphaelBundle:Default:canvas.html.twig', [
               'id' => $id,
               'width' => $width,
               'height' => $height,
           ]);
       }
   }
   

   Use in Twig:

   {{ raphael_canvas('chart', 500, 300) }}
   

3. Integration with Symfony Forms: Use Raphael for custom form widgets (e.g., interactive sliders or color pickers). Example:

   <div id="color-picker"></div>
   {{ form_widget(form.color) }}
   <script>
       var paper = Raphael("color-picker", 200, 50);
       // Custom color picker logic using Raphael
   </script>
   

4. Asset Management: Override Raphael assets in app/Resources/public/bundles/bmatznerraphael/ for custom builds. Use assets:install --symlink in development to avoid caching issues.

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • The bundle assumes assets are installed in web/bundles/bmatznerraphael/. If using a custom public directory (e.g., public/), update the assets:install path or configure the bundle’s Resources/public path in BmatznerRaphaelBundle.php.
   • Debugging: Verify the asset path with {{ asset('bundles/bmatznerraphael/js/raphael.min.js') }} in Twig. A 404 indicates misconfigured assets.

2. Version Lock: The bundle bundles Raphael v2.1.2, which is outdated (current version is v2.3.0 as of 2023). Ensure compatibility with your project’s dependencies (e.g., jQuery plugins). Consider forking the bundle to update Raphael or using a CDN for the latest version.

3. Symfony 2.x Only: The bundle is Symfony 2.x-specific. It will not work with Symfony 3+ without modifications (e.g., updating AppKernel.php to Kernel.php and adjusting bundle registration).

4. No Twig Integration: The bundle provides no built-in Twig helpers or filters. You must manually include scripts and manage canvas elements in templates.

5. Debugging Raphael:

   • Check browser console for errors (e.g., missing Raphael global object).
   • Ensure jQuery (if used) is loaded before Raphael, as Raphael depends on it for some features.

Tips

1. Custom Builds: Override Raphael’s JS/CSS in app/Resources/public/bundles/bmatznerraphael/ to include custom builds or plugins. Example:

   cp vendor/bmatzner/raphael-bundle/Resources/public/js/raphael.min.js app/Resources/public/bundles/bmatznerraphael/js/
   

   Then extend it with additional plugins (e.g., raphael.elastic.js).

2. Performance: Lazy-load Raphael if not used on every page:

   {% block javascripts %}
       {{ parent() }}
       {% if is_raphael_page %}
           <script src="{{ asset('bundles/bmatznerraphael/js/raphael.min.js') }}"></script>
       {% endif %}
   {% endblock %}
   

3. Testing: Use Symfony’s WebTestCase to test Raphael-rendered content by inspecting the DOM or simulating user interactions:

   public function testRaphaelCanvas()
   {
       $client = static::createClient();
       $client->request('GET', '/chart-page');
       $this->assertSelectorTextContains('div#canvas', 'Raphael');
   }
   

4. Fallbacks: Provide a fallback for browsers without SVG support (e.g., older IE):

   <div id="canvas-fallback">Your browser does not support SVG.</div>
   <script>
       if (!window.Raphael) {
           document.getElementById('canvas').style.display = 'none';
           document.getElementById('canvas-fallback').style.display = 'block';
       }
   </script>
   

5. Extending the Bundle: To add features (e.g., custom Twig functions), subclass BmatznerRaphaelBundle and override its behavior:

   // src/AppBundle/Bmatzner/Raphael/AppRaphaelBundle.php
   class AppRaphaelBundle extends BmatznerRaphaelBundle
   {
       public function getPath($name)
       {
           return parent::getPath($name) . 'custom/'; // Extend asset paths
       }
   }
   

   Register it in AppKernel.php instead of the original bundle.

6. Raphael Plugins: Integrate Raphael plugins (e.g., raphael.elastic) by including them after Raphael’s script:

   <script src="{{ asset('bundles/bmatznerraphael/js/raphael.min.js') }}"></script>
   <script src="{{ asset('bundles/app/js/raphael.elastic.js') }}"></script>