Form Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle via Composer:

   composer require "elao/form-bundle":"~2.1"
   

   Enable it in AppKernel.php:

   new Elao\Bundle\FormBundle\ElaoFormBundle(),
   

2. Twig Configuration Apply the global form theme in config/packages/twig.yaml:

   twig:
       form_themes:
           - "@ElaoForm/Form/form_elao_layout.html.twig"
   

   Alternative: Apply it per-form in Twig:

   {% form_theme form '@ElaoForm/Form/form_elao_layout.html.twig' %}
   

3. First Use Case Use the help option to add a help block to a field:

   $builder->add('email', EmailType::class, ['help' => 'A valid email address']);
   

   Render the form in Twig:

   {{ form_start(form) }}
       {{ form_row(form.email) }}
   {{ form_end(form) }}
   

Implementation Patterns

Common Workflows

1. Dynamic Form Collections Use data-collection for sortable/draggable collections (requires Elao/form.js):

   {% for item in form.items %}
       <div data-collection="{{ form.vars.collection_name }}">
           {{ form_row(item) }}
       </div>
   {% endfor %}
   

   Initialize with JavaScript:

   $('[data-collection]').collection();
   

2. Button Shortcuts Add submit/reset buttons via form options:

   $builder->setOptions([
       'submit' => true,  // Adds default submit button
       'reset'  => true,  // Adds default reset button
   ]);
   

3. Custom Help Blocks Extend the default help template by overriding:

   {% block elao_form_help %}
       <div class="help-block custom-style">
           {{- block('elao_form_help_content') -}}
       </div>
   {% endblock %}
   

Integration Tips

• Symfony 3.x/4.x: Works with Symfony 3.0+, but test thoroughly in newer versions (last release: 2018).
• Asset Management: Ensure elao/form.js is included for collection features:

  {{ encore_entry_link_tags('app') }}  {# or manual JS include #}
  

• Translation: Help text is auto-translated via Symfony’s translation system. Use:

  ['help' => 'app.form.email_help']
  

  in translations/messages.en.yaml.

Gotchas and Tips

Pitfalls

1. Deprecated Features

   • The bundle is unmaintained (last release: 2018). Avoid for new projects; fork if critical.
   • Some features (e.g., submit/reset options) may conflict with Symfony’s built-in attr or row_attr.

2. JavaScript Dependencies

   • elao/form.js is required for collection features. Missing it breaks drag-and-drop/sorting.
   • Ensure jQuery is loaded before elao/form.js.

3. Template Overrides

   • Overriding form_elao_layout.html.twig requires copying the entire template. Use {% extends %} carefully:

     {% extends '@ElaoForm/Form/form_elao_layout.html.twig' %}
     {% block elao_form_row %}...{% endblock %}
     

Debugging

• Collection Not Working? Check for:

  • Missing data-collection attribute on container elements.
  • JavaScript errors in browser console (e.g., $ is not defined).
  • Correct initialization order (jQuery → elao/form.js → your code).

• Help Text Not Showing? Verify:

  • The field has the help option set.
  • Twig’s form_theme is applied (global or per-form).
  • No CSS is hiding the .help-block class.

Extension Points

1. Custom Field Types Extend the bundle’s field templates by creating a new theme:

   # templates/elao_custom_theme.html.twig
   {% extends '@ElaoForm/Form/form_elao_layout.html.twig' %}
   {% block elao_form_row %}
       <div class="custom-wrapper">
           {{ parent() }}
       </div>
   {% endblock %}
   

   Apply it via:

   {% form_theme form '@ElaoForm/Form/form_elao_layout.html.twig', 'elao_custom_theme.html.twig' %}
   

2. Dynamic Help Blocks Use Twig’s form_help block to customize help content:

   {% block elao_form_help_content %}
       {{ form_help(form) }}  {# Default help #}
       <small>Additional info: {{ form.vars.custom_data }}</small>
   {% endblock %}
   

3. Button Styling Override button templates:

   {% block elao_form_submit_button %}
       <button type="submit" class="btn btn-primary">
           {{ block('elao_form_submit_button_content') }}
       </button>
   {% endblock %}