Form Collection Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require antona/form-collection-bundle
   

   (Symfony Flex auto-registers the bundle.)

2. Include Web Components Add the JS/CSS to your base template (e.g., base.html.twig):

   <script src="{{ asset('bundles/onlinqformcollection/onlinq-collection.js') }}"></script>
   <link rel="stylesheet" href="{{ asset('bundles/onlinqformcollection/onlinq-collection.css') }}">
   

3. Enable a Form Theme Configure Twig to use a theme (e.g., Bootstrap 5) in config/packages/twig.yaml:

   twig:
       form_themes:
           - '@OnlinqFormCollection/bootstrap_5_collection_theme.html.twig'
   

4. First Use Case Replace CollectionType with OnlinqCollectionType in a form:

   use Onlinq\FormCollectionBundle\Form\OnlinqCollectionType;
   
   $builder->add('tags', OnlinqCollectionType::class, [
       'entry_type' => TextType::class,
       'allow_add' => true,
       'allow_delete' => true,
       'allow_move' => true, // Unique to OnlinqCollectionType
   ]);
   

Implementation Patterns

Core Workflows

1. Dynamic Collections Use OnlinqCollectionType for sortable, addable, and deletable collections with minimal JS:

   $builder->add('steps', OnlinqCollectionType::class, [
       'entry_type' => StepType::class,
       'prototype' => true, // Renders a template for new entries
       'allow_move' => true,
       'min' => 1, // Enforce minimum items
   ]);
   

2. Theming Integration Extend existing themes by copying and modifying:

   • @OnlinqFormCollection/collection_theme.html.twig (base)
   • @OnlinqFormCollection/bootstrap_5_collection_theme.html.twig (Bootstrap 5) Override in your project’s templates/form/ directory.

3. Stimulus Integration For custom behavior, extend the web component via Stimulus controllers:

   // assets/controllers/collection_controller.js
   import { Controller } from '@hotwired/stimulus';
   export default class extends Controller {
       connect() {
           this.element.addEventListener('onlinq-collection-add', (e) => {
               // Custom logic on add
           });
       }
   }
   

   Attach to forms:

   {{ form_start(form, { attr: { 'data-controller': 'collection' } }) }}
   

4. Validation Feedback Leverage Twig’s built-in validation display with the theme:

   {% for error in form.errors %}
       <div class="error">{{ error.message }}</div>
   {% endfor %}
   

Integration Tips

• Symfony UX: Pair with symfony/ux-live-component for reactive forms.
• API Forms: Use with ApiPlatform for nested collection handling.
• Custom Entry Types: Extend OnlinqCollectionType for domain-specific logic:

  class CustomCollectionType extends OnlinqCollectionType {
      public function configureOptions(OptionsResolver $resolver) {
          $resolver->setDefaults(['custom_option' => true]);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Asset Loading

   • Forgetting assets:install after composer require breaks JS/CSS.
   • Fix: Run php bin/console assets:install and clear cache.

2. Theme Conflicts

   • Mixing @OnlinqFormCollection/collection_theme with Bootstrap themes may cause styling issues.
   • Fix: Use one theme consistently (e.g., bootstrap_5_collection_theme).

3. Prototype Rendering

   • prototype: true requires a prototype template in your theme.
   • Fix: Override the theme’s prototype_row.html.twig if needed.

4. JavaScript Dependencies

   • The web component relies on lit and stimulus. Conflicts may arise with other JS bundles.
   • Fix: Ensure webpack.config.js includes:

     Encore
         .addEntry('app', './assets/app.js')
         .splitEntry(chunk => chunk.name === 'app' && ['onlinq-collection']);
     

Debugging

• Console Errors: Check browser console for onlinq-collection errors (e.g., missing dependencies).
• Form Data: Use {{ dump(form.vars) }} to inspect collection structure.
• Event Listeners: Add debug logs in Stimulus controllers:

  console.log('Collection event:', event.detail);
  

Extension Points

1. Custom Templates Override Twig templates in templates/form/OnlinqFormCollection/:

   • collection_widget.html.twig
   • prototype_row.html.twig

2. Configuration Extend OnlinqCollectionType options via a compiler pass:

   public function process(ContainerBuilder $container) {
       $definition = $container->findDefinition(OnlinqCollectionType::class);
       $definition->addMethodCall('setCustomOption', ['value']);
   }
   

3. Localization Translate labels/buttons by extending the theme and using trans:

   <button>{{ 'onlinq.add'|trans }}</button>
   

Pro Tips

• Performance: Disable allow_move if not needed to reduce JS payload.
• Accessibility: Ensure aria-labels are set in custom themes for screen readers.
• Testing: Use Symfony\Panther to test dynamic collection interactions:

  $crawler->executeScript("document.querySelector('onlinq-collection').addItem()");