Bcknockoutjsbundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require brookinsconsulting/bcknockoutjsbundle:dev-master
   

   Add to AppKernel.php:

   new BrookinsConsulting\BcKnockoutJSBundle\BcKnockoutJSBundle(),
   

   Import config in config.yml:

   imports:
       - { resource: "@BcKnockoutJSBundle/Resources/config/config.yml" }
   

2. Basic Usage:

   • Include KnockoutJS in your template:

     <script src="{{ asset('bundles/bcknockoutjs/js/knockout-3.4.1.js') }}"></script>
     

   • Render the form with Knockout integration:

     {{ knockout(form.vars.knockout)|raw }}
     {{ form_widget(form) }}
     

3. First Use Case: Define a CollectionType field with knockout type in your form builder:

   $builder->add('items', 'knockout', [
       'type' => new OrderItemType(),
       'allow_add' => true,
       'allow_delete' => true,
       'prototype' => true,
   ]);
   

Implementation Patterns

Common Workflows

1. Dynamic Collections: Use allow_add/allow_delete to enable CRUD operations for collection items:

   $builder->add('tags', 'knockout', [
       'type' => new TagType(),
       'allow_add' => true,
       'allow_delete' => true,
       'prototype' => true, // Renders a hidden template for new items
   ]);
   

2. Nested Forms: Combine with Symfony’s CollectionType for multi-level Knockout integration:

   $builder->add('categories', 'collection', [
       'type' => new CategoryType(),
       'allow_add' => true,
       'prototype' => true,
       'by_reference' => false,
       'knockout' => true, // Enable Knockout for nested collections
   ]);
   

3. Custom Templates: Override the prototype template in Twig:

   {% block knockout_prototype_items %}
       <div class="new-item">
           {{ form_row(form.prototype) }}
           <button type="button" class="remove-item">Remove</button>
       </div>
   {% endblock %}
   

4. Data Binding: Bind form data to a Knockout observable:

   {{ knockout(form.vars.knockout, {
       'data-bind': 'foreach: items, with: $data'
   })|raw }}
   

Integration Tips

• Asset Management: Ensure knockout-3.4.1.js is accessible via asset().
• Form Theming: Extend knockout.html.twig for consistent styling.
• Validation: Use Symfony’s validation with Knockout’s ko.validation for client-side feedback.
• AJAX: Pair with Symfony’s FormHandler for seamless server-side updates.

Gotchas and Tips

Pitfalls

1. Deprecation Warning: The bundle is deprecated (Symfony 2/3 only). Avoid in new projects; consider alternatives like:

   • knplabs/knp-components (Symfony 4+).
   • Custom Knockout + Symfony UX Turbo integration.

2. JMS DI Extra: The jms_di_extra config is unnecessary if all_bundles: true is set elsewhere (performance risk).

3. Prototype Template: Forgetting prototype: true breaks "Add Item" functionality. Ensure the template block (knockout_prototype_*) exists.

4. Knockout Version Lock: The bundle ships with Knockout 3.4.1. Conflicts may arise if other bundles include newer versions.

5. Form Events: Knockout’s add/remove events may not trigger Symfony’s PRE_SUBMIT/POST_SUBMIT lifecycle. Handle manually:

   ko.applyBindingsToNode(document.getElementById('your-form'), {
       createViewModel: function() {
           return { items: formData.items };
       }
   });
   

Debugging

• Check form.vars.knockout: Inspect the rendered Twig variable to verify Knockout data is passed correctly.

  {{ dump(form.vars.knockout) }}
  

• Console Errors: Knockout errors often appear in the browser console. Look for:

  • Cannot read property 'applyBindings' of undefined (missing ko global).
  • Template not found (incorrect prototype template block name).

• Symfony Profiler: Use the Form panel to debug collection data binding.

Extension Points

1. Custom Types: Extend BrookinsConsulting\BcKnockoutJSBundle\Form\Type\KnockoutType for specialized behavior.

2. Template Overrides: Override BcKnockoutJSBundle:Form:knockout.html.twig for global changes.

3. JavaScript Extensions: Add custom Knockout bindings in a separate JS file:

   // assets/js/knockout-extensions.js
   ko.bindingHandlers.customBinding = { /* ... */ };
   

   Include it after the bundle’s Knockout script.

4. Server-Side Logic: Use Symfony’s PRE_SET_DATA to pre-populate Knockout observables:

   $form->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
       $data = $event->getData();
       $event->getForm()->vars['knockout']['initialData'] = $data->toArray();
   });