Advanced Controls Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require allyoullneed/advanced-controls
   

   Publish the package assets (if needed):

   php artisan vendor:publish --provider="Allyoullneed\AdvancedControls\AdvancedControlsServiceProvider" --tag="public"
   

2. First Use Case: Replace a basic Blade form input with an enhanced component. For example, swap a standard <select> for the Select component:

   @select([
       'name' => 'category',
       'label' => 'Select a category',
       'options' => [
           'tech' => 'Technology',
           'design' => 'Design',
           'business' => 'Business',
       ],
       'wire:model' => 'categoryId',
   ])
   

3. Where to Look First:

   • Documentation: Visit allyoullneed.com for component-specific guides.
   • Source Code: Browse the resources/views/vendor/advanced-controls directory for Blade templates.
   • Livewire Integration: Check the app/Http/Livewire directory for example components if using Livewire.

Implementation Patterns

Common Workflows

1. Form Enhancement: Replace standard form elements with interactive components:

   @checkbox([
       'name' => 'subscribe',
       'label' => 'Subscribe to newsletter',
       'wire:model' => 'newsletter',
       'labelPosition' => 'right',
   ])
   

2. Dynamic UI with Livewire: Use wire:model for two-way binding:

   @tabs([
       'wire:model' => 'activeTab',
       'tabs' => [
           ['name' => 'home', 'label' => 'Home'],
           ['name' => 'profile', 'label' => 'Profile'],
       ],
   ])
   

3. Conditional Rendering: Combine with Blade @if directives:

   @if(auth()->check())
       @avatar([
           'src' => auth()->user()->avatar,
           'name' => auth()->user()->name,
           'size' => 'md',
       ])
   @endif
   

4. Configuration Overrides: Customize global settings in config/advanced-controls.php:

   'icons' => [
       'set' => 'heroicons',
       'cdn' => 'https://cdn.jsdelivr.net/npm/heroicons@2.0.18',
   ],
   

5. Chart Integration: Load charts dynamically with CDN configuration:

   @chart([
       'type' => 'line',
       'data' => $chartData,
       'options' => ['responsive' => true],
       'cdn' => 'chartjs',
   ])
   

Integration Tips

• Livewire Components: Extend existing Livewire classes to use these components:

  public function mount() {
      $this->activeTab = 'home';
  }
  

• Alpine.js: Some components support Alpine.js attributes (e.g., @click).
• Validation: Leverage Livewire’s validation with error styling:

  @error('categoryId')
      <div class="error-message">{{ $message }}</div>
  @enderror
  

Gotchas and Tips

Pitfalls

1. Component Registration:

   • Ensure components are registered globally by checking AdvancedControlsServiceProvider. If using Artisan commands, verify the fix from PR #12 is applied.

2. Livewire Model Binding:

   • For Select, Tabs, and other components, ensure wire:model is correctly bound to a Livewire property (fixed in PR #10).

3. Icon Dependencies:

   • Default icons may not load if the CDN is unreachable. Fallback to local assets or configure a custom icon set in config/advanced-controls.php.

4. Chart Loading:

   • Charts require JavaScript. Ensure the CDN is loaded (configured in config/advanced-controls.php) and the component is rendered after the DOM is ready.

5. Alpine.js Conflicts:

   • Some components (e.g., Rating) removed Alpine.js dependencies in PR #1. Avoid mixing Alpine.js directives unless documented.

Debugging

• Missing Styles: Publish assets if using custom CSS:

  php artisan vendor:publish --tag="public"
  

• Component Not Rendering: Check for typos in component names or missing attributes. Use @dd() to inspect passed data:

  @dd($componentData)
  

• Livewire Errors: Verify wire:model properties exist in the Livewire component class.

Tips

1. Customization:

   • Override Blade templates in resources/views/vendor/advanced-controls to tailor components to your theme.

2. Performance:

   • Lazy-load heavy components (e.g., charts) using Alpine.js or JavaScript:

   <div x-data="{ loadChart: false }" x-init="loadChart = true">
       @chart([...])
   </div>
   

3. Accessibility:

   • Add aria-* attributes manually if components lack them:

   @select([...])
       <span aria-hidden="true">↓</span>
   @endselect
   

4. Testing:

   • Test components in isolation using Livewire’s render() method:

   $this->render();
   

   Capture Blade output with ob_start() and ob_get_clean().

5. Extensions:

   • Create custom components by extending the base class in app/View/Components/AdvancedControlsComponent.php. Example:

   namespace App\View\Components;
   use Allyoullneed\AdvancedControls\AdvancedControlsComponent;
   
   class CustomSelect extends AdvancedControlsComponent {
       public $options;
       // ...
   }