Naptab Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hdaklue/naptab
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Hdaklue\NapTab\NapTabServiceProvider" --tag="config"
   

2. Basic Blade Integration:

   @napTab
       @napTabItem('Dashboard', route('dashboard'))
           <!-- Content loads only when tab is clicked -->
           <p>Dashboard content here</p>
       @endNapTabItem
   
       @napTabItem('Profile', route('profile'))
           <p>Profile content here</p>
       @endNapTabItem
   @endNapTab
   

3. First Use Case: Replace a traditional tab system (e.g., Alpine.js + manual lazy loading) with @napTab for a dashboard with heavy backend operations (e.g., analytics, user management). Only load the active tab’s data on click.

Implementation Patterns

Core Workflows

1. Lazy-Loaded Tab Content:

   • Use @napTabItem directives to wrap content that should load only when activated.
   • Example: Multi-step forms or complex reports where initial page load would be slow.

2. Dual-Level Hooks:

   • Container Hooks: Inject content around the entire tab container (e.g., global filters, breadcrumbs).

     @napTab
         @napTabContainerHook
             <div class="filters">...</div>
         @endNapTabContainerHook
     @endNapTab
     

   • Tab-Specific Hooks: Add content before/after individual tabs (e.g., tab-specific toolbars).

     @napTabItem('Settings')
         @napTabItemHook
             <button class="edit-tab">...</button>
         @endNapTabItemHook
     @endNapTabItem
     

3. Dynamic Tab Generation:

   • Fetch tabs via Livewire properties and render dynamically:

     public $tabs = [
         ['name' => 'Orders', 'route' => 'orders.index'],
         ['name' => 'Reports', 'route' => 'reports.index'],
     ];
     

     @foreach($tabs as $tab)
         @napTabItem($tab['name'], $tab['route'])
             {{ $slot }}
         @endNapTabItem
     @endforeach
     

4. Sidebar/Aside Layouts:

   • Use direction="aside" for dashboard-style layouts:

     @napTab(direction="aside")
         @napTabItem('Projects')
             <!-- Content -->
         @endNapTabItem
     @endNapTab
     

Integration Tips

• Livewire Components:

  • Embed @napTab inside a Livewire component to manage tab state server-side:

    <livewire:admin-dashboard>
        @napTab
            @napTabItem('Users')
                <livewire:user-manager />
            @endNapTabItem
        @endNapTab
    </livewire:admin-dashboard>
    

  • Use wire:model to sync active tab state across components.

• Route-Based Tabs:

  • Leverage Laravel routes for deep linking and bookmarking:

    @napTabItem('Invoices', route('invoices.index', ['status' => 'pending']))
    

• Conditional Tabs:

  • Hide/show tabs based on user roles/permissions:

    @if(auth()->user()->isAdmin())
        @napTabItem('Admin Tools', route('admin.tools'))
    @endif
    

Gotchas and Tips

Pitfalls

1. Livewire Conflict:

   • If using Livewire, ensure @napTab is outside the Livewire component’s root <div>. Nested Livewire components may cause hydration issues.
   • Fix: Move @napTab to the parent component or use wire:ignore on the tab container.

2. Lazy-Loading Overhead:

   • Tabs with no content (empty @napTabItem) will still render a clickable tab but may cause confusion.
   • Tip: Add a minimal placeholder (e.g., <div class="p-4">Loading...</div>) to avoid empty UI.

3. Route Caching:

   • If using route-based tabs, clear route cache (php artisan route:clear) after adding new routes to avoid stale tab links.

4. CSS/JS Dependencies:

   • NapTab relies on Alpine.js for interactivity. Ensure it’s loaded before the @napTab directive:

     @vite(['resources/js/app.js']) <!-- Ensure Alpine is included -->
     

Debugging

• Tab Not Activating:

  • Check for JavaScript errors in the browser console. NapTab uses Alpine.js events (@nap-tab:activate).
  • Debug: Temporarily add x-data to the @napTab directive to inspect state:

    @napTab(x-data="{ debug: true }")
    

• Content Not Loading:

  • Verify the tab’s route/controller returns valid content. Use dd() in the controller to test.
  • Tip: Add a wire:loading state to the tab content for better UX:

    @napTabItem('Data')
        <div wire:loading>Loading data...</div>
        {{ $slot }}
    @endNapTabItem
    

Configuration Quirks

1. Default Active Tab:

   • Set via config('naptab.default_active_tab') (e.g., 'dashboard'). Useful for multi-page forms where the last active tab should persist.
   • Note: Override per-instance with active-tab="profile" in the @napTab directive.

2. Transition Effects:

   • Disable animations (e.g., for SPAs) by setting transition="none":

   @napTab(transition="none")
   

3. Custom Events:

   • Listen to tab activation events in Alpine.js:

   <div x-data @nap-tab:activate="console.log('Tab activated')"></div>
   

Extension Points

1. Custom Styling:

   • Override default classes via class attribute:

     @napTab(class="bg-gray-100")
     

   • Extend with Tailwind/CSS:

     .nap-tab--active { /* Custom active tab styles */ }
     

2. Server-Side Logic:

   • Use Livewire to modify tab behavior dynamically:

   public function getTabsProperty() {
       return auth()->user()->canAccess('reports')
           ? [...$this->defaultTabs, ['name' => 'Reports', 'route' => 'reports']]
           : $this->defaultTabs;
   }
   

3. Third-Party Integration:

   • Combine with Laravel Nova for admin panels:

     <nova-layout>
         @napTab
             @napTabItem('Resources', nova-index)
                 {{ Nova::resources() }}
             @endNapTabItem
         @endNapTab
     </nova-layout>