Tablar Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require takielias/tablar
   

   Run migrations and publish assets:

   php artisan migrate
   npm install && npm run dev
   

2. First Dashboard View:

   • Access /dashboard (default route). The package auto-generates a dark-mode dashboard with a dynamic sidebar menu.
   • Customize the menu by editing config/tablar.php under the menu key. Example:

     'menu' => [
         'Dashboard' => 'home',
         'Users' => [
             'text' => 'Users',
             'icon' => 'users',
             'route' => 'users.index',
         ],
     ],
     

3. First Page Integration:

   • Create a controller method (e.g., UsersController@index) and return a view:

     return view('users.index', ['users' => User::all()]);
     

   • Use Tablar’s built-in components in your Blade view:

     <x-tablar::card>
         <x-slot name="title">User Management</x-slot>
         <x-tablar::table>
             <x-tablar::thead>
                 <x-tablar::th>Name</x-tablar->th>
                 <x-tablar::th>Email</x-tablar->th>
             </x-tablar::thead>
             <x-tablar::tbody>
                 @foreach($users as $user)
                     <x-tablar::tr>
                         <x-tablar::td>{{ $user->name }}</x-tablar->td>
                         <x-tablar::td>{{ $user->email }}</x-tablar->td>
                     </x-tablar::tr>
                 @endforeach
             </x-tablar::tbody>
         </x-tablar::table>
     </x-tablar::card>
     

Where to Look First

• Configuration: config/tablar.php (menu, dark mode toggle, layout settings).
• Blade Components: resources/views/vendor/tablar/ (card, table, alerts, etc.).
• Routes: routes/web.php (default /dashboard route).
• Livewire Support: app/Http/Livewire/ (if using Livewire).

Implementation Patterns

Dynamic Menu Generation

Workflow:

1. Define menu items in config/tablar.php:

   'menu' => [
       'Analytics' => [
           'icon' => 'chart-bar',
           'route' => 'analytics.index',
           'children' => [
               'Reports' => 'reports.index',
               'Metrics' => 'metrics.index',
           ],
       ],
   ],
   

2. Nested Routes: Use dot notation for child routes (e.g., analytics.reports).
3. Active State: The package auto-highlights the active menu item based on the current route.

Integration Tip:

• For multi-tenancy, dynamically load menu items from a database:

  'menu' => collect(auth()->user()->roles)->mapWithKeys(function ($role) {
      return [
          $role->name => [
              'icon' => $role->icon,
              'route' => route('role.dashboard', $role->id),
          ],
      ];
  })->toArray(),
  

Dark Mode Toggle

Pattern:

1. Enable dark mode in config/tablar.php:

   'dark_mode' => true,
   

2. User Preference: Store user preference in the database (e.g., preferences table) and sync it:

   // In a middleware or service provider
   if (auth()->check()) {
       $user = auth()->user();
       config(['tablar.dark_mode' => $user->preferences->dark_mode ?? false]);
   }
   

3. Toggle Button: Use the built-in toggle component:

   <x-tablar::dark-mode-toggle />
   

Layout Customization

Patterns:

1. Override Default Layout:
   • Publish views: php artisan vendor:publish --tag=tablar-views.
   • Modify resources/views/layouts/tablar.blade.php.
2. Condensed Layout:

   // config/tablar.php
   'layout' => 'condensed',
   

3. Custom Views Path:

   'views_path' => 'resources/views/custom/tablar',
   

Integration Tip:

• Use Blade includes to extend Tablar’s layout without forking:

  @extends('vendor.tablar.layouts.app')
  @section('sidebar')
      @parent
      <!-- Custom sidebar items -->
      <x-tablar::menu-item icon="settings" route="settings.index" />
  @endsection
  

Livewire Integration

Workflow:

1. Create a Livewire component:

   php artisan make:livewire UsersTable
   

2. Use Tablar’s Livewire-ready components:

   <x-tablar::livewire-table>
       <x-slot name="header">
           <h3 class="text-xl font-semibold">Users</h3>
       </x-slot>
       <livewire:users-table />
   </x-tablar::livewire-table>
   

3. Style Livewire components with Tabler’s CSS classes.

Tip:

• Extend TablarComponent for consistent styling:

  use Takielias\Tablar\Facades\Tablar;
  
  class UsersTable extends Component {
      use TablarComponent;
  
      public function render() {
          return view('livewire.users-table', [
              'users' => User::paginate(10),
          ]);
      }
  }
  

Error Handling

Pattern:

1. Custom error pages are auto-integrated. Override them by publishing views:

   php artisan vendor:publish --tag=tablar-views --force
   

2. Modify resources/views/errors/404.blade.php to use Tablar’s layout:

   @extends('vendor.tablar.layouts.error')
   @section('title', 'Page Not Found')
   

Gotchas and Tips

Pitfalls

1. Menu Item Activation:

   • Issue: Child menu items don’t highlight as active.
   • Fix: Ensure child routes use dot notation (e.g., analytics.reports) and match the config structure exactly.
   • Debug: Check dd(config('tablar.menu')) to verify the structure.

2. Dark Mode Persistence:

   • Issue: Dark mode resets on page reload.
   • Fix: Store the preference in the database and sync it on auth (see Dark Mode Toggle).

3. Asset Compilation:

   • Issue: Vite assets fail to compile.
   • Fix: Ensure Node.js is v20.19+ and run:

     npm install
     npm run dev
     

   • Debug: Check resources/js/tablar.js for errors.

4. Livewire Conflicts:

   • Issue: Livewire components render without Tabler styles.
   • Fix: Include Tablar’s CSS in your Livewire component:

     @push('styles')
         <link href="{{ asset('css/tablar.css') }}" rel="stylesheet">
     @endpush
     

Debugging Tips

1. Menu Debugging:

   • Dump the menu config to verify structure:

     dd(config('tablar.menu'));
     

   • Check active route matching with:

     dd(request()->route()->getName());
     

2. Layout Issues:

   • Clear cached views:

     php artisan view:clear
     

   • Check for conflicting CSS by inspecting the <head> section.

3. Dark Mode Toggle:

   • Verify the toggle button is included in your layout:

     <x-tablar::dark-mode-toggle />
     

   • Check for JavaScript errors in the browser console.

Extension Points

1. Custom Components:

   • Create a new Blade component in resources/views/vendor/tablar/components/ and extend the namespace:

     // config/tablar.php
     'components_path' => 'resources/views/vendor/tablar/components',
     

2. Dynamic Menu from Database:

   • Override the menu resolver in a service provider:

     Tablar::macro('resolveMenu', function () {
         return UserMenu::where('user_id', auth()->id())->get()->toArray();
     });
     

3. Custom Icons:

   • Extend Tabler’s icon set by adding custom SVG files to public/vendor/tabler/icons/ and reference them in the menu:

     'icon' => 'custom-icon', // Points to public/vendor/tabler/icons/custom-icon.svg
     

4. Multi-Language Support:

   • Override menu labels dynamically:

     'menu' => [
         __('Dashboard') => 'home',
         __('Users') => [
             'text' => __('User Management'),
             'icon' => 'users',
         ],
     ],
     

Configuration Quirks

1. Views Path:
   • Setting