Trumbowygbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require xlabs/trumbowygbundle
   

   Add to config/app.php under providers:

   Xlabs\TrumbowygBundle\TrumbowygBundle::class,
   

2. Basic Usage in Twig

   {{ trumbowyg({
       name: 'content',
       config: {
           btns: ['bold', 'italic', 'undo', 'redo']
       }
   }) }}
   

   Renders a WYSIWYG editor with minimal buttons.

3. First Use Case

   • Form Integration: Use in a Symfony form type:

     use Xlabs\TrumbowygBundle\Form\Type\TrumbowygType;
     
     $builder->add('description', TrumbowygType::class, [
         'config' => ['btns' => ['bold', 'link']],
     ]);
     

Implementation Patterns

Common Workflows

1. Dynamic Configuration Pass runtime config via Twig or form options:

   {{ trumbowyg({
       name: 'article_body',
       config: app.config.get('trumbowyg.defaults')
   }) }}
   

   Override defaults in config/packages/xlabs_trumbowyg.yaml.

2. Asset Management

   • Bundle auto-registers JS/CSS via Webpack Encore or Symfony Assets.
   • Customize paths in config/packages/xlabs_trumbowyg.yaml:

     assets:
         js: 'bundles/trumbowyg/js/trumbowyg.min.js'
         css: 'bundles/trumbowyg/css/trumbowyg.min.css'
     

3. Form Handling

   • Validation: Use Symfony’s constraints (e.g., Length) on Trumbowyg fields.
   • Data Binding: Clean HTML output with htmlspecialchars or a custom filter:

     $builder->add('content', TrumbowygType::class, [
         'mapped' => false,
         'attr' => ['data-sanitize' => true],
     ]);
     

4. Event Listeners

   • Extend editor behavior via JavaScript events (e.g., tbwyg.init):

     document.addEventListener('tbwyg.init', (e) => {
         if (e.detail.name === 'content') {
             e.detail.editor.addButton('custom', { ... });
         }
     });
     

Gotchas and Tips

Pitfalls

1. Asset Loading

   • Issue: JS/CSS fails to load if Webpack Encore isn’t configured.
   • Fix: Verify assets/install.js includes:

     import 'trumbowyg/dist/trumbowyg.min';
     

2. Form Submission

   • Issue: Raw HTML may break validation or cause XSS.
   • Fix: Use Symfony’s HtmlEntityEncoder or a custom form type extension:

     $builder->get('content')->addModelTransformer(new CallbackTransformer(
         fn($html) => strip_tags($html, '<p><strong><em>'),
         fn($text) => nl2br(e($text))
     ));
     

3. Configuration Overrides

   • Issue: Global config (config/packages/...) may conflict with per-field settings.
   • Fix: Use merge in Twig:

     {{ trumbowyg({
         config: app.config.get('trumbowyg.defaults')|merge({
             btns: ['bold', 'custom']
         })
     }) }}
     

Debugging Tips

• Console Errors: Check browser console for Uncaught TypeError (missing assets).
• Twig Debug: Enable debug: true in config/packages/twig.yaml to inspect rendered HTML.
• Editor Events: Log events via JavaScript:

  document.addEventListener('tbwyg.change', (e) => console.log(e.detail));
  

Extension Points

1. Custom Buttons Extend TrumboWYG’s buttons via JavaScript:

   $.extend(true, $.trumbowyg.btnsDef, {
       custom: {
           dropdown: ['sub1', 'sub2'],
           fn: (api) => { /* logic */ }
       }
   });
   

2. Symfony Integration

   • Form Events: Subscribe to PRE_SET_DATA/POST_SUBMIT to modify editor state:

     $builder->addEventListener(FormEvents::PRE_SET_DATA, fn($event) => {
         $event->getData()['config']['btns'][] = 'custom';
     });
     

3. Localization Override language files in translations/messages.xlabs_trumbowyg.en.yaml:

   trumbowyg:
       btns:
           bold: "Make it bold!"