Richer Editor Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require awcodes/richer-editor
   

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

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

3. Basic Usage in a Form:

   use Awcodes\RicherEditor\Plugins\EmojiPlugin;
   use Awcodes\RicherEditor\Plugins\LinkPlugin;
   
   RichEditor::make('content')
       ->plugins([
           EmojiPlugin::make(),
           LinkPlugin::make(),
       ])
       ->toolbarButtons([
           'bold', 'italic', 'link', 'emoji',
       ]);
   

First Use Case: Enhanced Content Editing

Replace a basic RichEditor field with this package to add plugins like syntax highlighting, embeds, or emojis. Example:

RichEditor::make('article_content')
    ->plugins([
        CodeBlockShikiPlugin::make()->defaultTheme('github-dark'),
        EmbedPlugin::make(),
    ])
    ->toolbarButtons([
        'bold', 'italic', 'codeBlock', 'embed',
    ]);

Implementation Patterns

Plugin Integration Workflow

1. Select Plugins: Choose plugins based on use case (e.g., CodeBlockShikiPlugin for developers, EmbedPlugin for media-rich content).

   ->plugins([
       CodeBlockShikiPlugin::make()->languages(['php', 'js']),
       FullScreenPlugin::make(),
   ])
   

2. Organize Toolbar: Group related tools (e.g., headings, developer tools) into dropdowns for cleaner UIs.

   ->tools([
       ToolGroup::make('headings')
           ->items(['h1', 'h2', 'h3'])
           ->icon('heroicon-o-text-increase'),
   ])
   ->toolbarButtons(['headings', 'bold', 'italic']);
   

3. Customize Rendering: Extend rendering behavior (e.g., convert headings to links or markdown).

   RichContentRenderer::make($content)
       ->linkHeadings(level: 2)
       ->toHtml();
   

Common Patterns

• Syntax Highlighting: Use CodeBlockShikiPlugin for live code editing with themes. Sync themes between editor and server-side rendering:

  // Editor
  CodeBlockShikiPlugin::make()
      ->defaultTheme('tokyo-night')
      ->themes(light: 'github-light', dark: 'github-dark');
  
  // Renderer
  RichContentRenderer::make($content)
      ->plugins([
          CodeBlockShikiPlugin::make()
              ->themes(light: 'github-light', dark: 'github-dark'),
      ]);
  

• Faker for Testing: Generate realistic test content with RichContentFaker:

  $fakeContent = RichContentFaker::make()
      ->heading(level: 1)
      ->paragraphs(count: 3)
      ->codeBlock(language: 'php')
      ->asHtml();
  

• Custom Blocks: Add custom blocks (e.g., highlighted code) via blocks():

  RichEditor::make('content')
      ->blocks([HighlightedCodeBlock::class]);
  

Gotchas and Tips

Pitfalls

1. Theme Dependency:

   • Issue: Dark/light themes for CodeBlockShikiPlugin require index.css to be imported. Forgetting this breaks dark mode.
   • Fix: Always include the CSS import in your theme file.

2. Plugin Conflicts:

   • Issue: LinkPlugin requires IdPlugin (for anchor IDs). Omitting it causes errors.
   • Fix: Include both plugins:

     ->plugins([
         IdPlugin::make(),
         LinkPlugin::make(),
     ]);
     

3. Experimental Plugins:

   • Issue: FigurePlugin and VideoPlugin are marked experimental. Use at your own risk.
   • Fix: Avoid in production until stability is confirmed.

4. Server-Side Rendering:

   • Issue: Shiki (browser-based) won’t highlight code on server-side renders. Use PhikiCodeBlockPlugin for server-side syntax highlighting:

     RichContentRenderer::make($content)
         ->plugins([PhikiCodeBlockPlugin::make()])
         ->phikiCodeBlocks();
     

5. Deprecated Tools:

   • Issue: HeadingFourTool, HeadingFiveTool, and HeadingSixTool are deprecated. Use Filament’s built-in heading tools instead.

Debugging Tips

• DebugPlugin: Enable in development to inspect editor state:

  DebugPlugin::make(), // Only works locally
  

• Console Logs: Check browser console for Tiptap/Shiki errors (e.g., missing themes or plugins).

Extension Points

1. Custom Themes: Extend CodeBlockShikiPlugin to support custom Shiki themes:

   CodeBlockShikiPlugin::make()
       ->themes(light: 'my-custom-theme', dark: 'my-dark-theme');
   

2. RichContentFaker: Extend RichContentFaker to add domain-specific content:

   class CustomRichContentFaker extends RichContentFaker {
       public function customBlock(): self {
           $this->content .= '<custom-block data="example"></custom-block>';
           return $this;
       }
   }
   

3. Toolbar Customization: Dynamically hide/show buttons based on user roles:

   ->toolbarButtons(fn (User $user) => $user->isAdmin ? ['debug'] : []),
   

Performance Notes

• Shiki Themes: Prefer smaller themes (e.g., github-dark) to reduce bundle size.
• Lazy-Load Plugins: Load heavy plugins (e.g., CodeBlockShikiPlugin) only when needed via conditional toolbar buttons.