Form Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require genemu/form-bundle:2.2.*
   

   Ensure your composer.json targets Symfony 2.3+.

2. Enable the Bundle: Add new Genemu\Bundle\FormBundle\GenemuFormBundle() to AppKernel::registerBundles().

3. Initialize Assets:

   php app/console assets:install web/
   

4. First Form Integration: Use the Select2Type in a form builder:

   use Genemu\Bundle\FormBundle\Form\Type\Select2Type;
   
   $builder->add('fieldName', Select2Type::class, [
       'choices' => ['option1' => 'Label 1', 'option2' => 'Label 2'],
       'multiple' => true, // Optional
   ]);
   

5. Verify Assets: Check web/bundles/genemuform/ for loaded JS/CSS. For Select2, include its template:

   {% form_theme form _self %}
   

Implementation Patterns

Common Workflows

1. Select2 Integration:

   • Dynamic Data: Fetch remote data via ajax_url option:

     $builder->add('user', Select2Type::class, [
         'ajax_url' => '/api/users',
         'ajax_data' => ['role' => 'admin'],
     ]);
     

   • Custom Templates: Override GenemuFormBundle:Select2:select2_widget.html.twig in your theme.

2. Captcha Usage:

   • GD Captcha: Add to a form and validate via CaptchaValidator:

     $builder->add('captcha', CaptchaGDType::class);
     

   • ReCaptcha: Configure with API keys in config.yml:

     genemu_form:
         recaptcha:
             public_key:  'your_public_key'
             private_key: 'your_private_key'
     

     Use in forms:

     $builder->add('recaptcha', ReCaptchaType::class);
     

3. TinyMCE Editor:

   • Basic Setup: Add to a form with default config:

     $builder->add('content', TinyMceType::class);
     

   • Custom Config: Override via config option:

     $builder->add('content', TinyMceType::class, [
         'config' => [
             'plugins' => 'code',
             'toolbar' => 'bold italic code',
         ],
     ]);
     

4. Form Theming:

   • Extend base templates in Resources/views/Form/:

     {# app/Resources/Form/fields.html.twig #}
     {% block select2_widget %}
         {{ parent() }}
         <script>$(document).ready(function() { /* Custom JS */ });</script>
     {% endblock %}
     

Integration Tips

• Asset Management: Use {% javascripts '@GenemuFormBundle/Resources/public/js/*' %} in layouts to bundle JS.
• Validation: For Captcha, add constraints:

  use Genemu\Bundle\FormBundle\Validator\Constraints\Captcha;
  
  $builder->add('captcha', CaptchaGDType::class, [
      'constraints' => [new Captcha()],
  ]);
  

• Lazy Loading: Load Select2/TinyMCE assets only on pages where forms exist via Twig’s {% block javascripts %}.

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • Issue: Missing JS/CSS after assets:install.
   • Fix: Ensure web/bundles/genemuform/ exists. Run assets:install --symlink in dev.

2. Select2 Dependencies:

   • Issue: Select2 fails with Uncaught TypeError: $(...).select2 is not a function.
   • Fix: Verify jQuery is loaded before Select2 JS. Check Twig order:

     {% javascripts
         '//code.jquery.com/jquery-3.4.1.min.js'
         '@GenemuFormBundle/Resources/public/js/select2/select2.min.js'
     %}
     

3. ReCaptcha Errors:

   • Issue: "Invalid domain for site owner" during validation.
   • Fix: Whitelist your domain in Google ReCaptcha Admin.

4. TinyMCE Conflicts:

   • Issue: Multiple TinyMCE instances break.
   • Fix: Use unique id in config:

     'config' => ['selector' => 'form_editor_' . uniqid()]
     

5. Symfony 3/4+ Compatibility:

   • Issue: Bundle may fail on newer Symfony versions.
   • Fix: Override GenemuFormBundle in config/bundles.php to force load:

     return [
         // ...
         Genemu\Bundle\FormBundle\GenemuFormBundle::class => ['all' => true],
     ];
     

Debugging

• Form Dumping: Use Symfony’s form profiler (_profiler) to inspect rendered fields.
• Console Logs: Enable debug mode (APP_DEBUG=true) to catch asset/JS errors.
• Select2 AJAX: Test ajax_url endpoints manually (e.g., /api/users?role=admin).

Extension Points

1. Custom Form Types: Extend existing types (e.g., Select2Type) by creating a new class:

   use Genemu\Bundle\FormBundle\Form\Type\Select2Type;
   
   class CustomSelect2Type extends Select2Type {
       public function getParent() { return Select2Type::class; }
       public function configureOptions(OptionsResolver $resolver) {
           $resolver->setDefaults(['custom_option' => true]);
       }
   }
   

2. Override Templates: Copy Resources/views/ from the bundle to your theme (e.g., app/Resources/GenemuFormBundle/).

3. Event Listeners: Subscribe to form events (e.g., PRE_SET_DATA) to modify behavior:

   $form->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
       $event->getForm()->add('field', Select2Type::class, ['multiple' => true]);
   });
   

4. Configuration: Override bundle defaults in config.yml:

   genemu_form:
       select2:
           theme: 'bootstrap'  # Default: 'default'
       tinymce:
           base_url: '//cdn.tiny.cloud/1/your_api_key/tinymce/5/'