Ace Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require contao-components/ace
   

   Publish the assets (if needed):

   php artisan vendor:publish --tag=ace-assets
   

2. Basic Usage Include the editor in a Blade view:

   {!! Ace::editor('my_editor', $content, ['theme' => 'monokai', 'mode' => 'php'])->render() !!}
   

   • $content: Initial editor content (optional).
   • theme: Syntax theme (e.g., monokai, github).
   • mode: Language mode (e.g., php, javascript, html).

3. First Use Case Integrate with a Laravel form for rich-text editing:

   // Controller
   public function edit(Post $post) {
       return view('posts.edit', ['content' => $post->content]);
   }
   

   <!-- posts/edit.blade.php -->
   <form method="POST" action="/posts">
       @csrf
       {!! Ace::editor('content', old('content', $content), ['mode' => 'markdown'])->render() !!}
       <button type="submit">Save</button>
   </form>
   

Implementation Patterns

Common Workflows

1. Dynamic Editor Initialization Use JavaScript to initialize editors conditionally:

   $(document).ready(function() {
       if ($('#dynamic-editor').length) {
           Ace.edit('dynamic-editor').setTheme('chrome');
       }
   });
   

2. Integration with Laravel Forms Extend Illuminate\Support\Facades\Form for Ace-compatible fields:

   // app/Providers/AppServiceProvider.php
   use ContaoComponents\Ace\Facades\Ace;
   
   public function boot() {
       Form::macro('ace', function ($name, $value = null, $options = []) {
           return Ace::editor($name, $value, $options)->render();
       });
   }
   

   Usage:

   {!! Form::ace('description', $post->description, ['mode' => 'html']) !!}
   

3. Saving Editor Content Handle form submissions with AJAX for seamless updates:

   $('#editor-form').submit(function(e) {
       e.preventDefault();
       const content = Ace.edit('my_editor').getValue();
       $.post('/posts', { content, _token: '{{ csrf_token() }}' }, function() {
           alert('Saved!');
       });
   });
   

4. Multi-Editor Pages Manage multiple editors with unique IDs:

   @foreach($post->sections as $section)
       {!! Ace::editor("section_{$section->id}", $section->content, ['mode' => 'javascript'])->render() !!}
   @endforeach
   

Advanced Patterns

• Custom Themes/Plugins Load external ACE themes/plugins via CDN or local assets:

  {!! Ace::editor('code', $content, [
      'lib' => ['theme' => '//cdn.example.com/ace/themes/custom'],
      'plugins' => ['beautify']
  ])->render() !!}
  

• Real-Time Collaboration Use ACE’s ace.require('ace/ext/beautify') with Laravel Echo/Pusher for live editing.

• Server-Side Processing Sanitize/process editor content before saving:

  $cleanContent = purify($request->input('content')); // Use HTML Purifier or similar
  

Gotchas and Tips

Pitfalls

1. Asset Loading Conflicts

   • Issue: ACE may fail if jQuery or dependencies are loaded twice.
   • Fix: Ensure ACE’s assets are loaded after jQuery:

     @stack('scripts')
     @push('scripts')
         {!! Ace::assets()->render() !!}
     @endpush
     

2. CSRF Token Mismatch

   • Issue: AJAX submissions may fail if CSRF token isn’t included.
   • Fix: Always pass _token in AJAX calls (as shown in workflows).

3. Editor Not Initializing

   • Issue: Editor appears as plain <textarea>.
   • Debug: Check browser console for Ace is not defined. Ensure:
     • Assets are published (php artisan vendor:publish).
     • No JavaScript errors block ACE initialization.

4. Performance with Large Files

   • Issue: Slow rendering for files >100KB.
   • Fix: Lazy-load editors or use setValue() after DOM ready.

Debugging Tips

• Inspect Editor State:

  console.log(Ace.edit('editor_id').getSession().getDocument().getValue());
  

• Check ACE Version:

  console.log(Ace.version);
  

• Disable Plugins Temporarily: Pass plugins: [] to isolate issues.

Extension Points

1. Custom Commands Extend ACE’s behavior via JavaScript:

   Ace.edit('editor').commands.addCommand({
       name: 'save',
       bindKey: {win: 'Ctrl-S', mac: 'Command-S'},
       exec: function() { /* Custom logic */ }
   });
   

2. Server-Side Validation Validate editor content in Laravel:

   $validator = Validator::make($request->all(), [
       'content' => 'required|max:10000|mimes:text/plain,text/html',
   ]);
   

3. Theme/Mode Overrides Dynamically set themes/modes via Laravel config:

   config(['ace.default_theme' => env('ACE_THEME', 'monokai')]);
   

   Then use:

   {!! Ace::editor('code')->render() !!} <!-- Uses config default -->
   

4. Laravel Mix Integration Process ACE assets with Mix for caching:

   // resources/js/app.js
   require('ace-builds/src-min-noconflict/ace');
   require('ace-builds/src-min-noconflict/theme-monokai');