README

A collection of extensions and tools to enhance the Filament Rich Editor field.

Installation

You can install the package via composer:

composer require awcodes/richer-editor

Important

If you have not set up a custom theme and are using Filament Panels follow the instructions in the Filament Docs first.

After setting up a custom theme add the plugin's css and views to your theme.css file or your app.css file if using the standalone packages.

@import '../../../../vendor/awcodes/richer-editor/resources/css/index.css';

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

Editor Usage

Warning

The following plugins are experimental and should not be used at the moment. See their docblocks for more information.

• CodeBlockLowlightPlugin
• CodeBlockShikiPlugin
• FigurePlugin
• VideoPlugin

Plugins

use Awcodes\RicherEditor\Plugins\DebugPlugin;
use Awcodes\RicherEditor\Plugins\EmbedPlugin;
use Awcodes\RicherEditor\Plugins\EmojiPlugin;
use Awcodes\RicherEditor\Plugins\FullScreenPlugin;
use Awcodes\RicherEditor\Plugins\IdPlugin;
use Awcodes\RicherEditor\Plugins\LinkPlugin;
use Awcodes\RicherEditor\Plugins\SourceCodePlugin;

RichEditor::make('content')
    ->plugins([
        DebugPlugin::make(), // only works in local environment
        EmbedPlugin::make(),
        EmojiPlugin::make(), // Doesn't have a toolbar button
        FullScreenPlugin::make(),
        IdPlugin::make(), // Doesn't have a toolbar button
        LinkPlugin::make(), // Requires IdPlugin
        SourceCodePlugin::make(),
    ])
    ->toolbarButtons([
        ['embed', 'sourceCode', 'fullscreen', 'debug'],
    ])

Max Height

use Filament\Forms\Components\RichEditor\RichEditorTool;

RichEditor::make('content')
    ->maxHeight('400px')

Nested Tool Groups (Dropdowns)

use Awcodes\RicherEditor\Tools\ToolGroup;
use Filament\Forms\Components\RichEditor\RichEditorTool;

RichEditor::make('content')
    ->tools([
        ToolGroup::make('headingTools')
            ->label('Headings')
            ->icon(Heroicon::H1)
            ->displayAsLabel()
            ->items([
                'h1', 
                'h2', 
                'h3',
                RichEditorTool::make('h4')...
            ]),
    ])
    ->toolbarButtons([
        ['headingTools'],
    ])

Prebuilt Tools

• Heading Four Tool
• Heading Five Tool
• Heading Six Tool

use Awcodes\RicherEditor\Tools\HeadingFourTool;
use Awcodes\RicherEditor\Tools\HeadingFiveTool;
use Awcodes\RicherEditor\Tools\HeadingSixTool;

RichEditor::make('content')
    ->tools([
        HeadingFourTool::make(),
        HeadingFiveTool::make(),
        HeadingSixTool::make(),
    ])
    ->toolbarButtons([
        ['h4', 'h5', 'h6'],
    ])

Prebuilt Blocks

Highlighted Code Block (Phiki)

use Awcodes\RicherEditor\Blocks\HighlightedCodeBlock;

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

// when rendering the content you can change the theme using any of Phiki's supported themes. See https://phiki.dev/multi-themes

use Awcodes\RicherEditor\Blocks\HighlightedCodeBlock;
use Phiki\Theme\Theme;

RichContentRenderer::make($content)
    ->customBlocks([
        HighlightedCodeBlock::class => [
            'light' => Theme::GithubLight,
            'dark' => Theme::GithubDark,
        ],
    ])
    ->toHtml()

Rendering Usage

Rendering Headings as links

use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichContentRenderer::make($content)
    ->linkHeadings(level: 3, wrap: false)
    ->toHtml()

Rendering as Markdown

This feature uses HTML To Markdown for PHP by thephpleague. Please see their documentation for available options.

use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichContentRenderer::make($content)
    ->toMarkdown(options: [])

Rendering native code blocks with Phiki syntax highlighting.

Caution

This should NOT be used globally as it will not work with Filament's rich content attributes when storing/reading content in the database when in a form context.

use Awcodes\RicherEditor\Support\RichContentRenderer;
use Awcodes\RicherEditor\Plugins\PhikiCodeBlockPlugin;

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

Rendering Table of Contents

use Awcodes\RicherEditor\Support\TableOfContents;

TableOfContents::make($content)
    ->asHtml();
    
/** or as an array to handle the output yourself */

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

Utilities

Rich Content Faker

use Awcodes\RicherEditor\Support\RichContentFaker;

$richContent = RichContentFaker::make()
    ->heading(level: 2)
    ->paragraphs(
        count: 1, 
        links: false, 
        code: false, 
        bold: false, 
        italic: false, 
        underline: false, 
        strike: false, 
        subscript: false, 
        superscript: false, 
        mergeTags: [], 
        highlight: false
    )
    ->lead(pargraphs: 1, links: false)
    ->small(pargraphs: 1, links: false)
    ->list(count: 3, links: false, ordered: false)
    ->image(source: null, width: 1280, height: 720)
    ->details(open: false, links: false)
    ->code(className: 'language-php')
    ->codeBlock(language: 'sh', prefix: 'language-')
    ->blockquote()
    ->hr()
    ->br()
    ->table(cols: null)
    ->grid(cols: [1,1,1], breakpoint: 'md')
    ->customBlock(
        id: 'batman', 
        config: [
            'name' => 'Batman', 
            'color' => 'black', 
            'side' => 'hero'
        ]
    )
    ->emptyParagraph()
    // rendering (only use one)
    ->asHtml()
    ->asJson()
    ->asText();

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Adam Weston
• The League of Extraordinary Packages
• Phiki
• All Contributors

License

The MIT License (MIT). Please see License File for more information.