Fgx Laravel Package

Getting Started

Minimal Steps

1. Installation: Run composer require talalalmrka/fgx in your Laravel project.
2. Publish Config: Execute php artisan vendor:publish --tag=fgx-config to generate the config file (though minimal config is required).
3. First Use Case: Insert a basic alert in a Blade template:

   <fgx:alert type="success" message="Welcome to your dashboard!" />
   

4. Verify: Check the rendered output in your browser to confirm the component appears as expected.

Where to Look First

• README.md: Focus on the Usage section for component examples and props.
• Published Config: Inspect config/fgx.php for customization options (e.g., default styles, class prefixes).
• Blade Directives: Check if the package includes any Blade directives (e.g., @fgxStyle) for global styling.

Implementation Patterns

Core Workflows

1. Component Integration:

   • Blade Templates: Use <fgx:component> syntax for all provided components (e.g., <fgx:button>).
   • Dynamic Props: Pass props via Blade syntax (e.g., :disabled="true", @click="handleClick").
   • Slot Content: Leverage slots for custom content (if supported; check component docs):

     <fgx:card>
         <h3>Custom Title</h3>
         <p>Custom content</p>
     </fgx:card>
     

2. Reusable UI Logic:

   • Shared Styles: Use the package’s default styles or extend them via config/fgx.php:

     'styles' => [
         'prefix' => 'fgx-', // Customize class prefixes
         'theme' => 'light', // e.g., 'dark', 'custom'
     ],
     

   • Component Composition: Combine components for complex UIs (e.g., Card + Table + Button for a dashboard tile).

3. Form Handling:

   • Input Component: Use <fgx:input> for forms with built-in validation feedback:

     <fgx:input
         name="email"
         label="Email"
         :errors="$errors->get('email')"
         required
     />
     

   • Dropdowns: For select inputs, use <fgx:dropdown> with options:

     <fgx:dropdown
         name="category"
         :options="$categories"
         label="Select Category"
     />
     

4. State Management:

   • Modals: Use <fgx:modal> for dynamic content (e.g., confirmations, forms):

     <fgx:modal wire:model="isModalOpen">
         <h3>Confirm Action</h3>
         <p>Are you sure?</p>
         <template #footer>
             <fgx:button type="primary" @click="confirmAction">Yes</fgx:button>
         </template>
     </fgx:modal>
     

   • Alerts: Trigger alerts from controllers or Livewire components:

     // In a Livewire component
     public function showSuccess() {
         $this->dispatch('alert', type: 'success', message: 'Saved!');
     }
     

5. Livewire Integration:

   • Two-Way Binding: Bind props to Livewire properties:

     <fgx:input wire:model="form.email" />
     

   • Event Listeners: Listen for component events (if supported):

     <fgx:button @click="$wire.submitForm">Submit</fgx:button>
     

6. Testing:

   • Unit Tests: Test components in isolation using Laravel’s Blade testing helpers:

     $this->blade('<fgx:alert type="success" message="Test" />')
          ->assertSee('Operation completed successfully!');
     

   • Feature Tests: Test components in context (e.g., with Livewire):

     $this->livewire(ModalComponent::class)
          ->assertSee('Confirm Action');
     

Gotchas and Tips

Pitfalls

1. Missing Config:

   • Issue: Components may render incorrectly if vendor:publish is skipped.
   • Fix: Run php artisan vendor:publish --tag=fgx-config and review config/fgx.php.

2. Prop Validation:

   • Issue: Undefined props (e.g., type="invalid") may throw errors or render unpredictably.
   • Fix: Always use valid props (e.g., type="success|error|warning|info"). Check the Usage section for allowed values.

3. Caching:

   • Issue: Changes to Blade components may not reflect immediately due to caching.
   • Fix: Clear views and config caches:

     php artisan view:clear
     php artisan config:clear
     

4. Slot Limitations:

   • Issue: Some components may not support slots or may require specific slot names (e.g., #footer).
   • Fix: Refer to individual component docs (e.g., <fgx:modal>) for slot usage.

5. Livewire Conflicts:

   • Issue: Livewire’s @this or $wire directives may conflict with component props.
   • Fix: Prefix Livewire directives or use unique IDs:

     <fgx:input wire:model.defer="form.email" />
     

6. Asset Loading:

   • Issue: Custom styles or scripts may not load if not properly registered.
   • Fix: Use the package’s provided Blade directives (if available) or manually include assets:

     @fgxStyles
     @fgxScripts
     

Debugging Tips

1. Inspect Rendered HTML:

   • Use browser dev tools to verify component structure and classes. Look for missing or extra classes (e.g., fgx-alert fgx-alert--success).

2. Check for Deprecations:

   • Monitor the package’s GitHub for breaking changes or deprecations (e.g., prop name changes).

3. Fallback Classes:

   • If a component fails to render, manually apply its default classes (e.g., .alert, .alert-success) to debug.

4. Log Props:

   • For complex components, log props in a Blade component’s render() method to verify data:

     public function render() {
         \Log::info('Props:', $this->props);
         return view('fgx::alert', $this->props);
     }
     

Extension Points

1. Custom Components:

   • Extend Existing: Copy and modify a component’s Blade view (e.g., resources/views/vendor/fgx/alert.blade.php) to create variants.

2. New Components:

   • Add to Package: Fork the repository and add new components by following the existing pattern (e.g., resources/views/vendor/fgx/new-component.blade.php).

3. Dynamic Styling:

   • CSS Variables: Override default styles via CSS variables in your app’s stylesheet:

     .fgx-alert {
         --fgx-alert-bg: #333;
         --fgx-alert-color: #fff;
     }
     

4. JavaScript Enhancements:

   • Extend Functionality: Add custom JS behavior by targeting component classes or using Alpine.js:

     <fgx:dropdown x-data="{ open: false }" @click.away="open = false">
         <!-- Options -->
     </fgx:dropdown>
     

5. Configuration Overrides:

   • Global Settings: Override defaults in config/fgx.php:

     'defaults' => [
         'alert_type' => 'info', // Default alert type
         'button_variant' => 'primary', // Default button style
     ],