Form Extra Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require egeloen/form-extra-bundle
   

   Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       Ivory\FormExtraBundle\IvoryFormExtraBundle::class => ['all' => true],
   ];
   

2. Enable in config/packages/ivory_form_extra.yaml:

   ivory_form_extra:
       form:
           # Enable the fragments you need (e.g., 'javascript' or 'stylesheet')
           fragments: ['javascript', 'stylesheet']
   

3. First Use Case: Inject the IvoryFormExtraBundle services into a form type or controller to render dynamic JS/CSS fragments:

   use Ivory\FormExtraBundle\Form\Type\ExtraFormType;
   
   class MyFormType extends AbstractType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           $builder->add('field', TextType::class)
                   ->add('extra', ExtraFormType::class, [
                       'javascript' => '//cdn.example.com/script.js',
                       'stylesheet' => '//cdn.example.com/style.css',
                   ]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Dynamic Asset Injection: Use ExtraFormType to attach JS/CSS fragments conditionally (e.g., per form field or section):

   $builder->add('dynamicField', TextType::class, [
       'extra' => [
           'javascript' => [
               'path' => '//cdn.example.com/field-script.js',
               'attributes' => ['defer' => true],
           ],
       ],
   ]);
   

2. Twig Integration: Render fragments in templates with:

   {{ form_widget(form.extra) }}
   

   Or target specific fragments:

   {{ form_widget(form.extra.javascript) }}
   {{ form_widget(form.extra.stylesheet) }}
   

3. Event-Based Customization: Subscribe to FormEvents::PRE_SET_DATA to modify fragments dynamically:

   $form->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
       $form = $event->getForm();
       if ($form->get('userType')->getData() === 'admin') {
           $form->add('extra', ExtraFormType::class, [
               'javascript' => '//admin.example.com/dashboard.js',
           ]);
       }
   });
   

4. Asset Versioning: Leverage Symfony’s asset system for cache-busting:

   # config/packages/ivory_form_extra.yaml
   ivory_form_extra:
       form:
           fragments:
               javascript:
                   version: '{{ asset_version("js") }}'
   

Gotchas and Tips

Pitfalls

1. Fragment Ordering: JS/CSS fragments render in the order they’re defined. Use position options to control placement:

   'javascript' => [
       'path' => 'script.js',
       'position' => 'head', // 'head' or 'body'
   ],
   

2. Circular Dependencies: Avoid adding ExtraFormType recursively (e.g., inside another extra field). Use events or base types instead.

3. Asset Paths: Relative paths (e.g., bundles/acme/js/script.js) may fail in production. Prefer absolute URLs or %kernel.project_dir%:

   'javascript' => '%kernel.project_dir%/public/js/script.js',
   

4. Debug Mode Quirks: In APP_DEBUG=true, fragments may render multiple times. Use {{ form_widget(form.extra, {'render_extras': false}) }} to suppress duplicates.

Debugging

• Check Rendered Output: Inspect the HTML source to verify fragments are injected. Use {{ dump(form.extra.vars) }} in Twig for debugging.

• Clear Cache: After config changes, run:

  php bin/console cache:clear
  

Extension Points

1. Custom Fragment Types: Extend Ivory\FormExtraBundle\Form\Type\ExtraFormType to add new fragment types (e.g., iframe or meta tags):

   class CustomExtraFormType extends ExtraFormType {
       public function configureOptions(OptionsResolver $resolver) {
           $resolver->setDefaults([
               'custom_fragment' => null,
           ]);
       }
   }
   

2. Override Default Rendering: Create a custom template for fragments:

   # templates/ivory_form_extra/extra/javascript.html.twig
   <script src="{{ asset(path) }}" {{ attributes }}></script>
   

3. Conditional Loading: Use Twig’s if to render fragments conditionally:

   {% if app.user.isAdmin %}
       {{ form_widget(form.extra.javascript) }}
   {% endif %}
   

4. Asset Processing: Integrate with Encore/Webpack for bundling:

   # config/packages/ivory_form_extra.yaml
   ivory_form_extra:
       form:
           fragments:
               javascript:
                   entry: 'app' # Webpack entry point