Form Extensions Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require avocode/form-extensions-bundle:dev-master
   

   Add to AppKernel.php before AdmingeneratorGeneratorBundle:

   new Avocode\FormExtensionsBundle\AvocodeFormExtensionsBundle(),
   

2. Template Integration: Update your base template (base.html.twig or similar) to include:

   {% block stylesheets %}
       {{ parent() }}
       {% include 'AvocodeFormExtensionsBundle::stylesheets.html.twig' %}
       {% if form is defined %}{{ afe_form_stylesheet(form) }}{% endif %}
   {% endblock %}
   
   {% block javascripts %}
       {{ parent() }}
       {% include 'AvocodeFormExtensionsBundle::javascripts.html.twig' %}
       {% if form is defined %}{{ afe_form_javascript(form) }}{% endif %}
   {% endblock %}
   

3. First Use Case: Extend a form type in your entity CRUD. Example for a UserType:

   use Avocode\FormExtensionsBundle\Form\Type\Select2Type;
   
   $builder->add('roles', Select2Type::class, [
       'choices' => $roles,
       'multiple' => true,
       'config' => ['width' => 'resolve'],
   ]);
   

Implementation Patterns

Common Workflows

1. Select2 Integration: Replace standard EntityType or ChoiceType with Select2Type for enhanced UX:

   $builder->add('tags', Select2Type::class, [
       'choices' => $tagRepository->findAll(),
       'config' => [
           'placeholder' => 'Select tags...',
           'allowClear' => true,
       ],
   ]);
   

2. File Uploads: Use SingleUploadType or MultipleUploadType for drag-and-drop uploads:

   $builder->add('avatar', SingleUploadType::class, [
       'allowed_mime_types' => ['image/jpeg', 'image/png'],
       'upload_directory' => '%kernel.project_dir%/public/uploads',
   ]);
   

3. Dynamic Forms: Leverage DynamicFormType for multi-step or collapsible forms:

   $builder->add('dynamic_fields', DynamicFormType::class, [
       'fields' => [
           'field1' => ['type' => TextType::class, 'label' => 'Field 1'],
           'field2' => ['type' => DateType::class, 'label' => 'Field 2'],
       ],
   ]);
   

4. Bootstrap Integration: Use BootstrapType for consistent styling:

   $builder->add('submit', SubmitType::class, [
       'attr' => ['class' => 'btn btn-primary'],
   ]);
   

Integration Tips

• Admingenerator Compatibility: Override buildForm in your generator’s AdminGenerator to inject extensions:

  protected function buildForm(FormBuilderInterface $builder, array $options)
  {
      $builder->add('field', Select2Type::class, [...]);
  }
  

• Asset Management: For custom assets (e.g., Font Awesome), ensure paths in config.yml align with bundle defaults:

  avocode_form_extensions:
      assets:
          jqueryui_path: "%kernel.root_dir%/vendor/components/jqueryui"
          bootstrap_path: "%kernel.root_dir%/vendor/components/bootstrap"
  

• Translation: Extend translations via translations/messages.en.yml (or your locale):

  avocode_form_extensions:
      select2:
          search_placeholder: "Search..."
  

Gotchas and Tips

Pitfalls

1. Bundle Loading Order: Critical: Register AvocodeFormExtensionsBundle before AdmingeneratorGeneratorBundle. Failure causes form types to fail silently.

2. Asset Conflicts:

   • If using Bootstrap 3+, manually include select2-bootstrap.css in your template to avoid styling issues.
   • jQuery version conflicts (e.g., jQuery 2.x) may break Select2. Pin to ~1.9.0 in composer.json if needed.

3. Deprecated Dependencies: The bundle relies on twig/extensions (v1.2) and components/* packages. Update paths in config.yml if these are moved in your project:

   avocode_form_extensions:
       assets:
           jquery_path: "%kernel.root_dir%/vendor/jquery/dist/jquery"
   

4. Form Type Overrides: Avoid naming conflicts with Symfony’s core types. Prefix custom types (e.g., App\Form\Type\CustomSelect2Type).

Debugging

• Missing Styles/JS: Check browser console for 404s on /bundles/avocodeformextensions/.... Verify:

  • Assets are included in your base template.
  • app/console assets:install is run post-install.

• Select2 Not Loading: Ensure select2.min.js is loaded after jQuery and jQuery UI:

  {% include 'AvocodeFormExtensionsBundle::javascripts.html.twig' %}
  {{ afe_form_javascript(form) }} {# Must come last #}
  

• Upload Issues: Validate upload_directory permissions and MIME types. Debug with:

  $builder->add('file', SingleUploadType::class, [
      'upload_handler' => function ($file) {
          // Custom logic (e.g., validation)
      },
  ]);
  

Extension Points

1. Custom Form Types: Extend existing types (e.g., Select2Type) by subclassing:

   use Avocode\FormExtensionsBundle\Form\Type\Select2Type;
   
   class CustomSelect2Type extends Select2Type {
       public function configureOptions(OptionsResolver $resolver) {
           $resolver->setDefaults([
               'custom_option' => true,
           ]);
       }
   }
   

2. Twig Extensions: Override Twig functions (e.g., afe_form_stylesheet) in your app’s Twig environment:

   $twig->addFunction(new \Twig_SimpleFunction('afe_form_stylesheet', function($form) {
       // Custom logic
   }));
   

3. Configuration Overrides: Override bundle defaults in config.yml:

   avocode_form_extensions:
       select2:
           theme: "bootstrap"  # Default: 'default'
           width: "style"     # Default: 'resolve'
       upload:
           max_file_size: 10M