Formextra Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require clubmaster/formextra
   

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

   Club\FormExtraBundle\ClubFormExtraBundle::class => ['all' => true],
   

   (For Symfony 3.x, add to AppKernel.php as per the README.)

3. Twig Integration

   • Global Theme (recommended for all forms):

     {% form_theme form '@ClubFormExtra/Default/fields.html.twig' %}
     

   • Per-Template Theme:

     {% form_theme form '@ClubFormExtra/Default/fields.html.twig' %}
     

4. First Use Case: Enhanced Textarea

   {{ form_widget(form.description, {'attr': {'class': 'tinymce'}}) }}
   

   (Note: Add novalidate="true" to the <form> tag for TinyMCE.)

Implementation Patterns

1. Form Field Customization

• Slider Integration Use the built-in slideshow for static content:

  <ul id="slideshow">
      {% for item in items %}
          <li>{{ item }}</li>
      {% endfor %}
  </ul>
  {{ include('@ClubFormExtra/Default/slideshow.html.twig') }}
  

  (Include slideshow.css and slideshow.js in your layout.)

• Typeahead Autocomplete Controller Setup:

  public function autocompleteAction(Request $request)
  {
      $results = [
          ['value' => 'Option 1', 'label' => 'Label 1'],
          ['value' => 'Option 2', 'label' => 'Label 2'],
      ];
      return new JsonResponse($results);
  }
  

  Twig Template:

  {{ form_widget(form.search, {
      'attr': {
          'data-url': path('app_autocomplete'),
          'class': 'typeahead'
      }
  }) }}
  

  (Include typeahead.css, handlebars.js, and typeahead.bundle.js.)

2. Workflow Integration

• Dynamic Form Theming Override default templates in templates/bundles/ClubFormExtra/Default/ to customize fields (e.g., textarea_widget.html.twig for TinyMCE).

• Validation Handling Disable validation for TinyMCE fields:

  <form {{ form_enctype(form) }} method="{{ form_method(form) }}" novalidate>
  

• Asset Management Use Symfony’s asset pipeline for CSS/JS:

  <link rel="stylesheet" href="{{ asset('bundles/clubformextra/css/typeahead.css') }}">
  

3. Common Use Cases

Gotchas and Tips

Pitfalls

1. TinyMCE Dependencies

   • The bundle does not include TinyMCE; you must install it separately (e.g., via tinymce/tinymce).
   • Fix: Add novalidate="true" to forms with TinyMCE fields to avoid validation conflicts.

2. Typeahead JSON Structure

   • The bundle expects {'value': '...', 'label': '...'} for typeahead.
   • Fix: Adjust your controller to return this format or override the Handlebars template.

3. Asset Paths

   • Hardcoded paths in the README (e.g., bundles/clubformextra/js/slideshow.css) may break if assets aren’t published.
   • Fix: Use Symfony’s asset() function or configure asset paths in config/packages/assetic.yaml.

4. Twig Template Overrides

   • Overriding templates requires creating a ClubFormExtra/Default/ directory in your templates/bundles/ folder.
   • Tip: Use debug: true in config/packages/twig.yaml to verify template inheritance.

Debugging Tips

• Check Template Loading Enable Twig debug mode to confirm templates are loaded:

  twig:
      debug: true
  

• Validate JSON Responses Test typeahead endpoints with curl or Postman to ensure correct JSON format:

  curl -X GET http://your-app.com/autocomplete
  

• Inspect Browser Console Look for 404 errors on missing assets (e.g., slideshow.js). Use the Network tab to verify paths.

Extension Points

1. Custom Handlebars Templates Override typeahead.html.twig to modify the autocomplete UI:

   {# templates/bundles/ClubFormExtra/Default/typeahead.html.twig #}
   <div class="custom-typeahead">
       {{ parent() }}
   </div>
   

2. Add New Field Types Extend the bundle by creating custom Twig extensions or form types in your application bundle.

3. Configuration No public config options exist, but you can override assets or templates via Symfony’s template inheritance.

Pro Tips

• Bundle Maturity: With 0 stars and no dependents, test thoroughly in a staging environment.
• Fallbacks: For critical forms, include a fallback theme:

  {% form_theme form [
      '@ClubFormExtra/Default/fields.html.twig',
      'form/themes/default.html.twig'  # Symfony fallback
  ] %}
  

• Asset Versioning: Use Symfony’s asset versioning to cache-bust:

  {{ asset('bundles/clubformextra/css/slideshow.css', 'clubformextra') }}