Tinymce Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bdjurisic/tinymce-bundle
   

   (Note: The README mentions stfalcon/tinymce-bundle, but the package name in the prompt is bdjurisic/tinymce-bundle. Use the correct package name.)

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

   return [
       // ...
       Bdjurisic\TinymceBundle\BdjurisicTinymceBundle::class => ['all' => true],
   ];
   

3. Install Assets:

   php bin/console assets:install public
   

4. First Usage in Twig:

   {{ tinymce('content') }}
   

   (Renders a TinyMCE editor for the content field.)

First Use Case

• Basic Editor Integration: Use {{ tinymce('field_name') }} in a form to replace a standard textarea with TinyMCE. Example:

  {{ form_row(article.content) }}
  {{ tinymce('article_content') }}  {# Override default textarea #}
  

Implementation Patterns

Common Workflows

1. Form Integration:

   • Replace form_row() or form_widget() for a TextareaType field:

     {{ form_row(article.body) }}
     {{ tinymce('article_body') }}
     

   • Use {{ form_row(article.body, {'attr': {'class': 'tinymce'}}) }} if you need to conditionally enable TinyMCE via JS.

2. Configuration via YAML: Define global settings in config/packages/bdjurisic_tinymce.yaml:

   bdjurisic_tinymce:
       tinymce_jquery: true  # Use jQuery version
       selector: 'textarea.tinymce'  # Target specific textareas
       plugins: ['advlist', 'autolink', 'lists']
       toolbar: 'bold italic bullist numlist link'
   

3. Dynamic Configuration: Override settings per field in Twig:

   {{ tinymce('field_name', {
       'plugins': ['image', 'code'],
       'toolbar': 'bold italic | image code'
   }) }}
   

4. Asset Management:

   • Customize TinyMCE skin/themes by overriding assets:

     mkdir -p public/build/tinymce
     cp vendor/bdjurisic/tinymce-bundle/Resources/public/tinymce/* public/build/tinymce/
     

   • Update config/packages/bdjurisic_tinymce.yaml to point to your custom path:

     bdjurisic_tinymce:
         base_url: '/build/tinymce'
     

5. Laravel-Specific Adaptation:

   • Symfony Bridge: Use SymfonyBridge to integrate with Laravel’s Blade:

     // In a service provider
     $this->app->singleton('tinymce', function () {
         return new \Bdjurisic\TinymceBundle\Twig\Extension\TinymceExtension();
     });
     

   • Blade Directive:

     // In a Blade service provider
     Blade::directive('tinymce', function ($expression) {
         return "<?php echo \$this->tinymce->render($expression); ?>";
     });
     

     Usage in Blade:

     @tinymce('content')
     

6. API-Driven Content:

   • Use TinyMCE’s setup callback to attach Laravel-specific logic (e.g., image uploads):

     {{ tinymce('content', {
         'setup': 'function(editor) {
             editor.on("init", function() {
                 editor.addButton("laravel_upload", {
                     text: "Upload",
                     onclick: function() { /* Laravel API call */ }
                 });
             });
         }'
     }) }}
     

Gotchas and Tips

Pitfalls

1. Bundle Name Mismatch:

   • The README references stfalcon/tinymce-bundle, but the package is bdjurisic/tinymce-bundle. Ensure you install the correct package to avoid ClassNotFoundException.

2. Asset Installation:

   • Forgetting to run assets:install will break TinyMCE’s JS/CSS loading. Always run:

     php bin/console assets:install public --symlink
     

3. jQuery Dependency:

   • If tinymce_jquery: true, ensure jQuery is loaded before TinyMCE. In Laravel, add to resources/views/layouts/app.blade.php:

     <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
     

4. Symfony 5+ Configuration:

   • The bundle expects config/packages/, not app/config/. Move YAML files to the correct location.

5. Twig Extension Conflicts:

   • If using other Twig extensions (e.g., VichUploaderBundle), ensure namespace collisions don’t occur. Prefix the extension class if needed:

     class BdjurisicTinymceExtension extends \Twig\Extension\AbstractExtension
     

6. Laravel Mix/Webpack:

   • If using Laravel Mix, exclude TinyMCE’s assets from processing to avoid bundling issues. Add to webpack.mix.js:

     mix.excludeChunks(['tinymce']);
     

Debugging

1. Console Errors:

   • Check for Uncaught ReferenceError: tinymce is not defined. This usually means:
     • Assets weren’t installed.
     • jQuery is missing or loaded after TinyMCE.
     • The selector in config doesn’t match your textarea’s class/ID.

2. Configuration Overrides:

   • Use dump() in Twig to verify settings:

     {{ dump(tinymce_config('field_name')) }}
     

3. Plugin Loading:

   • If plugins fail to load, ensure they’re listed in both:
     • Global config (plugins: [...]).
     • Field-specific config (if overridden).

Tips

1. Laravel-Specific Features:

   • CSRF Protection: TinyMCE’s AJAX uploads may need CSRF tokens. Use Laravel’s csrf_token() in JS:

     {{ tinymce('content', {
         'setup': 'function(editor) {
             editor.on("init", function() {
                 $.ajaxSetup({
                     headers: { "X-CSRF-TOKEN": "{{ csrf_token() }}" }
                 });
             });
         }'
     }) }}
     

2. Performance:

   • Lazy-load TinyMCE for non-critical forms by initializing it via JS:

     {{ tinymce('content', { 'init': false }) }}
     <script>
         $(document).ready(function() {
             tinymce.init({ selector: 'textarea#content' });
         });
     </script>
     

3. Custom Upload Handler:

   • Use Laravel’s routes to handle file uploads. Example route:

     Route::post('/tinymce-upload', [YourController::class, 'upload'])->name('tinymce.upload');
     

   • JS setup:

     {{ tinymce('content', {
         'images_upload_handler': 'function(blobInfo, success, failure) {
             var formData = new FormData();
             formData.append("file", blobInfo.blob(), blobInfo.filename());
             $.ajax("{{ route("tinymce.upload") }}", {
                 method: "POST",
                 data: formData,
                 processData: false,
                 contentType: false,
                 success: function(url) { success(url); }
             });
         }'
     }) }}
     

4. Version Pinning:

   • Lock TinyMCE’s version in composer.json to avoid breaking changes:

     "require": {
         "bdjurisic/tinymce-bundle": "^3.0"
     }
     

5. Testing:

   • Mock TinyMCE in PHPUnit by extending the Twig environment:

     $twig = new \Twig\Environment($loader);
     $twig->addExtension(new \Bdjurisic\TinymceBundle\Twig\Extension\TinymceExtension());
     

   • Use tinymce in tests to verify output:

     $this->assertStringContainsString('tinymce.init', $twig->render('template.html.twig'));