Timelinejs Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (recommended):

   composer require chub/timelinejs-bundle
   

   (Note: The README mentions Symfony2, but this package works with Symfony 3+ via Composer.)

2. Enable the Bundle: Add to config/bundles.php:

   ChubProduction\TimelineJSBundle\ChubProductionTimelineJSBundle::class => ['all' => true],
   

3. First Use Case: Generate a timeline JSON file in src/Resources/public/timeline/ (e.g., events.json):

   {
     "events": [
       {
         "text": {"headline": "Event 1", "text": "Description..."},
         "start_date": {"year": 2023, "month": 1, "day": 1}
       }
     ]
   }
   

   Render in a Twig template:

   {{ timelinejs_render('bundles/yourbundle/timeline/events.json') }}
   

Implementation Patterns

Core Workflow

1. JSON Generation:

   • Store timeline data as JSON files in src/Resources/public/timeline/ (or a custom path via config).
   • Use Symfony’s Asset component to reference files:

     {{ asset('timeline/events.json') }}
     

2. Dynamic Data:

   • Fetch data from Doctrine/DBAL and convert to JSON:

     // Controller
     $events = $entityManager->getRepository(Event::class)->findAll();
     $json = json_encode(['events' => array_map(function($e) {
         return [
             'text' => ['headline' => $e->title, 'text' => $e->description],
             'start_date' => ['year' => $e->year, 'month' => $e->month, 'day' => $e->day]
         ];
     }, $events)]);
     file_put_contents($this->getParameter('timelinejs.path').'/dynamic.json', $json);
     

3. Twig Integration:

   • Use the timelinejs_render Twig function to embed timelines:

     {% timelinejs_render('timeline/dynamic.json', {
         'height': '500px',
         'lang': 'en',
         'css': 'https://cdn.example.com/timeline.css'
     }) %}
     

Advanced Patterns

• Event Subscribers: Listen for kernel.request to dynamically generate timelines:

  // EventSubscriber
  public function onKernelRequest(GetResponseEvent $event)
  {
      if ($event->isMasterRequest() && $event->getRequest()->getPathInfo() === '/timeline') {
          $json = $this->generateTimelineJson();
          $response = new Response($json, 200, ['Content-Type' => 'application/json']);
          $event->setResponse($response);
      }
  }
  

• Asset Versioning: Override the bundle’s asset path in config/packages/chub_production_timelinejs.yaml:

  chub_production_timelinejs:
      path: '%kernel.project_dir%/public/timelines'
      version: 'v1'  # Adds cache-busting query string
  

Gotchas and Tips

Common Pitfalls

1. Symfony2 vs. Symfony Flex:

   • The bundle assumes Symfony2’s deps file. For Symfony 3+/Flex, use Composer and ignore the registerNamespaces step.
   • If using Flex, ensure config/bundles.php is the correct registration point.

2. JSON Validation: TimelineJS is strict about JSON structure. Validate with:

   jsonlint.com  # Paste your JSON here
   

   Example error: Missing events array or invalid start_date format.

3. Asset Paths:

   • Hardcoding paths (e.g., ../vendor/...) breaks when moving projects. Use Symfony’s asset() helper or bundle config.

4. Caching:

   • TimelineJS caches generated HTML. Clear cache after dynamic updates:

     php bin/console cache:clear
     

Debugging Tips

• Check Generated HTML: Inspect the rendered <div id="timeline-embed"> in the browser. If empty, verify:

  • The JSON file exists at the configured path.
  • The JSON is valid and matches TimelineJS’s schema.
  • No JavaScript errors (open DevTools → Console).

• Log JSON Generation: Add debug logs in your controller/subscriber:

  $this->logger->debug('Timeline JSON:', ['data' => $json]);
  

Extension Points

1. Custom TimelineJS Config: Override default settings in Twig:

   {% timelinejs_render('events.json', {
       'theme': 'dark',
       'start_at_end': true,
       'hash_tags': ['#project']
   }) %}
   

   (See TimelineJS config options.)

2. Event Twig Extensions: Create a custom Twig extension to generate timelines from entities:

   // src/Twig/Extension/TimelineExtension.php
   class TimelineExtension extends \Twig\Extension\AbstractExtension
   {
       public function getFunctions()
       {
           return [
               new \Twig\TwigFunction('timeline_from_events', [$this, 'renderFromEvents']),
           ];
       }
   
       public function renderFromEvents(array $events)
       {
           // Convert entities to JSON and render
       }
   }
   

   Usage in Twig:

   {{ timeline_from_events(events) }}
   

3. Localization: Set the lang parameter in timelinejs_render to support non-English timelines:

   {% timelinejs_render('events.json', {'lang': 'es'}) %}
   

4. Testing: Mock the TimelineJSTwigExtension in PHPUnit:

   $twig = new \Twig\Environment($loader);
   $twig->addExtension(new \ChubProduction\TimelineJSBundle\Twig\TimelineExtension(
       $this->createMock(\ChubProduction\TimelineJSBundle\TimelineJSBundle::class)
   ));