Jsfv Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies:

   composer require apy/jsfv-bundle
   composer require willdurand/bazinga-expose-translation-bundle
   

   Ensure BazingaExposeTranslationBundle is registered in AppKernel.php.

2. Configure Bundle: Add to config.yml:

   apy_jsfv:
       framework: jquery  # or mootools, prototype, etc.
       assets_warmer: true
   

3. Include Assets: In your base template (e.g., base.html.twig), add:

   <script src="{{ asset('bundles/bazingaexposetranslation/js/translator.min.js') }}"></script>
   <script src="{{ path('bazinga_exposetranslation_js', { 'domain_name': 'validators' }) }}"></script>
   

4. First Use Case: In your form template, add the Twig function:

   {{ JSFV(form) }}
   

   Place this after the form widget ({{ form_widget(form) }}) but before the closing </form> tag.

Implementation Patterns

Core Workflow

1. Form Definition: Define constraints in your entity (e.g., @Assert\NotBlank()) or form type. The bundle mirrors these to JavaScript.

2. Template Integration:

   <form {{ form_enctype(form) }}>
       {{ form_widget(form) }}
       {{ JSFV(form) }}  <!-- Auto-generates JS validation -->
       <button type="submit">Submit</button>
   </form>
   

3. Localization: Translations are exposed via BazingaExposeTranslationBundle. Ensure your validators translation domain is populated (e.g., messages.en.yml):

   validators:
       This value should not be blank: "This field is required."
   

4. Event-Driven Customization: Subscribe to apy_jsfv.on_generate_validation_script to modify the generated JS:

   // services.yml
   services:
       app.jsfv_listener:
           class: AppBundle\EventListener\JsFVListener
           tags:
               - { name: kernel.event_listener, event: apy_jsfv.on_generate_validation_script, method: onGenerateScript }
   

Integration Tips

• Asset Management: Use assets_warmer to precompile JS/CSS for production:

  php app/console assets:install --symlink
  php app/console assets:warmer --env=prod
  

• Dynamic Forms: For AJAX-loaded forms, reinitialize validation with:

  JsFormValidator.init();
  

• Constraint Prioritization: The bundle processes constraints in the order they appear in the form. Use setAttribute('validation_groups', ['group1']) to control groups.

Gotchas and Tips

Pitfalls

1. Deprecated Symfony Versions: The bundle only supports Symfony 2.1–2.3. For newer versions, use fp/jsformvalidator-bundle.

2. Missing Translations: If validation messages appear as keys (e.g., This value should not be blank), ensure:

   • BazingaExposeTranslationBundle is configured.
   • The validators domain is exposed via bazinga_exposetranslation_js route.

3. JavaScript Framework Conflicts: The bundle assumes a single JS framework. Mixing frameworks (e.g., jQuery + Mootools) may break validation. Stick to one.

4. Constraint Limitations: Not all Symfony constraints are supported. Check constraints_warning.md for unsupported types (e.g., custom callbacks).

Debugging

• Generated JS: Inspect the rendered HTML for the <script> tag generated by {{ JSFV(form) }}. Validate its content matches your constraints.

• Console Errors: If JS fails silently, check the browser console for errors like:

  TypeError: $(...).JsFormValidator is not a function
  

  Fix: Ensure the JS framework is loaded before the bundle’s script.

• Cache Issues: Clear assets and cache after configuration changes:

  php app/console cache:clear --env=prod
  php app/console assets:clear --env=prod
  

Extension Points

1. Custom Constraints: Extend the bundle by implementing APY\JsFormValidationBundle\Constraint\ConstraintInterface and register it in services.yml:

   services:
       app.custom_constraint:
           class: AppBundle\Constraint\CustomConstraint
           tags:
               - { name: apy_jsfv.constraint }
   

2. Override Templates: Copy APYJsFormValidationBundle::validation.html.twig to AppBundle/Resources/views/ to customize the generated JS.

3. Event Hooks: Use apy_jsfv.on_generate_validation_script to inject custom logic:

   public function onGenerateScript(GenerateValidationScriptEvent $event) {
       $event->setValidationScript($event->getValidationScript() . "\n// Custom JS");
   }
   

Performance

• Disable for Non-Critical Forms: Use Twig conditionals to exclude validation from forms where UX isn’t impacted:

  {% if form.vars.required %}
      {{ JSFV(form) }}
  {% endif %}
  

• Lazy Loading: For large forms, defer validation initialization until the form is interacted with:

  $(document).on('focus', 'input, select, textarea', function() {
      if (!window.JsFormValidatorInitialized) {
          JsFormValidator.init();
          window.JsFormValidatorInitialized = true;
      }
  });