Trix Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bartosz-maciaszek/trix-bundle
   

   Add the bundle to config/bundles.php:

   BartoszMaciaszek\TrixBundle\TrixBundle::class => ['all' => true],
   

2. Basic Configuration Add Trix to your form (Symfony 5+):

   {{ form_widget(form.content, {'attr': {'data-controller': 'trix'}}) }}
   

   Include Trix assets in your base template:

   {{ encore_entry_script_tags('app') }} <!-- Ensure Trix JS is included via Encore -->
   

3. First Use Case Create a simple text field in a form:

   // src/Form/ArticleType.php
   public function buildForm(FormBuilderInterface $builder, array $options)
   {
       $builder->add('content', TextType::class, [
           'attr' => ['data-controller' => 'trix'],
       ]);
   }
   

   Ensure trix is enabled in config/packages/trix.yaml:

   trix:
       enabled: true
   

Implementation Patterns

Workflows

1. Form Integration

   • Use data-controller="trix" on textareas to auto-initialize Trix.
   • For dynamic forms (e.g., AJAX), trigger Trix manually:

     document.querySelectorAll('textarea[data-controller="trix"]').forEach(el => {
         new Trix.Editor(el);
     });
     

2. Asset Management

   • Configure assets via config/packages/trix.yaml:

     trix:
         assets:
             js: ['trix', 'trix-attachments'] # Custom JS files
             css: ['trix', 'custom-trix-styles'] # Custom CSS
     

   • Use Webpack Encore to bundle Trix with your app:

     // webpack.config.js
     Encore
         .addEntry('app', './assets/app.js')
         .addEntry('trix', 'trix')
         .copyFiles({
             from: './vendor/bartosz-maciaszek/trix-bundle/public',
             to: 'build/public/[path][name].[ext]',
         });
     

3. Server-Side Processing

   • Sanitize Trix HTML on submission (e.g., using symfony/html-sanitizer):

     use Symfony\Component\HtmlSanitizer\SanitizerInterface;
     
     public function submit(ArticleForm $form, SanitizerInterface $sanitizer)
     {
         $data = $form->getData();
         $data['content'] = $sanitizer->sanitize($data['content']);
         // Save to DB
     }
     

4. Dynamic Attachments

   • Configure file uploads in trix.yaml:

     trix:
         attachments:
             upload_dir: '%kernel.project_dir%/public/uploads'
             allowed_mime_types: ['image/jpeg', 'image/png']
     

   • Handle uploads via a custom controller (e.g., TrixAttachmentsController).

Gotchas and Tips

Pitfalls

1. Asset Loading

   • Issue: Trix JS/CSS fails to load.
   • Fix: Ensure encore is configured to copy Trix assets from vendor/bartosz-maciaszek/trix-bundle/public to public/build/.
   • Debug: Check browser console for 404 errors on /build/trix.*.

2. CSRF Token Conflicts

   • Issue: Trix uploads fail with CSRF errors.
   • Fix: Exclude Trix upload routes from CSRF protection in config/packages/security.yaml:

     security:
         access_control:
             - { path: ^/trix/attachments, roles: PUBLIC_ACCESS }
     

3. HTML Sanitization

   • Issue: Trix HTML breaks when saved to DB.
   • Fix: Use a sanitizer like symfony/html-sanitizer or white-october/pim-core-bundle's HtmlPurifier.
   • Tip: Allow safe Trix attributes (e.g., data-trix-content):

     $sanitizer->allowAttributes(['data-trix-content' => true]);
     

4. Dynamic Forms

   • Issue: Trix fails on dynamically added fields.
   • Fix: Reinitialize Trix after AJAX calls:

     $(document).on('trix-change', 'textarea[data-controller="trix"]', function() {
         // Handle changes
     });
     

Tips

1. Custom Toolbars

   • Extend Trix toolbar via config/packages/trix.yaml:

     trix:
         toolbar:
             buttons: ['bold', 'italic', 'strike', 'bullet-list', 'custom-button']
     

   • Add custom buttons using Trix plugins (e.g., trix-mentions).

2. Laravel Integration

   • For Laravel users, use symfony/bundle bridge:

     composer require symfony/bundle
     

   • Configure trix.yaml to work with Laravel’s asset pipeline.

3. Testing

   • Mock Trix in PHPUnit:

     $this->getContainer()->get('trix.helper')->setEditorEnabled(false);
     

   • Test uploads with symfony/panther:

     $client = static::createPantherClient();
     $crawler = $client->request('POST', '/upload', [
         'trix_attachment' => $file,
     ]);
     

4. Performance

   • Lazy-load Trix for non-critical forms:

     {% if is_granted('ROLE_EDITOR') %}
         {{ form_widget(form.content, {'attr': {'data-controller': 'trix'}}) }}
     {% else %}
         {{ form_widget(form.content) }}
     {% endif %}
     

   • Compress Trix assets in production:

     # config/packages/trix.yaml
     trix:
         assets:
             js: ['trix.min']
             css: ['trix.min']