Blocknote Filament Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require weave-php/blocknote-filament
   

   Ensure your composer.json meets the requirements (PHP 8.3+, Laravel 11+, Filament 3/4/5).

2. Register the Plugin (recommended): In your Panel configuration (e.g., app/Providers/Filament/AdminPanelProvider.php):

   public function panel(Panel $panel): Panel {
       return $panel
           ->plugins([
               BlockNotePlugin::make(),
           ]);
   }
   

3. First Usage: Add the field to a Filament form/resource:

   use Weave\BlockNote\Filament\Widgets\Forms\BlockNote;
   
   BlockNote::make('content')
       ->required()
       ->columnSpanFull(),
   

Key First Use Case

Replace a MarkdownEditor or RichEditor field with a BlockNote field for:

• Structured content (e.g., documentation, articles, or multi-format notes).
• Persistence as a JSON string (stored in your database).
• Real-time collaboration-ready UI (via BlockNote’s core features).

Implementation Patterns

Workflows

1. Basic Form Integration:

   // In a Filament Form
   BlockNote::make('editor_content')
       ->label('Article Content')
       ->helperText('Supports headings, lists, and embedded media.')
       ->required(),
   

2. Customizing Toolbar: Override default tools (e.g., hide the "code block" button):

   BlockNote::make('notes')
       ->toolbar([
           'bold', 'italic', 'heading', 'bulletList', 'numberedList',
           // Exclude 'codeBlock'
       ]),
   

3. Validation & Sanitization: Validate the JSON structure (e.g., ensure non-empty blocks):

   BlockNote::make('description')
       ->rules([
           'required',
           'json', // Basic JSON validation
           function (string $attribute, mixed $value, Closure $fail) {
               $blocks = json_decode($value, true);
               if (empty($blocks['content'])) {
                   $fail('The '.$attribute.' must contain at least one block.');
               }
           },
       ]),
   

4. Database Handling:

   • Storage: The field stores a JSON string (e.g., {"content":[{"type":"paragraph",...}]}).
   • Retrieval: Use json_decode() to parse in your models:

     $blocks = json_decode($model->content, true);
     

5. Dynamic Configuration: Pass options via configure():

   BlockNote::make('dynamic_content')
       ->configure([
           'initialContent' => json_encode(['content' => []]), // Preload empty
           'theme' => 'dark', // 'light' or 'dark'
       ]),
   

Integration Tips

• Filament Resources: Use in create/edit forms for structured content (e.g., CMS pages, support tickets).
• Livewire Components: Embed BlockNote in custom Livewire components by extending the field’s React logic (see BlockNote’s docs).
• API Responses: Return parsed blocks in API responses:

  return response()->json(['content' => json_decode($model->content)]);
  

Gotchas and Tips

Pitfalls

1. JSON Validation:

   • The field stores raw JSON. Validate with json_decode($value, true) to avoid malformed data.
   • Example rule:

     ->rules(['json', function ($value) {
         return json_decode($value, true) !== null;
     }]),
     

2. Toolbar Customization:

   • Incorrect tool names (e.g., 'bold' vs 'boldButton') will break the UI. Use BlockNote’s tool names.
   • Example of a broken config:

     // ❌ Won't work
     ->toolbar(['boldButton']), // Use 'bold' instead
     

3. Database Bloat:

   • Large JSON strings may bloat your database. Consider:
     • Compressing with gzip before storage.
     • Storing only essential blocks (e.g., strip metadata).

4. React Dependency:

   • BlockNote relies on React. Ensure your Filament panel’s Vite config includes:

     // vite.config.js
     export default defineConfig({
         plugins: [
             laravel({
                 input: ['resources/js/app.js'],
                 reactRefresh: true,
             }),
         ],
     });
     

Debugging

• Empty Editor:

  • Check if initialContent is valid JSON. Use:

    ->configure(['initialContent' => '{"content":[]}']),
    

  • Verify the field’s React component mounts (check browser console for errors).

• Toolbar Not Loading:

  • Clear Vite cache:

    npm run dev
    

  • Ensure no CSS conflicts (BlockNote uses Mantine styles).

Extension Points

1. Custom Block Types: Extend BlockNote’s schema by passing a custom schema in configure():

   ->configure([
       'schema' => [
           'blocks' => [
               'paragraph',
               'heading',
               // Add custom block types here
               'customBlock' => {
                   'props': {
                       'title': 'string',
                   },
               },
           ],
       ],
   ]),
   

2. Plugin Hooks: Use Filament’s plugin hooks to modify BlockNote’s behavior globally:

   BlockNotePlugin::make()
       ->modifyFormFieldsUsing(function (array $fields) {
           $fields['custom_field'] = BlockNote::make('custom')
               ->configure(['theme' => 'dark']);
           return $fields;
       }),
   

3. Localization: Override BlockNote’s labels (e.g., toolbar buttons) via Filament’s localization system:

   // lang/en/filament-blocknote.php
   return [
       'toolbar' => [
           'bold' => 'Make Bold',
       ],
   ];
   

4. Performance:

   • Lazy-load BlockNote in large forms by setting defer: true in the field’s config.
   • Use columnSpan to control layout:

     ->columnSpan('full'), // Full-width editor