Admin Ui Laravel Package

Getting Started

Minimal Setup

To start using ibexa/admin-ui in a Laravel project (via Ibexa DXP integration), follow these steps:

1. Install Ibexa DXP Ensure you have Ibexa DXP installed as a dependency in your Laravel project. This package is part of the DXP ecosystem, so it’s not standalone.

   composer require ibexa/dxp
   

2. Configure Ibexa Publish and configure Ibexa’s admin UI bundle:

   php artisan vendor:publish --provider="Ibexa\AdminUi\AdminUiServiceProvider"
   

   Update config/ibexa.php with your DXP settings (siteaccess, database, etc.).

3. First Use Case: Custom Field Validation Extend the back office UI with custom validation for a field type. For example, validate a custom ibexa_string field:

   // resources/js/ibexa/admin-ui/field-types/ibexa_string/validator.js
   class CustomStringValidator extends window.ibexa.BaseFieldValidator {
       validateInput(event) {
           const value = event.target.value;
           return {
               isError: value.length < 5,
               errorMessage: 'Minimum 5 characters required',
           };
       }
   }
   
   const validator = new CustomStringValidator({
       classInvalid: 'is-invalid',
       fieldSelector: '.ez-field-edit-ibexa_string',
       eventsMap: [{
           selector: '.ez-field-edit-ibexa_string input',
           eventName: 'blur',
           callback: 'validateInput',
           invalidStateSelectors: ['.ez-field-edit-ibexa_string'],
           errorNodeSelectors: ['.ez-field-edit-text-zone'],
       }],
   });
   validator.init();
   

4. Register the Validator Ensure your validator is loaded by Ibexa’s admin UI. Use a Laravel service provider or a custom JS bundle:

   // In your main JS entry point (e.g., resources/js/app.js)
   import './ibexa/admin-ui/field-types/ibexa_string/validator';
   

Implementation Patterns

1. Extending Field Types

• Pattern: Use BaseFieldValidator to add custom validation logic for existing or new field types.

  • Override validateInput to define validation rules.
  • Use eventsMap to bind validation to specific DOM events (e.g., blur, change).
  • Example: Validate a ibexa_url field to ensure it starts with https://.

• Workflow:

  1. Create a validator class for your field type.
  2. Configure fieldSelector, eventsMap, and error handling.
  3. Initialize the validator in your JS bundle.
  4. Test in the back office (e.g., content creation/edit forms).

2. Customizing UI Components

• Pattern: Extend or override Ibexa’s UI components using its extensibility points.

  • RichText Config: Extend the rich text editor config via IBX-10827 (v5.0.7+):

    // Extend rich text toolbar buttons
    window.ibexa.RichTextEditorConfig.extend({
        toolbar: [
            'bold', 'italic', 'customButton', // Add your button
        ],
        customButton: {
            handler: () => console.log('Custom button clicked'),
        },
    });
    

  • Translation Selector: Use the content edit translation selector extension point (v5.0.7+) to modify language dropdowns.

• Integration Tips:

  • Use Laravel’s asset pipeline to bundle custom JS/CSS.
  • Leverage Ibexa’s ez-admin-ui namespace for component overrides.
  • Example: Override the content tree view by extending ez-content-tree.

3. Handling API Responses

• Pattern: Ibexa’s admin UI relies on API endpoints (e.g., /api/ibexa/v2/content). Customize responses or add endpoints:
  • Laravel Route: Create a route to fetch custom data:

    Route::get('/api/ibexa/v2/custom-data', [CustomController::class, 'index']);
    

  • JS Fetch: Use the response in your UI logic:

    fetch('/api/ibexa/v2/custom-data')
        .then(response => response.json())
        .then(data => {
            // Update UI dynamically
            document.querySelector('.custom-placeholder').innerHTML = data.value;
        });
    

4. Debugging and Logging

• Pattern: Use Ibexa’s debug tools and Laravel’s logging:
  • Enable Ibexa debug mode in config/ibexa.php:

    'debug' => env('APP_DEBUG', true),
    

  • Log custom events:

    console.log('Custom event triggered', event); // Check browser console
    

  • Laravel logs:

    \Log::info('Custom Ibexa event', ['data' => $data]);
    

Gotchas and Tips

Pitfalls

1. DOM Timing Issues

   • Issue: Validators or UI extensions may fail if DOM elements aren’t ready.
   • Fix: Use reinit() to rebind events after DOM changes (e.g., in SPAs or dynamic content).

     validator.reinit(); // Rebind after AJAX updates
     

2. CSS Selector Mismatches

   • Issue: Ibexa’s UI uses dynamic class names (e.g., .ez-field-edit-*). Selectors may break across versions.
   • Fix: Use data attributes or more stable selectors:

     fieldSelector: '[data-field-type="ibexa_string"]',
     

3. Translation Conflicts

   • Issue: Hardcoded strings in JS may not respect Ibexa’s language settings.
   • Fix: Use Ibexa’s translation system or Laravel’s trans() helper in PHP.

4. API Versioning

   • Issue: Ibexa’s API endpoints may change between versions (e.g., /api/ibexa/v2/ vs /api/ibexa/v3/).
   • Fix: Check release notes (e.g., v5.0.7) for breaking changes.

5. OSS vs. DXP Features

   • Issue: Some features (e.g., IBX-10737) are DXP-only and may throw errors in OSS.
   • Fix: Conditionally load DXP-specific code:

     if (window.ibexa.isDXP) {
         // DXP-only logic
     }
     

Debugging Tips

1. Browser DevTools

   • Inspect Ibexa’s JS bundles under Network tab (look for ez-admin-ui.js).
   • Override Ibexa’s JS in development:

     window.ibexa = { ...window.ibexa, MyCustomConfig: {} };
     

2. Laravel Debugging

   • Dump Ibexa’s config:

     dd(\Ibexa\AdminUi\Config::get());
     

   • Enable Ibexa’s debug toolbar (if available).

3. Validator Debugging

   • Log validation results:

     validateInput(event) {
         const result = { isError: true, errorMessage: 'Debug: Validation failed' };
         console.log('Validation result:', result);
         return result;
     }
     

Extension Points

1. RichText Editor

   • Extend via window.ibexa.RichTextEditorConfig (v5.0.7+).
   • Example: Add a custom plugin:

     window.ibexa.RichTextEditorConfig.plugins = [
         'customPlugin',
         ...window.ibexa.RichTextEditorConfig.plugins,
     ];
     

2. Content Tree

   • Override tree behavior by extending ez-content-tree:

     window.ibexa.ContentTree = window.ibexa.ContentTree.extend({
         initialize: function() {
             this._super();
             console.log('Custom content tree initialized');
         },
     });
     

3. Field Type UI

   • Create custom field type views by extending Ibexa’s templates (e.g., Twig templates in resources/views/vendor/ibexa/).

4. API Extensions

   • Add custom endpoints in Laravel and register them in Ibexa’s API router:

     $router->get('/custom-endpoint', [CustomController::class, 'handle']);