Ux Collection Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require arkounay/ux-collection
   npm install --force && npm run watch
   

   Ensure StimulusBundle is configured in your Symfony app.

2. Basic Usage: Replace CollectionType with UxCollectionType in your form builder:

   use Arkounay\Bundle\UxCollectionBundle\Form\UxCollectionType;
   
   $builder->add('items', UxCollectionType::class, [
       'entry_type' => ItemType::class,
       'allow_add' => true,
       'allow_delete' => true,
   ]);
   

3. First Use Case: Create a dynamic form for a product variant collection (e.g., SKUs, colors, sizes) where users can add/remove variants via a clean UI.

Implementation Patterns

Common Workflows

1. Dynamic Collections: Use allow_add/allow_delete for CRUD operations on form entries (e.g., multi-step forms, nested configurations).

   'allow_add' => true,
   'allow_delete' => true,
   'min' => 1, // Enforce minimum items
   'max' => 5, // Limit maximum items
   

2. Reordering Items: Enable drag-and-drop for sortable lists (e.g., priority queues, step-by-step workflows):

   'allow_drag_and_drop' => true,
   'drag_and_drop_filter' => 'input,textarea,button', // Exclude specific elements
   

3. Nested Collections: Configure child collections with unique prototype_name to avoid conflicts:

   'entry_type' => NestedItemType::class,
   'prototype_name' => '__nested_item__', // Custom prototype name
   

4. Custom Styling: Override default classes via form options:

   'add_class' => 'btn btn-primary',
   'add_wrapper_class' => 'mb-4',
   

5. Event Listening: Extend functionality with Stimulus controllers (e.g., real-time validation, analytics):

   'attr' => [
       'data-controller' => 'custom-collection',
       'data-action' => 'ux-collection:change->parent#updateTotal'
   ],
   

Integration Tips

• Symfony UX: Works seamlessly with StimulusBundle and WebpackEncore.
• EasyAdmin: Override form theme in configureCrud():

  ->addFormTheme('@ArkounayUxCollection/ux_collection_form_theme.html.twig')
  

• AssetMapper: Supported since v4.0.0; configure in assets/controllers.json:

  "@arkounay/ux-collection": { "collection": { "enabled": true } }
  

Gotchas and Tips

Pitfalls

1. File Inputs: Disable sorting (allow_drag_and_drop: false) if using VichUploaderBundle to avoid form name conflicts. Alternatively, use position_selector to manually manage positions:

   'position_selector' => '.position-input',
   

2. Nested Collections:

   • Prototype Name: Child collections must have unique prototype_name (e.g., __parent__[__child__]).
   • Position Bug: If parent positions change, child items may misplace. Test thoroughly with nested drag-and-drop.

3. Bootstrap 5: Disable standalone CSS in controllers.json to avoid conflicts:

   "@arkounay/ux-collection/src/style-when-not-using-bootstrap-5.css": false
   

4. Event Handling:

   • Use ux-collection:change for real-time updates (e.g., cart totals).
   • Ensure Stimulus controllers are registered in assets/controllers.json:

     "custom-collection": { "path": "path/to/controller.js" }
     

5. Deprecations:

   • Twig’s spaceless filter is deprecated (v4.0.2+). Update templates if using custom themes.

Debugging Tips

• Console Logs: Add debug logs in custom Stimulus controllers:

  _onAdd(event) { console.log('Added item:', event.detail); }
  

• Form Themes: Override @ArkounayUxCollection/ux_collection.html.twig for custom HTML.
• CSS Conflicts: Use browser dev tools to inspect .arkounay-ux-collection classes.

Extension Points

1. Custom Controllers: Extend default behavior via Stimulus (e.g., auto-focus new items):

   connect() {
       this.element.addEventListener('ux-collection:add', (e) => {
           e.detail.target.querySelector('input').focus();
       });
   }
   

2. Validation: Use ux-collection:change to trigger custom validation (e.g., duplicate checks):

   'attr' => ['data-action' => 'ux-collection:change->validator#checkDuplicates']
   

3. Localization: Override translations in your bundle’s Resources/translations/ (e.g., messages.en.yaml):

   arkounay_ux_collection:
       add: "Ajouter un élément" # French override
   

4. Alternative Collection Types:

   • Horizontal: Use UxHorizontalCollectionType for left-to-right layouts.
   • Tabbed: Use UxTabbedCollectionType (Bootstrap 5 required; customize CSS via tabbed-style.css).

Pro Tips

• Performance: Disable allow_drag_and_drop for large collections (>50 items) to reduce JS overhead.
• Accessibility: Add aria-live regions for dynamic updates:

  <div aria-live="polite">{{ form_row(form) }}</div>
  

• Testing: Use Symfony’s FormTestCase to verify collection behavior:

  $form->submit(['items' => [['name' => 'Item 1'], ['name' => 'Item 2']]]);
  $this->assertEquals(2, count($form->getData()['items']));