Filament Ace Editor Field Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require jeffersongoncalves/filament-ace-editor-field:^2.0
   

2. Publish the config (optional, for customization):

   php artisan vendor:publish --tag=filament-ace-editor-field-config
   

3. Use in a Filament form:

   use JeffersonGoncalves\Filament\AceEditorField\Forms\Components\AceEditorInput;
   
   AceEditorInput::make('code_snippet')
       ->mode('php') // Defaults to 'text'
       ->height(200)
       ->required(),
   

First Use Case

Edit HTML snippets in a marketing page builder:

AceEditorInput::make('page_html')
    ->mode('html')
    ->theme('monokai')
    ->height(400)
    ->placeholder('<div>Your HTML here...</div>')
    ->validationRules(['required', 'max:10000']),

Implementation Patterns

Common Workflows

1. Dynamic Mode Selection: Use a mode() method to set syntax highlighting for different languages:

   AceEditorInput::make('config')
       ->mode('json') // or 'javascript', 'php', 'css', etc.
   

2. Conditional Theming: Tie themes to user preferences or roles:

   $theme = auth()->user()->prefers_dark_mode ? 'twilight' : 'chrome';
   AceEditorInput::make('script')->theme($theme),
   

3. Validation Integration: Combine with Filament’s validation rules:

   AceEditorInput::make('api_payload')
       ->mode('json')
       ->validationRules(['required', 'json']),
   

4. Read-Only Mode: Disable editing for display purposes:

   AceEditorInput::make('template')
       ->mode('handlebars')
       ->readOnly(),
   

Advanced Patterns

1. Custom Ace Editor Options: Pass additional Ace Editor configurations via extraOptions():

   AceEditorInput::make('sql_query')
       ->mode('sql')
       ->extraOptions([
           'showLineNumbers' => true,
           'tabSize' => 4,
           'fontSize' => '14px',
       ]),
   

2. Dynamic Height: Use JavaScript to adjust height based on content:

   AceEditorInput::make('large_code')
       ->mode('javascript')
       ->height(150)
       ->extraOptions(['autoScrollEditorIntoView' => true]),
   

3. Integration with Filament Tables: Use in table actions or inline editing:

   Tables\Columns\TextColumn::make('code_preview')
       ->toggleable(isToggledHiddenByDefault: true)
       ->copyable()
       ->extraAttributes(['class' => 'whitespace-pre-wrap']),
   

4. Multi-Field Coordination: Sync editor modes across related fields:

   // In a form component
   $language = $this->data['language'] ?? 'javascript';
   AceEditorInput::make('code')
       ->mode($language)
       ->reactive(),
   

Gotchas and Tips

Pitfalls

1. Filament Version Mismatch:

   • Error: Class 'JeffersonGoncalves\Filament\AceEditorField\Forms\Components\AceEditorInput' not found
   • Fix: Ensure Filament ^5.3 is installed (package requires it). Downgrade to ^1.x if using Filament ^4.8.

2. Missing Ace Editor Assets:

   • Error: Editor renders as blank or broken.
   • Fix: Run npm install && npm run dev (if using Vite) or php artisan filament:assets to compile assets.

3. Syntax Validation Bypass:

   • Risk: Users can switch modes (e.g., from html to javascript) to inject malicious code.
   • Fix: Restrict modes and validate server-side:

     AceEditorInput::make('html_content')
         ->mode('html')
         ->validationRules(['required', 'string']),
     

4. Performance with Large Files:

   • Issue: Slow rendering for files >10KB.
   • Fix: Use height() to limit visible lines or implement client-side chunking.

Debugging Tips

1. Check Console for Errors: Open browser dev tools (F12) to inspect Ace Editor initialization errors (e.g., missing modes).

2. Verify Config Publishing: If custom themes/modes aren’t working, ensure the config was published:

   php artisan vendor:publish --tag=filament-ace-editor-field-config --force
   

3. Inspect Extra Options: Use extraOptions(['behavior' => 'start']) to debug editor behavior.

4. Fallback for Unsupported Modes: If a mode (e.g., graphql) fails, fall back to text:

   $mode = in_array($this->data['language'], ['graphql', 'yaml']) ? $this->data['language'] : 'text';
   AceEditorInput::make('code')->mode($mode),
   

Extension Points

1. Custom Themes: Extend the package by publishing custom Ace themes:

   // config/filament-ace-editor-field.php
   'themes' => [
       'custom-theme' => resource_path('assets/ace/themes/custom-theme.css'),
   ],
   

2. Plugin Integration: Load Ace Editor plugins via extraOptions:

   AceEditorInput::make('code')
       ->extraOptions([
           'plugins' => ['textmate', 'wrap'],
           'textmate' => {
               'mode' => 'javascript',
               'theme' => 'monokai',
           },
       ]),
   

3. Server-Side Processing: Sanitize input before saving:

   // In a Filament Resource
   protected static function getValidationRules(): array
   {
       return [
           'code_snippet' => ['required', function ($attribute, $value, $fail) {
               if (str_contains($value, '<script>')) {
                   $fail('Script tags are not allowed.');
               }
           }],
       ];
   }
   

4. Localization: Translate placeholders and labels:

   AceEditorInput::make('description')
       ->placeholder(__('filament-ace-editor::fields.placeholder'))
       ->label(__('filament-ace-editor::fields.label')),