Laravel Popper Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require andcarpi/laravel-popper
   

   For Laravel ≥5.5, skip manual service provider/facade registration (auto-discovery handles it).

2. Include Assets: Add @include('popper::assets') before </body> in your Blade view (or master layout) to load Popper.js/Tippy.js dependencies.

3. First Tooltip: Use the facade directly in an HTML element:

   <button {{ Popper::pop('Hello!') }}>Hover Me</button>
   

   Or via the Blade directive:

   <span @popper("Hello!")>Hover Text</span>
   

Implementation Patterns

Core Workflows

1. Dynamic Tooltips: Pass dynamic content (e.g., from controllers) to tooltips:

   <a href="{{ route('profile') }}" {{ Popper::pop("Welcome, {$user->name}!") }}>
     Profile
   </a>
   

2. Reusable Components: Create a Blade component for consistent tooltips:

   @component('components.tooltip-button', ['text' => 'Save', 'tip' => 'Save changes'])
   @endcomponent
   

   <!-- components/tooltip-button.blade.php -->
   <button {{ Popper::pop($tip) }}>{{ $text }}</button>
   

3. Conditional Tooltips: Use Blade logic to toggle tooltips:

   @if(auth()->check())
     <button {{ Popper::pop('Logged in as ' . auth()->user()->name) }}>
       User Menu
     </button>
   @endif
   

4. Asset Optimization:

   • Lazy Loading: Include @include('popper::assets') only in views needing tooltips (not globally).
   • CDN: Replace local assets with CDN links in resources/views/vendor/popper/assets.blade.php for production.

5. Integration with JavaScript: Trigger tooltips programmatically via JavaScript:

   document.querySelector('[data-popper]')._tippy.enable();
   

Gotchas and Tips

Pitfalls

1. Asset Loading Order:

   • Issue: Tooltips may not render if @include('popper::assets') is placed after the closing </body> tag.
   • Fix: Always include assets before </body>.

2. Duplicate Assets:

   • Issue: Multiple @include('popper::assets') calls load Popper.js/Tippy.js multiple times, increasing bundle size.
   • Fix: Use a single @include in a master layout or check for existing assets with @if(!app()->bound('popper.assets.loaded')).

3. Blade Directive Scope:

   • Issue: @popper directive may not work in non-Blade templates (e.g., .html files).
   • Fix: Use the facade ({{ Popper::pop() }}) for non-Blade files or preprocess templates.

4. Conflicts with Other Libraries:

   • Issue: Tippy.js may conflict with other tooltip libraries (e.g., Bootstrap Tooltips).
   • Fix: Use unique data-tippy attributes or namespace tooltips:

     {{ Popper::pop('Tip', ['theme' => 'my-theme']) }}
     

5. Deprecated Methods:

   • Issue: The package hasn’t been updated since 2019; some Tippy.js features may not work.
   • Fix: Manually extend Tippy.js options via JavaScript:

     tippy.defaults.animation = 'fade';
     

Debugging Tips

1. Check Console for Errors:

   • Open browser dev tools (F12) to verify Popper.js/Tippy.js loads without errors (e.g., 404 for assets).

2. Inspect Rendered HTML:

   • Tooltips rely on data-popper attributes. Verify they’re rendered correctly in the DOM.

3. Disable Other Tooltips:

   • Temporarily disable Bootstrap/other tooltip libraries to isolate conflicts:

     $(document).off('mouseenter', '[data-toggle="tooltip"]');
     

Extension Points

1. Custom Tippy.js Options: Override default Tippy.js settings via the facade:

   {{ Popper::pop('Custom Tip', [
       'theme' => 'light',
       'delay' => 200,
       'arrow' => true
   ]) }}
   

2. Global Configuration: Publish the config file (if available) to customize defaults:

   php artisan vendor:publish --provider="andcarpi\Popper\PopperServiceProvider"
   

   (Note: The package may not include a publishable config; check the repo for updates.)

3. Extend with JavaScript: Add custom Tippy.js plugins or modify behavior post-render:

   document.addEventListener('DOMContentLoaded', () => {
       tippy('[data-popper]', {
           content: 'Dynamic content!',
           onShow(instance) { console.log('Tooltip shown!'); }
       });
   });
   

4. Localization: Use Laravel’s localization features to support multi-language tooltips:

   {{ Popper::pop(__('messages.tooltip')) }}