Getting Started

Minimal Steps to Begin

Installation Ensure Mailcoach is already installed in your Laravel project. Install the editor package via Composer:
```
composer require spatie/laravel-mailcoach-editor
```
Publish the package configuration (if needed):
```
php artisan vendor:publish --provider="Spatie\MailcoachEditor\MailcoachEditorServiceProvider"
```

Configuration Open config/mailcoach-editor.php and configure the tools array to define which Editor.js blocks you want to enable. Example:

'tools' => [
    \Spatie\MailcoachEditor\Tools\HeaderTool::class,
    \Spatie\MailcoachEditor\Tools\ParagraphTool::class,
    \Spatie\MailcoachEditor\Tools\ListTool::class,
    // Add more tools as needed
],

First Use Case Navigate to the Mailcoach dashboard in your Laravel app. When creating or editing a campaign, the Editor.js-based editor will now be available instead of the default textarea. Test by drafting a campaign with blocks like headers, paragraphs, or lists.

Implementation Patterns

Usage Patterns

Customizing Available Tools Extend the default tools by registering additional Editor.js tools in the tools array of the config file. For example, to include an image tool:
```
'tools' => [
    // Default tools...
    \Spatie\MailcoachEditor\Tools\ImageTool::class,
],
```
Ensure the tool class exists in the package or create a custom tool by extending Spatie\MailcoachEditor\Tools\Tool.
Integration with Mailcoach Workflows
- Campaign Creation: Use the editor when drafting new campaigns. The editor replaces the default WYSIWYG or textarea, offering a more structured, block-based approach.
- Templates: Apply the editor to campaign templates for consistent formatting across emails.
- A/B Testing: Leverage the editor’s block structure to create variations of email content for A/B tests.
Localization and Theming Customize the editor’s appearance by overriding the default CSS or JavaScript. Publish the package’s assets:
```
php artisan vendor:publish --tag=mailcoach-editor-assets
```
Modify the published files in public/vendor/mailcoach-editor.

Data Handling The editor outputs JSON-serialized data. Use Mailcoach’s built-in methods to retrieve and manipulate this data. Example:

$campaign = Mailcoach::campaigns()->find($id);
$editorData = $campaign->editorData; // JSON string
$blocks = json_decode($editorData, true); // Array of blocks

Gotchas and Tips

Pitfalls

Tool Configuration Conflicts Ensure all tool classes listed in the tools array exist and are properly namespaced. Missing or incorrect tool classes will result in runtime errors or broken editor functionality.
Editor.js Version Mismatch The package relies on a specific version of Editor.js. If you manually include Editor.js in your project (e.g., via CDN), ensure it matches the version expected by the package to avoid compatibility issues.
Data Serialization The editor outputs data as a JSON string. Always validate and sanitize this data before processing or storing it to prevent injection or malformed data issues. Use json_decode with JSON_THROW_ON_ERROR for strict validation:
```
$blocks = json_decode($editorData, true, 512, JSON_THROW_ON_ERROR);
```
Caching and Asset Loading If you publish and modify the editor’s assets (CSS/JS), clear your Laravel cache and browser cache to ensure changes take effect:
```
php artisan cache:clear
php artisan view:clear
```

Debugging Tips

Editor Not Loading Check the browser’s console for JavaScript errors. Ensure the Editor.js library and the package’s assets are loaded correctly. Verify the tools configuration in config/mailcoach-editor.php.
Tool-Specific Issues If a specific tool (e.g., image upload) fails, inspect the tool’s configuration and dependencies. For example, the ImageTool may require additional setup for file uploads or storage paths.
Data Not Saving Confirm that the editorData field is included in Mailcoach’s campaign model and that the data is being saved correctly. Use Laravel’s logging to debug:
```
\Log::info('Editor data:', ['data' => $editorData]);
```

Extension Points

Custom Tools Create custom Editor.js tools by extending Spatie\MailcoachEditor\Tools\Tool. Override methods like getConfig to define tool-specific behavior:

namespace App\MailcoachEditor\Tools;

use Spatie\MailcoachEditor\Tools\Tool;

class CustomTool extends Tool
{
    public function getConfig(): array
    {
        return [
            'title' => 'Custom Tool',
            'blocks' => [
                // Custom block configuration
            ],
        ];
    }
}

Hooks and Events Listen for Mailcoach events (e.g., campaign.saving) to manipulate editor data before it’s saved. Example:

Mailcoach::campaigns()->saving(function ($campaign) {
    $editorData = $campaign->editorData;
    // Modify $editorData as needed
    $campaign->editorData = json_encode($editorData);
});

API Integration Extend the editor to fetch or send data via API calls. For example, use the ImageTool to upload images to a custom endpoint:
```
'tools' => [
    \Spatie\MailcoachEditor\Tools\ImageTool::class => [
        'endpoint' => '/api/upload-image',
    ],
],
```
Ensure your API endpoint handles the upload and returns the expected Editor.js response format.

Laravel Mailcoach Editor Laravel Package