Richer Editor Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require awcodes/richer-editor
   

2. Add CSS to your theme (in resources/css/app.css or filament.css):

   @import '../../../../vendor/awcodes/richer-editor/resources/css/index.css';
   @source '../../../../vendor/awcodes/richer-editor/resources/views/**/*.blade.php';
   

3. Basic usage in a Filament form:

   use Awcodes\RicherEditor\Plugins\EmbedPlugin;
   use Awcodes\RicherEditor\Plugins\LinkPlugin;
   
   RichEditor::make('content')
       ->plugins([
           EmbedPlugin::make(),
           LinkPlugin::make(),
       ])
       ->toolbarButtons(['embed', 'link'])
   

First Use Case

Add a rich editor to a Filament resource:

use Filament\Forms\Components\RichEditor;
use Awcodes\RicherEditor\Plugins\EmojiPlugin;

RichEditor::make('description')
    ->plugins([
        EmojiPlugin::make(),
    ])
    ->toolbarButtons(['emoji'])

Implementation Patterns

Plugin Integration Workflow

1. Select plugins based on needs (e.g., EmbedPlugin for YouTube, SourceCodePlugin for syntax highlighting).
2. Register plugins in the RichEditor component:

   RichEditor::make('content')
       ->plugins([
           EmbedPlugin::make(),
           SourceCodePlugin::make(),
       ])
   

3. Add toolbar buttons for UI accessibility:

   ->toolbarButtons(['embed', 'sourceCode'])
   

Custom Tool Groups (Dropdowns)

Organize tools into collapsible groups for cleaner UIs:

use Awcodes\RicherEditor\Tools\ToolGroup;

RichEditor::make('content')
    ->tools([
        ToolGroup::make('formatting')
            ->label('Formatting')
            ->icon('heroicon-o-text')
            ->items(['bold', 'italic', 'underline']),
    ])
    ->toolbarButtons(['formatting'])

Rendering Content

Convert rich content to HTML/Markdown:

// HTML output
$html = RichContentRenderer::make($content)->toHtml();

// Markdown output
$markdown = RichContentRenderer::make($content)->toMarkdown();

Faker for Testing

Generate mock rich content for testing:

$fakeContent = RichContentFaker::make()
    ->heading(level: 2)
    ->paragraphs(count: 3)
    ->asHtml();

Gotchas and Tips

Common Pitfalls

1. Missing CSS imports:

   • Forgetting to add @import for the package’s CSS will break styling.
   • Fix: Ensure index.css is imported in your theme.

2. Plugin conflicts:

   • Some plugins (e.g., DebugPlugin, FakerPlugin) are local-only and will throw errors in production.
   • Fix: Exclude them in production:

     if (app()->environment('local')) {
         RichEditor::make('content')->plugins([DebugPlugin::make()]);
     }
     

3. ToolGroup dropdowns:

   • Requires a shift key to open (fixed in v2.1.2+). Older versions may need manual JS tweaks.

4. Syntax highlighting:

   • PhikiCodeBlockPlugin is not database-compatible—use only for frontend rendering.

Debugging Tips

• Inspect toolbar buttons: Use DebugPlugin (local-only) to see registered tools:

  DebugPlugin::make()->showToolbarButtons(true)
  

• Check for invalid HTML: The SourceCodePlugin may fail on malformed tags. Validate input with:

  SourceCodePlugin::make()->validateTags(true)
  

Extension Points

1. Custom blocks: Extend HighlightedCodeBlock for new syntax themes:

   class CustomCodeBlock extends HighlightedCodeBlock {
       public function getTheme(): string {
           return Theme::Dracula;
       }
   }
   

2. Toolbar customization: Override default buttons via toolbarButtons():

   ->toolbarButtons(['customButton', 'embed'])
   

3. Faker customization: Add custom blocks to RichContentFaker:

   RichContentFaker::make()->customBlock(
       id: 'alert',
       config: ['type' => 'warning']
   )
   

Performance Notes

• Lazy-load plugins: Only include plugins you use to reduce bundle size.
• Avoid toMarkdown() in loops: It’s computationally expensive. Cache results if reused.

Filament-Specific Quirks

• Form persistence: Ensure IdPlugin is enabled if using LinkPlugin for anchor links.
• Livewire updates: RichEditor may trigger unnecessary Livewire updates. Use defer() for heavy plugins:

  RichEditor::make('content')
      ->plugins([EmbedPlugin::make()->defer()])