@dearj/core

DearJ - Drag & Drop Email Editor Suite

🌟 Overview

The DearJ suite provides a powerful drag-and-drop email editor for modern web applications. With seamless integrations for frameworks like Angular and React, DearJ enables users to easily create and manage dynamic email templates. The suite is built on Unlayer's core technology, ensuring top-tier email design capabilities.

DearJ aims to offer a simple, framework-agnostic solution for embedding email editing functionality with a minimal API and an intuitive interface.

📦 Packages

• dearj - Core JavaScript library
• @dearj/types - TypeScript type definitions for the DearJ editor
• @dearj/angular - Angular wrapper component
• @dearj/react - React wrapper component

🚀 Features

• Framework-Specific Integrations: Native support for React and Angular.
• Drag & Drop Interface: Build complex email templates visually with an easy-to-use interface.
• Minimal API: Inspired by Zustand, offering simplicity and clarity in state management.
• Template Export: Export your email designs in both HTML and JSON formats.
• Security: Robust security model with token-based authorization.

📦 Installation

To install DearJ, simply use npm or yarn:

npm install dearj

or

yarn add dearj

🧑‍💻 Usage

Initialise the Editor

To initialize the editor, create an instance of the EmailEditor class and provide the necessary configuration.

import { EmailEditor } from "dearj";

const editor = new EmailEditor({
  authorization: "YOUR_AUTHORIZATION_TOKEN",
  // other configuration options
});

Mount the Editor

After initialization, you can mount the email editor inside a container element.

const container = document.getElementById("editor-container");
editor.mount(container);

Exporting Designs

Once you're done designing, you can export the email design as HTML or JSON.

// Export HTML
editor.exportHtml().then((html) => {
  console.log("Exported HTML: ", html);
});

// Export JSON
editor.exportJson().then((json) => {
  console.log("Exported JSON: ", json);
});

🛠️ API

The EmailEditor class provides several methods to manage the email editor's lifecycle and functionality.

new EmailEditor(config: EditorConfig, design: Template | null = null)

• config: An Object containing configuration for the email editor. Must include authorization as a string.
• design: (Optional) A template to load initially.

Methods

mount(container: HTMLElement): Mounts the email editor into a specified container element. unmount(): Removes the editor iframe and cleans up event listeners. onDesignUpdate(): Returns a Promise that resolves when the email design is updated. onDesignLoad(): Returns a Promise that resolves when the design is successfully loaded into the editor. exportHtml(): Returns a Promise that resolves with the HTML representation of the email template. exportJson(): Returns a Promise that resolves with the JSON data of the email template.

Event Handlers

You can register event handlers for different message types.

editor.registerHandler("UPDATED", (data) => {
  console.log("Design updated:", data);
});

Types of events:

• "UPDATED": Fired when the email design is updated.
• "LOADED": Fired when the email design is loaded.
• "EXPORT_HTML": Fired when HTML export is requested.
• "EXPORT_JSON": Fired when JSON export is requested.

Security

DearJ employs secure message passing between the editor iframe and the parent window. The verifyMessageSecurity function ensures that messages from the iframe are validated using a security token. This prevents unauthorized access and tampering.

⚡ Performance

DearJ is built with performance in mind, leveraging efficient state updates and ensuring minimal re-renders, especially in React applications. Its lightweight and optimized design ensures smooth user experience even with complex email templates.

📝 License

DearJ is available under the BSD-3-CLAUSE License.