Tablar Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require takielias/tablar
   

   Run the publisher to set up configurations and views:

   php artisan vendor:publish --provider="Takielias\Tablar\TablarServiceProvider" --tag="tablar-config"
   php artisan vendor:publish --provider="Takielias\Tablar\TablarServiceProvider" --tag="tablar-views"
   

2. Run Migrations:

   php artisan migrate
   

3. First Use Case:

   • Visit /dashboard to see the default dashboard.
   • Use the dynamic menu system to add new routes by defining them in config/tablar.php under the menu key:

     'menu' => [
         [
             'icon' => 'home',
             'label' => 'Dashboard',
             'route' => 'dashboard',
         ],
         [
             'icon' => 'users',
             'label' => 'Users',
             'route' => 'users.index',
             'children' => [
                 [
                     'icon' => 'user-plus',
                     'label' => 'Create User',
                     'route' => 'users.create',
                 ],
             ],
         ],
     ],
     

Where to Look First

• Configuration: config/tablar.php – Customize menu, layout, and dark mode settings.
• Views: resources/views/vendor/tablar/ – Override default layouts or components.
• Routes: routes/web.php – Define routes for your dashboard sections.
• Documentation: Tablar Docs – Official guides and examples.

Implementation Patterns

Usage Patterns

1. Dynamic Menu Generation:

   • Define menu items in config/tablar.php to auto-generate the sidebar navigation.
   • Use nested arrays for hierarchical menus:

     'menu' => [
         [
             'icon' => 'layout',
             'label' => 'Layouts',
             'route' => 'layouts.index',
             'children' => [
                 ['icon' => 'layout-canonical', 'label' => 'Canonical', 'route' => 'layouts.canonical'],
             ],
         ],
     ],
     

   • Dynamically add menu items via middleware or service providers:

     Tablar::menu()->add([
         'icon' => 'settings',
         'label' => 'Settings',
         'route' => 'settings.index',
     ]);
     

2. Layout Customization:

   • Extend the default layout (resources/views/vendor/tablar/layouts/app.blade.php) to add custom headers, footers, or scripts.
   • Use @stack('scripts') to push JavaScript assets:

     @push('scripts')
         <script src="{{ asset('js/custom.js') }}"></script>
     @endpush
     

3. Dark Mode:

   • Toggle dark mode globally via config/tablar.php:

     'dark_mode' => true,
     

   • Or dynamically via JavaScript:

     document.documentElement.classList.toggle('dark');
     

4. Livewire Integration:

   • Use Tablar’s Livewire components (e.g., tablar-card, tablar-table) in your Livewire views:

     <x-tablar-card>
         <x-slot name="title">Users</x-slot>
         <livewire:users-table />
     </x-tablar-card>
     

5. Authentication:

   • Tablar includes Breeze-inspired auth scaffolding. Customize login/register views in resources/views/auth/.
   • Extend the App\Models\User model or AuthServiceProvider for role-based access.

Workflows

1. Adding a New Dashboard Section:

   • Define a route in routes/web.php:

     Route::get('/reports', [ReportController::class, 'index'])->name('reports.index');
     

   • Add the route to the menu in config/tablar.php:

     'menu' => [
         [
             'icon' => 'file-text',
             'label' => 'Reports',
             'route' => 'reports.index',
         ],
     ],
     

   • Create a view at resources/views/reports/index.blade.php and extend the Tablar layout:

     @extends('vendor.tablar.layouts.app')
     @section('content')
         <h1>Reports Dashboard</h1>
     @endsection
     

2. Theming:

   • Override Tabler’s CSS variables in resources/css/app.css:

     @tailwind base;
     @tailwind components;
     @tailwind utilities;
     
     @layer components {
         .dark .tablar-primary {
             --tw-border-opacity: 1;
             border-color: rgb(139 92 246 / var(--tw-border-opacity));
         }
     }
     

   • Publish and compile assets:

     npm run dev
     

3. API-Driven Menus:

   • Fetch menu items dynamically from a database and merge them with the static config:

     $dynamicMenu = Menu::where('user_id', auth()->id())->get()->toArray();
     $mergedMenu = array_merge(config('tablar.menu'), $dynamicMenu);
     Tablar::menu()->set($mergedMenu);
     

Integration Tips

• Laravel Mix/Vite: Ensure your vite.config.js or webpack.mix.js includes Tablar’s CSS/JS:

  mix.postCss('resources/css/app.css', 'public/css', [
      require('tailwindcss'),
  ]);
  

• Multi-Auth: Use middleware to switch between Tablar and non-Tablar routes:

  Route::middleware(['auth', 'tablar'])->group(function () {
      Route::get('/dashboard', [DashboardController::class, 'index']);
  });
  

• Localization: Override Tablar’s language strings in resources/lang/en/tablar.php:

  return [
      'dashboard' => 'My Dashboard',
  ];
  

Gotchas and Tips

Pitfalls

1. View Path Conflicts:

   • If you publish views to a custom path (e.g., resources/views/tablar/), ensure your Blade templates extend the correct layout:

     @extends('tablar::layouts.app')  // Note the namespace
     

   • Fix: Set 'views_path' => 'resources/views/tablar' in config/tablar.php.

2. Dark Mode Toggle Issues:

   • If dark mode doesn’t persist after page reload, ensure you’re using Laravel’s session or cookies to store the preference:

     // In a middleware or controller
     if (request()->has('dark_mode')) {
         session()->put('dark_mode', request('dark_mode') === 'true');
     }
     

   • Fix: Add this to your layout:

     @if (session('dark_mode'))
         <script>
             document.documentElement.classList.add('dark');
         </script>
     @endif
     

3. Menu Item Highlighting:

   • Active menu items rely on route matching. If a child route doesn’t highlight its parent, manually set the active flag:

     'menu' => [
         [
             'icon' => 'users',
             'label' => 'Users',
             'route' => 'users.index',
             'active' => request()->is('users/*'),
             'children' => [...],
         ],
     ],
     

4. Asset Compilation:

   • Tablar uses Tailwind CSS. If your custom CSS breaks the layout, ensure you’re not overriding critical classes (e.g., .dark, .tablar-*).
   • Fix: Use @layer in your CSS to target specific Tailwind variants:

     @layer components {
         .dark .sidebar {
             background-color: #1e293b;
         }
     }
     

5. Livewire Conflicts:

   • If Livewire components don’t render correctly, ensure you’ve included Tablar’s Livewire scripts:

     @livewireScripts
     @stack('scripts')
     

   • Fix: Add this to your layout file.

Debugging

1. Menu Not Updating:

   • Clear the config cache:

     php artisan config:clear
     

   • Check for typos in route names or menu definitions.

2. Dark Mode Not Applying:

   • Inspect the <html> element to confirm the dark class is present.
   • Check for JavaScript errors in the console that might prevent the toggle from working.

3. Blade Components Not Found:

   • Ensure you’re using the correct namespace for components (e.g., <x-tablar::card> vs. <x-tablar-card>).
   • Fix: Publish the views and check the resources/views/vendor/tablar/components directory.

Config Quirks

1. Sticky Header:
   • Enable/disable the sticky header via config:

     'sticky_header' => true,