Blade Elements Ui Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require renatovdemoura/blade-elements-ui
   

   Add the service provider to config/app.php under providers:

   RenatoVdemoura\BladeElementsUI\BladeElementsUIServiceProvider::class,
   

2. First Use Case Create a simple UI element in a Blade file (e.g., resources/views/components/alert.blade.php):

   @element('alert', [
       'type' => 'success',
       'message' => 'Operation completed successfully!'
   ])
   

   Use it in your Blade template:

   @includeElements(['alert'])
   

3. Basic Configuration Publish the config file (if available) and customize default settings:

   php artisan vendor:publish --provider="RenatoVdemoura\BladeElementsUI\BladeElementsUIServiceProvider"
   

Implementation Patterns

Workflows

1. Component-Based UI

   • Define reusable UI elements (e.g., modals, cards, buttons) as Blade files in resources/views/components/.
   • Example: resources/views/components/card.blade.php

     @element('card', [
         'title' => 'User Profile',
         'content' => 'User details go here...'
     ])
     

   • Include them dynamically:

     @includeElements(['card'])
     

2. Dynamic Data Binding Pass data from controllers or services:

   return view('dashboard', [
       'elements' => [
           'alert' => ['type' => 'warning', 'message' => 'Pending tasks found!']
       ]
   ]);
   

   @includeElements($elements)
   

3. Conditional Rendering Use Blade directives to conditionally include elements:

   @if($showSuccess)
       @includeElements(['alert' => ['type' => 'success', 'message' => 'Success!']])
   @endif
   

Integration Tips

• Laravel Mix/Vite: Ensure your build process doesn’t strip Blade directives. Use @verbatim if needed.
• Livewire/Alpine: Combine with frontend frameworks for interactive elements:

  @element('modal', [
      'title' => 'Confirm Action',
      'content' => 'Are you sure?',
      'wire:model' => 'confirmAction'
  ])
  

• Testing: Mock elements in PHPUnit:

  $this->view->share('elements', ['alert' => ['message' => 'Test']]);
  

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Clear Blade cache after adding new elements:

     php artisan view:clear
     

   • Avoid caching views that use @includeElements dynamically.

2. Namespace Conflicts

   • Ensure component filenames match the @element directive (e.g., alert.blade.php for @element('alert')).
   • Use underscores or hyphens in filenames if needed (e.g., alert-message.blade.php), but adjust the directive accordingly.

3. Data Overwriting

   • Later elements in the array overwrite earlier ones with the same key:

     @includeElements(['alert' => ['type' => 'info'], 'alert' => ['type' => 'error']])
     

     Result: Only the error alert renders.

Debugging

• Missing Elements: Verify the Blade file exists in resources/views/components/ and the directive matches the filename.
• No Output: Check for typos in @element or @includeElements. Use {{ dd($elements) }} to debug passed data.
• Styling Issues: Ensure CSS/JS assets are properly enqueued in the element’s Blade file or a layout.

Extension Points

1. Custom Directives Extend the package by adding global Blade directives in AppServiceProvider:

   Blade::directive('elementIf', function ($expression) {
       return "<?php if({$expression}): ?>@includeElements(['{$expression}'])<?php endif; ?>";
   });
   

   Usage:

   @elementIf($showAlert)
   

2. Element Factories Create a helper class to generate elements programmatically:

   class ElementFactory {
       public static function alert(string $message, string $type = 'info') {
           return ['alert' => compact('message', 'type')];
       }
   }
   

   Usage:

   @includeElements(ElementFactory::alert('Hello!'))
   

3. Event-Based Triggers Use Laravel events to dynamically add elements:

   // In an event listener
   event(new ElementAdded('alert', ['message' => 'Event triggered!']));
   

   @includeElements(app('elements')->get())