Thrace Form Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aqarmap/thrace-form-bundle
   

   Enable the bundle in config/bundles.php (Symfony 4+) or app/AppKernel.php (Symfony 2/3):

   // Symfony 4+
   Thrace\FormBundle\ThraceFormBundle::class => ['all' => true],
   

2. Basic Usage: Import the form type in your controller or entity:

   use Thrace\FormBundle\Form\Type\DatePickerType;
   

   Register it in your form builder:

   $builder->add('birthday', DatePickerType::class);
   

3. First Use Case: Add a jQueryUI-powered datepicker to a form field:

   $builder->add('eventDate', DatePickerType::class, [
       'widget' => 'single_text',
       'html5' => false,
       'attr' => ['class' => 'datepicker']
   ]);
   

Key Files to Review

• Resources/doc/index.md: Official documentation with detailed usage examples.
• Form/Type/ directory: All available form types (e.g., DatePickerType.php, Select2Type.php).
• Resources/public/js/ and Resources/public/css/: Asset files for client-side behavior.

Implementation Patterns

Common Workflows

1. Basic Field Integration: Replace standard Symfony form fields with Thrace equivalents:

   // Before
   $builder->add('title', TextType::class);
   
   // After
   $builder->add('title', InputLimiterType::class, [
       'maxlength' => 100,
       'error_bubbling' => true
   ]);
   

2. jQueryUI Widgets: Configure jQueryUI-powered fields with options:

   $builder->add('budget', SliderType::class, [
       'min' => 0,
       'max' => 1000,
       'step' => 50,
       'options' => [
           'range' => 'min',
           'value' => 500
       ]
   ]);
   

3. Select2 Integration: Enhance <select> fields with search, tags, and AJAX:

   $builder->add('tags', Select2Type::class, [
       'choices' => $tags,
       'multiple' => true,
       'placeholder' => 'Select tags...',
       'ajax' => [
           'url' => $this->generateUrl('api_tags'),
           'data' => ['q' => 'term']
       ]
   ]);
   

4. TinyMCE Editor: Embed a WYSIWYG editor:

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

5. Collection Fields: Dynamically add/remove nested forms (e.g., for one-to-many relationships):

   $builder->add('items', CollectionType::class, [
       'entry_type' => ItemType::class,
       'allow_add' => true,
       'allow_delete' => true,
       'prototype' => true
   ]);
   

6. Dependent Fields: Chain Select2 fields where one field filters another:

   $builder->add('country', Select2Type::class, ['choices' => $countries]);
   $builder->add('city', Select2DependentType::class, [
       'choices' => $cities,
       'dependent_field' => 'country',
       'ajax_url' => $this->generateUrl('api_cities')
   ]);
   

Integration Tips

• Asset Management: Ensure jQuery and jQueryUI are loaded before Thrace assets. Use Symfony’s twig to include:

  {{ encore_entry_link_tags('app') }}
  <script src="{{ asset('bundles/thraceform/js/thrace-form.js') }}"></script>
  

• Configuration: Override default options in config/packages/thrace_form.yaml:

  thrace_form:
      datepicker:
          date_format: 'dd/MM/yyyy'
          autoclose: true
  

• Validation: Combine with Symfony’s validators:

  $builder->add('rating', RatingType::class, [
      'min' => 1,
      'max' => 5,
      'constraints' => [
          new NotBlank(),
          new Range(['min' => 1, 'max' => 5])
      ]
  ]);
  

• Doctrine Integration: For jqgrid multi-select, ensure ThraceDataGridBundle is installed and configured:

  $builder->add('roles', MultiSelectType::class, [
      'grid_options' => [
          'url' => $this->generateUrl('api_roles_grid')
      ]
  ]);
  

Gotchas and Tips

Common Pitfalls

1. Asset Loading Order:

   • Issue: jQueryUI widgets fail to initialize.
   • Fix: Ensure jQuery and jQueryUI are loaded before Thrace’s JS:

     <!-- Correct order -->
     <script src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
     <script src="https://code.jquery.com/ui/1.12.1/jquery-ui.min.js"></script>
     {{ encore_entry_link_tags('app') }}
     <script src="{{ asset('bundles/thraceform/js/thrace-form.js') }}"></script>
     

2. Symfony Version Mismatch:

   • Issue: Bundle fails to load with ClassNotFoundException.
   • Fix: Check composer.json requirements. For Symfony 4/5, use ~3.0 branch:

     composer require aqarmap/thrace-form-bundle@dev-master
     

3. TinyMCE Configuration:

   • Issue: TinyMCE editor not rendering.
   • Fix: Ensure tinymce is installed via npm and built:

     npm install tinymce
     yarn encore dev
     

   • Verify the config option in TinyMceType includes valid plugins/toolbar.

4. Select2 AJAX Dependencies:

   • Issue: Dependent fields fail to load data.
   • Fix: Ensure the AJAX endpoint returns data in the expected format:

     [
         {"id": 1, "text": "City 1"},
         {"id": 2, "text": "City 2"}
     ]
     

   • Check the ajax_url and data options in Select2DependentType.

5. CollectionType Prototype:

   • Issue: Dynamically added fields don’t submit.
   • Fix: Ensure prototype: true and the prototype template exists in your theme:

     {# templates/collection_prototype.html.twig #}
     <div class="collection-item">
         {{ form_row(form) }}
         <button type="button" class="remove-item">Remove</button>
     </div>
     

6. Recaptcha Validation:

   • Issue: Recaptcha fails silently.
   • Fix: Verify the site_key and secret in RecaptchaType match your reCAPTCHA settings. Enable error bubbling:

     $builder->add('recaptcha', RecaptchaType::class, [
         'error_bubbling' => true
     ]);
     

7. Date Format Mismatch:

   • Issue: Datepicker submits dates in an unexpected format.
   • Fix: Configure the date_format in the type options or globally:

     $builder->add('eventDate', DatePickerType::class, [
         'date_format' => 'Y-m-d', // ISO format
         'widget' => 'single_text'
     ]);
     

Debugging Tips

1. Console Errors:

   • Check browser console for missing assets or JS errors. Thrace relies on jQuery, so ensure $ is available globally.

2. Form Dumping: Use Symfony’s form dumper to inspect field options:

   $form->createView();
   dump($form->createView()->children);
   

3. Event Listeners: Override field behavior with events:

   $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
       $form = $event->getForm();
       $data = $event->getData();
       // Custom logic here
   });
   

4. Twig Debugging: For Select2 or TinyMCE, inspect rendered HTML to ensure assets are correctly included:

   {% if app.debug %}
       {{ dump(form.vars) }}
   {% endif %}
   

Extension Points

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