Tiny Editor Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require francescobruno-cmv/tiny-editor
   

   Publish the config (if needed) with:

   php artisan vendor:publish --provider="FrancescoBrunoCmv\TinyEditor\TinyEditorServiceProvider"
   

2. Register the Component Add the component to your Livewire blade file:

   <livewire:tiny-editor
       api-key="{{ config('services.tinymce.key') }}"
       wire:model="content"
       :settings="['height' => 400]"
   />
   

3. First Use Case Bind the editor to a Livewire property:

   public $content = '';
   
   // Handle submission
   public function save()
   {
       $this->validate(['content' => 'required']);
       // Save to DB
   }
   

Key Files to Review

• Config: config/tiny-editor.php (API key, default settings)
• Component Class: app/Http/Livewire/TinyEditor.php (if extending)
• Blade Template: resources/views/vendor/tiny-editor.blade.php (customization)

Implementation Patterns

Core Workflow

1. Livewire Integration Use wire:model to bind editor content to a Livewire property:

   <livewire:tiny-editor wire:model="post.body" />
   

   • Two-way binding: Updates Livewire property on content change.

2. Customizing TinyMCE Pass settings via :settings prop (TinyMCE config):

   <livewire:tiny-editor
       :settings="[
           'plugins' => 'image code',
           'toolbar' => 'bold italic | code',
           'images_upload_handler' => 'uploadImage'
       ]"
   />
   

3. Handling Uploads Implement a Livewire method for file uploads:

   public function uploadImage($file, $editorId)
   {
       $path = $file->store('uploads');
       return asset("storage/{$path}");
   }
   

   Bind it in Blade:

   <livewire:tiny-editor
       :upload-handler="['uploadImage']"
   />
   

4. Reactive Updates Listen for editor events (e.g., editorInit, editorChange):

   protected $listeners = [
       'editorInit' => 'onEditorInit',
       'editorChange' => 'onContentChange'
   ];
   

Advanced Patterns

• Dynamic API Key: Fetch from .env or a service:

  public $apiKey = config('services.tinymce.key');
  

• Multi-Editor Forms: Reuse the component with unique IDs:

  <livewire:tiny-editor wire:model="post.intro" id="intro-editor" />
  <livewire:tiny-editor wire:model="post.content" id="content-editor" />
  

• Presets: Define reusable editor configs in config/tiny-editor.php:

  'presets' => [
      'default' => ['height' => 400, 'plugins' => 'image'],
      'rich' => ['plugins' => 'image code link', 'toolbar' => 'full'],
  ],
  

  Use via :preset="rich".

Gotchas and Tips

Common Pitfalls

1. API Key Missing

   • Error: TinyMCE fails to load.
   • Fix: Ensure config('services.tinymce.key') is set in .env:

     TINYMCE_API_KEY=your_key_here
     

   • Debug: Check browser console for Invalid API key errors.

2. Livewire Property Not Updating

   • Cause: Missing wire:model or incorrect property name.
   • Fix: Verify the property exists in the Livewire class and is public:

     public $content = ''; // Must match wire:model="content"
     

3. Upload Handler Not Triggering

   • Cause: Incorrect method signature or missing wire:model.
   • Fix: Ensure the method matches TinyMCE’s expected format:

     public function uploadImage($file, $editorId) { ... }
     

   • Debug: Log $editorId to confirm it matches the editor’s ID.

4. CSS/JS Conflicts

   • Issue: TinyMCE styles interfere with your app.
   • Fix: Scope TinyMCE’s CSS/JS:

     <livewire:tiny-editor :styles="['container' => 'my-tinymce-class']" />
     

     Add to your CSS:

     .my-tinymce-class { /* override styles */ }
     

Debugging Tips

• Browser Console: Check for TinyMCE errors (e.g., missing plugins).
• Livewire Logs: Enable debug mode to trace property updates:

  public function mount()
  {
      $this->log('Editor mounted', 'debug');
  }
  

• Network Tab: Verify TinyMCE assets are loading (e.g., tinymce.min.js).

Extension Points

1. Custom Plugins Extend TinyMCE’s functionality by adding plugins to the :settings prop:

   <livewire:tiny-editor
       :settings="['plugins' => 'your-plugin']"
   />
   

   Register the plugin via TinyMCE’s API in a script:

   tinymce.PluginManager.add('your-plugin', function(editor) { ... });
   

2. Event Listeners Extend the component to emit custom events:

   // In Livewire component
   public function onEditorInit()
   {
       $this->dispatch('editor-ready');
   }
   

   Listen in Blade:

   @script
       window.addEventListener('livewire:init', () => {
           Livewire.on('editor-ready', () => { ... });
       });
   @endscript
   

3. Localization Override TinyMCE’s language files by passing :language:

   <livewire:tiny-editor :language="['language' => 'it_IT']" />
   

   Or publish the package’s language files:

   php artisan vendor:publish --tag=tiny-editor-lang
   

4. Performance

   • Lazy Load: Defer TinyMCE initialization until needed:

     public $lazyLoad = true;
     

   • Minify Assets: Use Laravel Mix to minify TinyMCE’s JS/CSS.

Configuration Quirks

• Default Settings: Override in config/tiny-editor.php:

  'default' => [
      'height' => 300,
      'menubar' => false,
  ],
  

• Environment-Specific Keys: Use Laravel’s config() helper:

  $apiKey = config('tiny-editor.api_key');
  

• Caching: TinyMCE caches API responses; clear cache if keys change:

  php artisan cache:clear