Bootstrap Admin Ui Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require sylius/bootstrap-admin-ui
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Sylius\Bundle\BootstrapAdminUiBundle\SyliusBootstrapAdminUiBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Ensure your config/packages/sylius_admin.yaml includes:

   sylius_admin:
       options:
           template: '@SyliusBootstrapAdminUi/admin.html.twig'
   

3. First Use Case Extend a Sylius admin controller (e.g., ProductCrudController) to leverage Bootstrap UI:

   use Sylius\Bundle\AdminBundle\Controller\CrudController;
   use Sylius\Bundle\BootstrapAdminUiBundle\EventListener\AdminUiListener;
   
   class ProductCrudController extends CrudController
   {
       public function __construct(
           // ... existing dependencies
           private AdminUiListener $adminUiListener
       ) {
           $this->adminUiListener->configure($this);
       }
   }
   

Key Files to Review

• config/packages/sylius_bootstrap_admin_ui.yaml (default config)
• templates/admin/ (Twig templates for UI overrides)
• src/EventListener/AdminUiListener.php (core logic for UI integration)

Implementation Patterns

Workflow: UI Customization

1. Override Default Templates Copy base templates from vendor/sylius/bootstrap-admin-ui/templates to templates/admin/ in your project. Example: Override index.html.twig for a custom grid view.

2. Extend Admin Controllers Use AdminUiListener to inject Bootstrap-specific behaviors:

   $this->adminUiListener->addActionButton(
       'product_update',
       'btn-primary',
       'sylius.ui.update',
       'fas fa-edit'
   );
   

3. Dynamic UI Logic Hook into Sylius events (e.g., sylius.admin.product.pre_create) to modify UI state:

   $event->getSubject()->setOption('ui', [
       'form' => [
           'fields' => [
               'name' => ['disabled' => true], // Disable field dynamically
           ],
       ],
   ]);
   

Integration Tips

• Symfony UX Integration Pair with symfony/ux-dropzone or symfony/ux-turbolinks for enhanced interactivity:

  # config/packages/symfony_ux.yaml
  symfony_ux: ~
  

• Asset Management Use Webpack Encore or Vite to compile Bootstrap CSS/JS alongside your assets.

• Translation Extend translations via translations/messages.en.yaml:

  sylius:
      ui:
          product:
              actions:
                  bulk_delete: "Delete Selected"
  

Gotchas and Tips

Common Pitfalls

1. Template Caching Clear cache after template overrides:

   php bin/console cache:clear
   

2. CSS/JS Conflicts Bootstrap Admin UI assumes Bootstrap 5. Ensure no other packages override its assets.

3. Event Priority UI listeners may override Sylius defaults. Use ->setPriority(100) to enforce order:

   $dispatcher->addListener(
       'sylius.admin.product.pre_create',
       [$listener, 'onPreCreate'],
       100
   );
   

Debugging Tips

• Twig Debugging Enable Twig debug mode in config/packages/twig.yaml:

  twig:
      debug: '%kernel.debug%'
      strict_variables: '%kernel.debug%'
  

• Event Dumping Log events to debug UI state changes:

  use Psr\Log\LoggerInterface;
  
  public function __construct(private LoggerInterface $logger) {}
  
  public function onPreCreate(ProductEvent $event) {
      $this->logger->debug('UI Options:', $event->getSubject()->getOption('ui'));
  }
  

Extension Points

1. Custom UI Components Create reusable Twig components in templates/components/ and include them:

   {% include '@SyliusBootstrapAdminUi/components/_custom-button.html.twig' %}
   

2. Dynamic Field Configuration Use ui.form.fields to conditionally render fields:

   $product->setOption('ui', [
       'form' => [
           'fields' => [
               'sku' => ['visible' => $product->getId() !== null],
           ],
       ],
   ]);
   

3. Turbolinks Integration For SPA-like behavior, configure Turbolinks in config/packages/symfony_ux_turbolinks.yaml:

   symfony_ux_turbolinks:
       include_assets: true