Livewire Quill Text Editor Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dasundev/livewire-quill-text-editor
   

   Publish the config (optional):

   php artisan vendor:publish --provider="DasunDev\LivewireQuillTextEditor\LivewireQuillTextEditorServiceProvider"
   

2. First Use Case: Add the component to a Livewire blade view:

   <livewire:quill-editor wire:model="content" />
   

   Ensure your Livewire component has a content property:

   public $content = '';
   

3. Where to Look First:

   • Documentation for config options and API.
   • config/livewire-quill-text-editor.php for default settings (e.g., toolbar modules, theme).
   • Example components in resources/views/vendor/livewire-quill-text-editor.

Implementation Patterns

Core Workflows

1. Basic Integration:

   • Use wire:model to bind to a Livewire property:

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

   • Supports nested properties:

     <livewire:quill-editor wire:model="user.bio" />
     

2. Custom Toolbars: Configure via config or component attributes:

   <livewire:quill-editor
       wire:model="content"
       :toolbar="['bold', 'italic', 'link', 'clean']"
   />
   

   Or in config/livewire-quill-text-editor.php:

   'default_toolbar' => [
       ['bold', 'italic', 'underline'],
       ['link', 'image'],
       ['clean'],
   ],
   

3. Storing HTML: The editor returns sanitized HTML. Store it directly in the database (use html column type or text with proper escaping).

4. Preview Mode: Use the preview attribute to render a static preview:

   <livewire:quill-editor wire:model="content" preview />
   

5. Dynamic Configuration: Pass dynamic options via options attribute (PHP array):

   <livewire:quill-editor
       wire:model="content"
       :options="['theme': 'snow', 'modules': ['toolbar', 'history']]"
   />
   

Advanced Patterns

1. Multi-Editor Forms: Reuse the component for multiple fields:

   <livewire:quill-editor wire:model="post.intro" />
   <livewire:quill-editor wire:model="post.conclusion" />
   

2. Image Uploads: Integrate with Laravel File Uploads or custom endpoints:

   // In Livewire component
   public function uploadImage($file) {
       $path = $file->store('quill-images');
       return ['url' => asset("storage/{$path}")];
   }
   

   Configure in config/livewire-quill-text-editor.php:

   'upload_handler' => 'App\Http\Livewire\QuillUploadHandler',
   

3. Custom Modules: Extend Quill’s functionality by registering custom modules:

   // In a separate JS file
   Quill.register('modules/customModule', CustomModuleClass);
   

   Load it via the options attribute:

   :options="['modules': ['customModule']]"
   

4. Validation: Validate HTML content in Livewire rules:

   use Illuminate\Validation\Rule;
   
   $rules = [
       'content' => [
           'required',
           Rule::html(), // Use a package like `spatie/laravel-html` for validation
       ],
   ];
   

Gotchas and Tips

Common Pitfalls

1. HTML Sanitization:

   • The editor sanitizes output by default. If you need raw HTML, disable sanitization in config:

     'sanitize_html' => false,
     

   • Warning: This exposes your app to XSS risks. Use a sanitizer like htmlpurifier if needed.

2. CORS for Uploads: If using custom upload handlers, ensure CORS is configured for the endpoint:

   // In your upload route middleware
   return response()->json(['url' => $url]);
   

3. Livewire Property Binding:

   • Ensure the bound property is public or uses public function setContent($value).
   • Avoid binding to non-string properties (e.g., wire:model="user->posts" may fail).

4. Quill JS Conflicts:

   • If using multiple Quill instances on a page, ensure unique IDs or namespaces:

     <livewire:quill-editor wire:model="content" name="editor-1" />
     

5. Toolbar Module Names:

   • Quill’s module names are case-sensitive (e.g., 'bold' vs 'Bold'). Check the Quill docs for exact names.

Debugging Tips

1. Console Errors: Check browser console for Quill initialization errors. Common issues:

   • Missing Quill JS/CSS (ensure @livewireScripts and @livewireStyles are included).
   • Invalid toolbar modules (e.g., typo in module name).

2. Livewire Logs: Enable Livewire logging to debug property updates:

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

   in config/livewire.php.

3. Network Requests: Inspect failed uploads or API calls in the Network tab. Look for:

   • 403/401 errors (CORS/auth issues).
   • Missing CSRF tokens (ensure @csrf is present in forms).

Extension Points

1. Custom Themes: Override Quill’s default theme by extending its CSS:

   /* resources/css/quill-custom.css */
   .ql-theme-custom {
       /* Your custom styles */
   }
   

   Load it in your layout:

   <link rel="stylesheet" href="{{ asset('css/quill-custom.css') }}">
   

2. Event Listeners: Listen to Quill events (e.g., text-change) via JavaScript:

   document.addEventListener('livewire:init', () => {
       Livewire.hook('quill-editor-initialized', (component, editor) => {
           editor.on('text-change', () => {
               console.log('Content changed!');
           });
       });
   });
   

3. Server-Side Processing: Use Livewire’s updatedContent hook to process HTML before saving:

   public function updatedContent($value) {
       $this->content = Str::limit($value, 1000); // Truncate long content
   }
   

4. Fallback for JavaScript: Provide a fallback for users without JS:

   @if (request()->wantsJson() || !app()->environment('production'))
       <livewire:quill-editor wire:model="content" />
   @else
       <textarea wire:model="content">{{ $content }}</textarea>
   @endif
   

Configuration Quirks

1. Default Values: The config file merges with component attributes. Component attributes override config:

   <livewire:quill-editor :options="['theme': 'bubble']" />
   

   Overrides config['default_theme'].

2. Lazy Loading: Disable lazy loading if you need the editor to initialize immediately:

   'lazy_load' => false,
   

   in config/livewire-quill-text-editor.php.

3. Module Dependencies: Some Quill modules require others (e.g., history needs toolbar). Ensure dependencies are included:

   'default_modules' => [
       'toolbar',
       'history',
       'clipboard',
   ],