Laravel Mailcoach Codemirror Laravel Package

Getting Started

Minimal Steps

1. Installation Require the package via Composer in your Mailcoach project:

   composer require spatie/laravel-mailcoach-codemirror
   

   Publish the package assets (if needed):

   php artisan vendor:publish --provider="Spatie\MailcoachCodemirror\MailcoachCodemirrorServiceProvider"
   

2. Enable in Mailcoach Ensure you’re using Mailcoach v7+ (for MJML support). Add the editor to your Mailcoach installation by configuring it in config/mailcoach.php:

   'editor' => [
       'enabled' => true,
       'codemirror' => [
           'mode' => 'htmlmixed', // or 'mjml' if using MJML
       ],
   ],
   

3. First Use Case

   • Open a Mailcoach campaign in edit mode.
   • The CodeMirror editor replaces the default textarea, offering syntax highlighting, autocompletion, and MJML support (if configured).
   • Write HTML or MJML directly in the editor and preview changes in real-time.

Implementation Patterns

Core Workflows

1. HTML Editing with Syntax Highlighting

   • Use the editor for WYSIWYG-like HTML authoring without leaving Mailcoach.
   • Leverage CodeMirror’s built-in modes (e.g., htmlmixed, xml, javascript) via config:

     'codemirror' => [
         'mode' => 'htmlmixed',
         'lineNumbers' => true,
         'theme' => 'default', // or 'dracula', 'monokai', etc.
     ],
     

2. MJML Integration (v7+)

   • Enable MJML mode for design-first email composition:

     'codemirror' => [
         'mode' => 'mjml',
     ],
     

   • Write MJML markup (e.g., <mjml> tags) and let Mailcoach compile it to HTML on send.
   • Autocompletion for MJML tags/components (e.g., mj-button, mj-section) reduces manual errors.

3. Customizing the Editor

   • Add Plugins: Extend functionality with CodeMirror plugins (e.g., linting, foldCode):

     'codemirror' => [
         'plugins' => [
             'foldcode',
             'lintjs', // Example: Add JavaScript linting
         ],
     ],
     

   • Keybindings: Override defaults (e.g., disable Ctrl+Enter for send):

     'codemirror' => [
         'extraKeys' => [
             'Ctrl-Enter' => null, // Disable default send shortcut
         ],
     ],
     

4. Integration with Mailcoach Hooks

   • Use Mailcoach’s mailcoach.campaign.saving event to validate editor content before save:

     Mailcoach::campaignSaving(function ($campaign) {
         if ($campaign->html && strpos($campaign->html, '<script>') !== false) {
             throw new \Exception('Scripts are not allowed in emails.');
         }
     });
     

Gotchas and Tips

Pitfalls

1. MJML Mode Limitations

   • No real-time preview: MJML must be compiled by Mailcoach (v7+) to see the final HTML. Use the Mailcoach preview pane for accurate rendering.
   • Browser compatibility: Test MJML output in multiple email clients (e.g., Gmail, Outlook) via Mailcoach’s testing tools.

2. Asset Conflicts

   • If using Laravel Mix/Vite, ensure CodeMirror’s CSS/JS isn’t bundled twice. Exclude the package’s assets from your build:

     // vite.config.js
     exclude: ['resources/vendor/spatie/mailcoach-codemirror/**'],
     

3. Performance with Large Templates

   • CodeMirror can lag with very long HTML/MJML files (e.g., >50KB). Optimize by:
     • Using MJML for complex layouts (smaller markup).
     • Splitting templates into partials (if your Mailcoach version supports includes).

4. Plugin Incompatibility

   • Some CodeMirror plugins (e.g., show-hint) may conflict with Mailcoach’s existing JS. Test thoroughly after adding custom plugins.

Debugging

• Editor Not Loading? Check browser console for 404 errors on /vendor/spatie/mailcoach-codemirror/js/codemirror.js. Ensure assets are published:

  php artisan vendor:publish --tag=mailcoach-codemirror-assets
  

• MJML Autocompletion Missing? Verify Mailcoach v7+ is installed and the mode is set to 'mjml' in config. Clear config cache if needed:

  php artisan config:clear
  

Tips

1. Keyboard Shortcuts

   • Fold/Unfold Code: Use Ctrl+Shift+[/] to collapse MJML/HTML blocks.
   • Jump to Line: Ctrl+G (default CodeMirror shortcut).

2. Custom Themes

   • Override the default theme by linking a custom CSS file in your Mailcoach layout:

     <link rel="stylesheet" href="{{ asset('css/codemirror-theme.css') }}">
     

   • Example theme config:

     'codemirror' => [
         'theme' => 'custom-theme',
     ],
     

3. Validation Rules

   • Combine with Laravel’s validation to enforce safe HTML in campaigns:

     use Spatie\Html\HtmlFacade;
     
     Mailcoach::campaignSaving(function ($campaign) {
         $cleanHtml = HtmlFacade::clean($campaign->html);
         $campaign->html = $cleanHtml;
     });
     

4. Extending MJML Support

   • Add custom MJML components by extending the editor’s MJML mode. Override the package’s JS:

     // resources/js/mailcoach-codemirror-extensions.js
     CodeMirror.registerHelper('hint', 'mjml', function (editor) {
         // Custom MJML hints logic
     });
     

   • Load it after the package’s JS:

     <script src="{{ asset('vendor/spatie/mailcoach-codemirror/js/codemirror.js') }}"></script>
     <script src="{{ asset('js/mailcoach-codemirror-extensions.js') }}"></script>