Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require orbtui/laravel
   

   Publish the config file (if available):

   php artisan vendor:publish --provider="Orbtui\Laravel\OrbtuiServiceProvider"
   

2. Basic Usage:

   • Integrate with Livewire components by extending Orbtui\Laravel\Components\OrbtuiComponent.
   • Example:

     use Orbtui\Laravel\Components\OrbtuiComponent;
     
     class MyComponent extends OrbtuiComponent
     {
         public function render()
         {
             return view('livewire.my-component');
         }
     }
     

   • Use the @orbtui directive in Blade views to render UI elements:

     @orbtui('button', ['label' => 'Click Me'])
     

3. First Use Case:

   • Replace static buttons with dynamic, fluid UI elements in a Livewire form:

     // In Livewire component
     public function mount()
     {
         $this->ui = [
             'primaryButton' => ['type' => 'button', 'label' => 'Submit', 'icon' => 'check'],
         ];
     }
     

     @orbtui('button', $this->ui['primaryButton'])
     

Implementation Patterns

Core Workflows

1. Dynamic UI Rendering:

   • Use the @orbtui directive to render reusable UI elements (buttons, cards, modals) with dynamic props:

     @orbtui('card', [
         'title' => 'User Profile',
         'content' => 'Welcome, ' . $user->name,
         'actions' => [
             ['type' => 'button', 'label' => 'Edit', 'onClick' => 'editProfile()'],
         ],
     ])
     

2. Livewire Integration:

   • Extend OrbtuiComponent to bind UI states to Livewire properties:

     class Dashboard extends OrbtuiComponent
     {
         public $showModal = false;
         public $modalType = 'success';
     
         public function toggleModal()
         {
             $this->showModal = !$this->showModal;
         }
     }
     

     @orbtui('modal', [
         'visible' => $this->showModal,
         'type' => $this->modalType,
         'title' => 'Confirmation',
         'content' => 'Are you sure?',
     ])
     

3. Theming and Styling:

   • Override default styles via the config/orbtui.php (if published):

     'theme' => [
         'primaryColor' => '#3b82f6',
         'borderRadius' => '0.5rem',
     ],
     

   • Use Tailwind/other CSS frameworks by extending the package’s default classes.

4. Event Handling:

   • Bind UI events to Livewire methods:

     @orbtui('button', [
         'label' => 'Delete',
         'onClick' => '$emit("deleteItem", { id: 123 })',
     ])
     

     protected $listeners = ['deleteItem' => 'handleDelete'];
     

Advanced Patterns

• Conditional Rendering:

  @if ($user->isAdmin)
      @orbtui('button', [
          'label' => 'Admin Actions',
          'type' => 'danger',
          'onClick' => 'showAdminPanel()',
      ])
  @endif
  

• Reusable UI Components: Create a base component for common UI patterns (e.g., AlertComponent):

  class AlertComponent extends OrbtuiComponent
  {
      public $message;
      public $type;
  
      public function render()
      {
          return view('livewire.alert-component');
      }
  }
  

Gotchas and Tips

Common Pitfalls

1. Directive Caching:

   • Ensure @orbtui directives are not cached in Blade views if props change dynamically. Use @verbatim or disable Blade caching during development:

     php artisan view:clear
     

2. Livewire Reactivity:

   • UI updates triggered via @orbtui may not react to Livewire property changes if the directive is static. Use wire:model or $wire events for dynamic updates:

     @orbtui('input', [
         'type' => 'text',
         'value' => $this->inputValue,
         'wire:model' => 'inputValue',
     ])
     

3. Configuration Overrides:

   • If config/orbtui.php is missing, default values may not apply. Publish the config first:

     php artisan vendor:publish --tag=orbtui-config
     

4. JavaScript Conflicts:

   • The package may load its own JS/CSS. Exclude them if using custom builds:

     // config/app.php
     'providers' => [
         // ...
         Orbtui\Laravel\OrbtuiServiceProvider::class,
     ],
     'aliases' => [
         // ...
         'Orbtui' => Orbtui\Laravel\Facades\Orbtui::class,
     ],
     

     Disable auto-registration in OrbtuiServiceProvider if needed.

Debugging Tips

• Inspect Props: Use dd() to debug props passed to @orbtui:

  @php dd(['label' => 'Test', 'onClick' => 'alert("Clicked")']) @endphp
  @orbtui('button', ['label' => 'Test', 'onClick' => 'alert("Clicked")'])
  

• Check Console: Enable JavaScript console logs for UI events:

  window.addEventListener('orbtui:event', (e) => {
      console.log('Orbtui Event:', e.detail);
  });
  

Extension Points

1. Custom Components:

   • Extend the package by creating new component classes in app/Orbtui/Components.
   • Register them in OrbtuiServiceProvider:

     public function boot()
     {
         $this->app->make('orbtui')->registerComponent('custom-card', CustomCardComponent::class);
     }
     

2. Override Views:

   • Publish and modify the package’s views:

     php artisan vendor:publish --tag=orbtui-views
     

   • Override in resources/views/vendor/orbtui/.

3. Add Icons/Assets:

   • Extend the package’s asset pipeline by publishing assets:

     php artisan vendor:publish --tag=orbtui-assets
     

   • Add custom icons or fonts to public/vendor/orbtui/.