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):

   @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\EmojiPlugin;
   
   RichEditor::make('content')
       ->plugins([
           EmbedPlugin::make(),
           EmojiPlugin::make(),
       ])
       ->toolbarButtons(['embed', 'emoji'])
   

First Use Case: Embedding Content

Add the EmbedPlugin to allow users to embed YouTube videos, tweets, or other media:

RichEditor::make('description')
    ->plugins([EmbedPlugin::make()])
    ->toolbarButtons(['embed'])

Implementation Patterns

Plugin Integration Workflow

1. Select Plugins: Choose plugins based on use case (e.g., LinkPlugin for internal linking, SourceCodePlugin for code snippets).

   RichEditor::make('content')
       ->plugins([
           LinkPlugin::make(), // Requires IdPlugin
           SourceCodePlugin::make(),
       ])
   

2. Organize Toolbar: Group related tools (e.g., headings, formatting) into logical sections:

   ->toolbarButtons([
       ['bold', 'italic', 'underline'],
       ['h1', 'h2', 'h3'],
       ['embed', 'sourceCode'],
   ])
   

3. Customize Rendering: Use RichContentRenderer to transform content post-submission:

   RichContentRenderer::make($content)
       ->linkHeadings(level: 3) // Auto-link H3 headings
       ->toHtml();
   

Common Patterns

• Code Blocks: Use HighlightedCodeBlock for syntax-highlighted code with Phiki:

  RichEditor::make('code_example')
      ->blocks([HighlightedCodeBlock::class])
      ->plugins([PhikiCodeBlockPlugin::make()]);
  

• Tables of Contents: Generate TOCs dynamically:

  $toc = TableOfContents::make($content)->asHtml();
  

• Faker for Testing: Generate mock content for development:

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

Integration Tips

• Filament Forms: Attach to any RichEditor field in Filament forms/resources.
• Livewire Components: Use the editor in custom Livewire components by extending RichEditor logic.
• API Responses: Serialize rendered content (HTML/Markdown) in API responses:

  return response()->json([
      'content' => RichContentRenderer::make($content)->toMarkdown(),
  ]);
  

Gotchas and Tips

Pitfalls

1. Plugin Dependencies:
   • LinkPlugin requires IdPlugin (adds IDs to headings for linking).
   • Experimental plugins (CodeBlockLowlightPlugin, VideoPlugin) may need manual setup.
2. CSS Conflicts: Ensure @import paths in app.css match your project structure. Use npx tailwindcss to debug.
3. Database Storage: Avoid phikiCodeBlocks() globally—it breaks Filament’s rich content attributes. Use only for rendering.
4. Emoji/Id Plugins: These lack toolbar buttons; add them via JavaScript if needed:

   document.querySelector('.rich-editor-toolbar').insertAdjacentHTML('beforeend', '<button data-tooltip="Emoji">😊</button>');
   

Debugging

• Invalid Tags: If SourceCodePlugin fails, check for malformed HTML tags (e.g., unclosed <pre>). Use ->debug() in local environments.
• Toolbar Misalignment: Add shift to ToolGroup dropdowns (fixed in v2.1.2+):

  ToolGroup::make('tools')
      ->shift(true) // Ensures proper dropdown positioning
  

• Phiki Themes: Validate theme names (e.g., Theme::GithubLight) against Phiki’s docs.

Extension Points

1. Custom Blocks: Extend HighlightedCodeBlock for domain-specific syntax:

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

2. Toolbar Buttons: Add custom buttons via JavaScript:

   document.addEventListener('filament-rich-editor-initialized', (e) => {
       e.detail.editor.addButton('custom', 'Custom Tool', () => {
           // Logic here
       });
   });
   

3. Faker Customization: Override RichContentFaker methods to generate domain-specific content:

   RichContentFaker::make()
       ->customBlock(id: 'api-reference', config: ['endpoint' => '/users']);
   

Performance Tips

• Lazy-Load Plugins: Load heavy plugins (e.g., PhikiCodeBlockPlugin) only when needed:

  if (request()->has('render_as_code')) {
      $renderer->plugins([PhikiCodeBlockPlugin::make()]);
  }
  

• Cache Rendered Content: Cache TOCs or Markdown conversions if used frequently:

  $toc = Cache::remember("toc_{$content}", now()->addHours(1), fn() =>
      TableOfContents::make($content)->asArray()
  );