Citation Portrait Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the repository to composer.json under "repositories":

   "repositories": {
       "bibsdb/citation-portrait-bundle": {
           "type": "vcs",
           "url": "https://github.com/bibsdb/citation-portrait-bundle"
       }
   }
   

   Require the bundle:

   composer require bibsdb/citation-portrait-bundle
   

2. Enable the Bundle Register in config/bundles.php (Laravel 5.5+) or AppKernel.php (older versions):

   Bibsdb\CitationPortraitBundle\BibsdbCitationPortraitBundle::class => ['all' => true],
   

3. Load Templates Run the template loader command:

   php artisan bibsdb:core:templates:load
   

4. Admin Setup Enable the template in the admin panel (check the bundle’s documentation for UI-specific steps).

First Use Case: Embedding a Citation Portrait

Use the bundle’s Twig template to embed a video in a view:

{{ bibsdb_citation_portrait({
    'video_id': 'YOUR_VIDEO_ID',
    'width': 640,
    'height': 360
}) }}

Replace YOUR_VIDEO_ID with a valid ID from citation-portrait.com.

Implementation Patterns

Workflow: Integrating with Existing Views

1. Dynamic Video IDs Pass video IDs dynamically from a database or API:

   // Controller
   return view('show', ['videoId' => $paper->citationPortraitId]);
   

   {{ bibsdb_citation_portrait({
       'video_id': videoId,
       'autoplay': false
   }) }}
   

2. Custom Styling Override the default template by extending the base template:

   {% extends 'BibsdbCitationPortraitBundle::default.html.twig' %}
   {% block video_container %}
       <div class="custom-video-wrapper">
           {{ parent() }}
       </div>
   {% endblock %}
   

3. Conditional Rendering Use Twig logic to show/hide based on data:

   {% if paper.hasCitationPortrait %}
       {{ bibsdb_citation_portrait({'video_id': paper.citationPortraitId}) }}
   {% endif %}
   

Integration Tips

• Asset Management The bundle relies on player.js from CitationPortrait. Ensure your webpack.mix.js or asset pipeline includes:

  mix.js('node_modules/citation-portrait/player.js', 'public/js');
  

  Or use a CDN:

  <script src="https://cdn.citation-portrait.com/player.js"></script>
  

• Laravel Mix/Webpack If using Laravel Mix, alias the player in webpack.mix.js:

  mix.alias({
      'citation-portrait': path.resolve(__dirname, 'node_modules/citation-portrait/player.js')
  });
  

• API-Driven IDs Fetch video IDs via an API (e.g., from a research paper database) and pass them to the template:

  $videoId = $apiClient->getCitationPortraitId($paper->doi);
  

Gotchas and Tips

Pitfalls

1. Ads and Controls

   • Issue: Ads/controls appear unless the video is from a PLUS account on citation-portrait.com.
   • Fix: Ensure video IDs are sourced from a paid account or contact CitationPortrait for a developer license.

2. Template Loading

   • Issue: Forgetting to run php artisan bibsdb:core:templates:load after installation.
   • Fix: Always run the command post-installation. Check logs if templates fail to load.

3. Missing JavaScript

   • Issue: Player fails to initialize due to missing player.js.
   • Fix: Verify the JS file is loaded (check browser console for 404 errors).

4. CORS Restrictions

   • Issue: Video fails to load if hosted on a subdomain or different origin.
   • Fix: Use a proxy or ensure CORS headers are configured on the CitationPortrait server.

Debugging

• Check Console Logs Open browser dev tools (F12) to inspect errors like:

  Uncaught ReferenceError: CitationPortraitPlayer is not defined
  

  → Indicates player.js is missing or loaded after the template.

• Validate Video IDs Test IDs manually on citation-portrait.com to confirm they work outside Laravel.

• Clear Cache After template updates, clear Laravel’s cache:

  php artisan cache:clear
  php artisan view:clear
  

Extension Points

1. Custom Player Options Extend the player config by overriding the Twig block:

   {% block player_options %}
       {{ parent() }}
       {{ {
           'customOption': true,
           'volume': 0.5
       }|json_encode|raw }}
   {% endblock %}
   

2. Event Listeners Hook into the bundle’s events (if documented) to modify behavior, e.g., post-video-load actions.

3. Localization Override translation files in resources/lang/vendor/bibsdb to customize labels (e.g., "Play Video").

Pro Tips

• Batch Processing Use the bundle in loops for research paper galleries:

  {% for paper in papers %}
      {{ bibsdb_citation_portrait({'video_id': paper.videoId, 'width': 400 }) }}
  {% endfor %}
  

• Fallback Content Provide fallback HTML/placeholders if the video fails to load:

  {% set portrait = bibsdb_citation_portrait({'video_id': videoId }) %}
  {% if portrait is empty %}
      <div class="fallback">Video unavailable. View on {{ citationPortraitLink(videoId) }}.</div>
  {% else %}
      {{ portrait }}
  {% endif %}
  

• Performance Lazy-load videos for better page performance:

  {{ bibsdb_citation_portrait({
      'video_id': videoId,
      'loading': 'lazy'
  }) }}