Filament Tiptap Editor Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require awcodes/filament-tiptap-editor
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Awcodes\FilamentTiptapEditor\FilamentTiptapEditorServiceProvider" --tag="config"
   

2. Basic Usage Register the editor in a Filament form:

   use Awcodes\FilamentTiptapEditor\Forms\Components\TiptapEditor;
   
   TiptapEditor::make('content')
       ->required()
       ->columnSpanFull(),
   

3. First Use Case Replace a standard Textarea or RichEditor with a more powerful WYSIWYG editor in a Filament resource:

   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               TiptapEditor::make('bio')
                   ->label('Biography')
                   ->rows(5),
           ]);
   }
   

Implementation Patterns

Common Workflows

1. Customizing Toolbar Extend the default toolbar via config (config/filament-tiptap-editor.php):

   'toolbar' => [
       'group1' => ['bold', 'italic', 'underline'],
       'group2' => ['bulletList', 'orderedList', 'blockquote'],
       // Add/remove buttons as needed
   ],
   

   Or dynamically in code:

   TiptapEditor::make('content')
       ->toolbar([
           ['bold', 'italic'],
           ['heading', '|', 'bulletList'],
       ]),
   

2. Handling Content

   • Storing HTML: The editor saves raw HTML by default. Use ->html() to retrieve it:

     $record->content; // Returns stored HTML
     

   • Sanitization: Use Laravel’s Str::of() or a package like spatie/laravel-html to sanitize before saving:

     $cleanHtml = Str::of($request->content)->sanitizeHtml();
     

3. Integration with Filament Tables Display formatted content in tables using ->toggleable() or custom render:

   use Awcodes\FilamentTiptapEditor\Tables\Columns\TiptapEditorColumn;
   
   TiptapEditorColumn::make('content')
       ->toggleable(isToggledHiddenByDefault: false),
   

4. Multi-Language Support Configure language packs via config:

   'lang' => 'es', // Spanish (default: 'en')
   

   Or per field:

   TiptapEditor::make('description')
       ->lang('fr'), // French
   

5. Validation Combine with Filament’s validation rules:

   TiptapEditor::make('terms')
       ->required()
       ->maxLength(5000),
   

Advanced Patterns

1. Dynamic Toolbar Based on User Role Override the toolbar in a Form modifier:

   public function form(Form $form): Form
   {
       return $form
           ->schema([
               TiptapEditor::make('content')
                   ->toolbar(auth()->user()->isAdmin() ? $adminToolbar : $defaultToolbar),
           ]);
   }
   

2. Custom Extensions Register Tiptap extensions via config or service provider:

   // config/filament-tiptap-editor.php
   'extensions' => [
       'StarterKit',
       'Tables',
       'CodeBlock',
   ],
   

   Or add custom extensions:

   TiptapEditor::make('content')
       ->extensions([
           new \Awcodes\FilamentTiptapEditor\Extensions\CustomExtension(),
       ]),
   

3. Live Preview Use the ->livewire() method to enable real-time updates:

   TiptapEditor::make('preview_content')
       ->livewire(),
   

4. Fallback for Non-JS Users Provide a fallback textarea:

   TiptapEditor::make('fallback_content')
       ->fallbackTextarea(),
   

Gotchas and Tips

Common Pitfalls

1. HTML Injection Risks

   • Issue: Storing unsanitized HTML can expose XSS vulnerabilities.
   • Fix: Always sanitize content before saving:

     $record->update(['content' => Str::of($request->content)->sanitizeHtml()]);
     

   • Tip: Use spatie/laravel-html for stricter sanitization:

     composer require spatie/laravel-html
     

     use Spatie\Html\HtmlFacade;
     $cleanHtml = HtmlFacade::sanitize($rawHtml);
     

2. Toolbar Button Misalignment

   • Issue: Custom toolbar buttons may not align properly.
   • Fix: Ensure buttons are grouped in arrays and separated by |:

     ->toolbar([
         ['bold', 'italic', '|', 'underline'],
         ['bulletList', 'orderedList'],
     ]),
     

3. Performance with Large Content

   • Issue: Laggy editing for very long documents.
   • Fix:
     • Limit max length via validation.
     • Use ->rows(10) to constrain initial textarea size.
     • Consider splitting content into multiple fields.

4. Conflicts with Other Filament Plugins

   • Issue: CSS/JS conflicts with plugins like filament-spatie-laravel-medialibrary.
   • Fix: Load the editor after other assets or use ->script() to defer:

     ->script(<<<'JS'
         document.addEventListener('DOMContentLoaded', function() {
             initTiptapEditor();
         });
     JS)
     

5. Database Storage Size

   • Issue: HTML content may exceed default database text limits.
   • Fix: Use ->columnType('longText') or adjust your DB column:

     Schema::table('posts', function (Blueprint $table) {
         $table->longText('content')->change();
     });
     

Debugging Tips

1. Console Errors

   • Check browser console for Tiptap-specific errors (e.g., missing extensions).
   • Enable debug mode in config:

     'debug' => env('APP_DEBUG', false),
     

2. Extension Loading

   • Verify extensions are registered in node_modules/@tiptap/extension-*.
   • Clear npm cache if extensions fail to load:

     npm cache clean --force
     npm install
     

3. Livewire Updates

   • If live updates don’t work, ensure the field is bound correctly:

     public $content = '';
     

   • Check for JavaScript errors in the Livewire console.

4. Config Overrides

   • Use php artisan config:clear after modifying filament-tiptap-editor.php.

Extension Points

1. Customizing the Editor Instance Pass a callback to modify the Tiptap editor instance:

   TiptapEditor::make('content')
       ->editor(function ($editor) {
           $editor
               ->addCommands({
                   toggleBold: () => editor.chain().focus().toggleBold().run(),
               });
       }),
   

2. Event Listeners Listen to editor events (e.g., onUpdate):

   ->script(<<<'JS'
       document.addEventListener('tiptap-editor-update', function(e) {
           console.log('Content updated:', e.detail.html);
       });
   JS)
   

3. Theming Override CSS variables in your app’s assets:

   .tiptap-editor {
       --tiptap-font-family: 'Inter', sans-serif;
       --tiptap-color: #333;
   }
   

4. Server-Side Processing Use model observers to process content on save:

   class PostObserver
   {
       public function saved(Post $post)
       {
           $post->content = Str::of($post->content)->markdown(); // Convert HTML to MD
           $post->save();
       }
   }