email-template-editor.md

Email Template Editor - Feature Documentation

A. High-Level Overview

The Email Template Editor is a comprehensive drag-and-drop email template creation system that allows users to design, edit, and manage email templates for review requests. Built around the Stripo email editor API, this feature provides a WYSIWYG interface where users can create personalized email templates with merge tags, validate content structure, import designs from other stores, and support multilingual content. The editor integrates with Yotpo's review request system, enabling users to craft engaging emails that drive customer engagement and review collection across different email types including reminders, targeted product requests, and site review requests.

B. Visual Diagrams (Using Mermaid.js)

1. Component Interaction Diagram

graph TB
    Container[EmailTemplateEditorContainerComponent] --> TemplateEditor[TemplateEditorComponent]
    Container --> ToolbarMenu[TemplateEditorToolbarMenuComponent]
    Container --> ImportModal[ImportEmailTemplateConfirmationModalComponent]
    
    TemplateEditor --> StripoService[StripoService]
    Container --> StripoService
    Container --> StoresService[StoresService]
    Container --> BlockValidator[StripoBlockValidationService]
    Container --> MergeTagValidator[StripoMergeTagValidationService]
    Container --> LoyaltyTracking[LoyaltyTrackingAnalyticsService]
    
    subgraph "External Dependencies"
        StripoAPI[Stripo API]
        YotpoAPI[Yotpo Backend]
        EmailTemplatesService[EmailTemplatesService]
    end
    
    StripoService --> StripoAPI
    StoresService --> YotpoAPI
    Container --> EmailTemplatesService
    
    subgraph "Data Flow"
        TemplateContent[TemplateContent]
        EditorConfig[EditorConfig]
        Store[Store]
    end
    
    Container --> TemplateContent
    Container --> EditorConfig
    Container --> Store

Loading

2. Data Flow Diagram

flowchart TD
    User[User Action] --> Container[Container Component]
    
    Container --> Init[Initialize Editor]
    Init --> LoadTemplate[Load Template from API]
    LoadTemplate --> StripoService[Stripo Service]
    StripoService --> StripoAPI[Stripo API]
    StripoAPI --> EditorReady[Editor Ready]
    
    EditorReady --> UserEdit[User Edits Template]
    UserEdit --> ContentChange[Content Change Event]
    ContentChange --> Validation[Content Validation]
    
    Validation --> BlockValidator[Block Validation Service]
    Validation --> MergeTagValidator[Merge Tag Validation]
    Validation --> ContentValidator[Content Validator]
    
    BlockValidator --> ValidationResult[Validation Result]
    MergeTagValidator --> ValidationResult
    ContentValidator --> ValidationResult
    
    ValidationResult --> SaveTemplate[Save Template]
    SaveTemplate --> YotpoAPI[Yotpo Backend]
    YotpoAPI --> SaveResult[Save Result]
    
    SaveResult --> User[User Feedback]
    
    subgraph "Import Flow"
        ImportRequest[Import Request] --> StoresService[Stores Service]
        StoresService --> GetStores[Get Available Stores]
        GetStores --> ImportDesign[Import Design]
        ImportDesign --> TemplateUpdate[Update Template]
    end

Loading

C. Technical Breakdown

1. Components

EmailTemplateEditorContainerComponent

• Purpose: Main container component that orchestrates the entire email template editing experience, managing state, validation, and user interactions.
• Inputs (@Input):
  • None (root component)
• Outputs (@Output):
  • None (handles events internally)
• Key Methods:
  • init(): Initializes the editor with template data and configuration
  • onSaveButtonClick(): Handles template saving with validation
  • switchLanguage(): Manages multilingual template switching

TemplateEditorComponent

• Purpose: Wrapper component that integrates the Stripo email editor and manages editor lifecycle events.
• Inputs (@Input):
  • storeId: string - Identifier for the current store
  • emailType: EmailType - Type of email being edited (reminder, targeted request, etc.)
  • reminderId: number - ID of the reminder being edited
  • name: string - Display name for the template
  • content: TemplateContent - HTML and CSS content of the template
  • config: EditorConfig - Configuration object for the Stripo editor
• Outputs (@Output):
  • onError: EventEmitter<Event> - Emitted when editor encounters an error
  • onLoad: EventEmitter<Event> - Emitted when editor is fully loaded
  • onContentChange: EventEmitter<Event> - Emitted when template content changes
  • onResetToDefault: EventEmitter<void> - Emitted when user requests template reset
• Key Methods:
  • onEditorLoaded(): Handles editor initialization and Stripo API setup
  • onContentChanged(): Processes content change events from the editor

TemplateEditorToolbarMenuComponent

• Purpose: Simple toolbar component that provides reset functionality for the template editor.
• Inputs (@Input):
  • None
• Outputs (@Output):
  • onResetToDefault: EventEmitter<void> - Emitted when reset button is clicked
• Key Methods:
  • handleResetToDefaultButtonClicked(): Triggers the reset event

ImportEmailTemplateConfirmationModalComponent

• Purpose: Modal component that allows users to import email template designs from other stores.
• Inputs (@Input):
  • open: boolean - Controls modal visibility
  • isLoading: boolean - Shows loading state during import
  • relatedStores: Store[] - List of available stores to import from
• Outputs (@Output):
  • onClose: EventEmitter<boolean> - Emitted when modal is closed
  • onImportDesign: EventEmitter<string> - Emitted when import is confirmed with store ID
• Key Methods:
  • importDesign(): Triggers the import process
  • hideImportEmailTemplateConfirmationModal(): Closes the modal

2. Services

StripoService

• Purpose: Core service that manages the Stripo email editor integration, handles API communication, and provides editor lifecycle management.
• Key Public Methods:
  • addCommonServicesToWindow(useGraphQLAPIFF: boolean): void - Injects required services into global window object for Stripo editor
  • setStripoApi(stripoApi: StripoApi): void - Sets the Stripo API instance for editor operations
  • stopEditor(): void - Stops and cleans up the editor instance
  • get isAllDataSaved(): boolean - Checks if all editor data is saved
• State Management: Maintains stripoApi instance and emailId for current editing session

StoresService

• Purpose: Service for managing store-related operations, particularly for importing email template designs from other stores.
• Key Public Methods:
  • getStores(): Observable<Store[]> - Retrieves list of available stores for import operations
  • importDesign(sourceStoreId: string): Observable<Object> - Imports email design from specified source store
• State Management: No internal state, provides stateless API operations

StripoBlockValidationService

• Purpose: Service responsible for validating the structure and content of email template blocks, ensuring proper email composition.
• Key Public Methods:
  • isStarsBlockValid(block: Element): boolean - Validates that stars rating block contains required elements
  • getStarsRatingBlockError(html: string): string[] - Returns validation errors for stars rating blocks
  • getEmailBodyBlockError(html: string): string - Validates presence of required email body blocks
• State Management: No internal state, provides validation logic

StripoMergeTagValidationService

• Purpose: Service for validating merge tags in email templates, ensuring proper syntax and allowed tag usage.
• Key Public Methods:
  • getAllTagsFromHTML(html: string): string[] - Extracts all merge tags from HTML content
  • getValidTagsFromHTML(html: string): string[] - Filters and validates merge tag syntax
  • getMergeTagsValidationErrors(tags: string[], emailType): string[] - Validates mandatory merge tags for specific email types
  • getAllowedTagsErrors(tags: string[]): string[] - Validates that only allowed merge tags are used
• State Management: No internal state, provides validation logic

LoyaltyTrackingAnalyticsService

• Purpose: Service for tracking user interactions and events within the email template editor for analytics purposes.
• Key Public Methods:
  • trackEvent(event: Partial<TrackingEvent>, additionalData?: any): void - Tracks user events with optional additional data
• State Management: No internal state, provides analytics tracking functionality

3. Data Models

Core Interfaces

• TemplateContent: Defines the structure of email template content with html: string and css: string properties
• TemplateParams: Contains template identification parameters including emailId: number, emailType: EmailType, and storeId: string
• TemplateEditorErrors: Defines validation error structure with properties for parse errors, merge tag errors, and block validation errors

Stripo Integration Models

• StripoApi: Interface defining the contract for Stripo editor API methods including initialization, template retrieval, and compilation
• ApiRequestData: Basic request data structure for API calls with emailId: number and optional storeId: string
• FeatureState: Type for feature flag states combining feature name and boolean value

Store and Configuration Models

• Store: Represents a store entity with properties for identification, creation date, enabled product categories, and store details
• ContextData: Simple context data structure with optional storeUrl property
• TrackingEvent: Analytics event structure with eventName: string and product: string properties

Merge Tag Constants

• MERGE_TAGS_MANDATORY: Object containing required merge tags for standard email templates
• MERGE_TAGS_MANDATORY_DISCOUNT: Required merge tags specifically for discount-related emails
• allowedTags: Array of all permitted merge tags for email templates
• MERGE_TAGS_OPTIONAL: Object containing optional merge tags for enhanced personalization

The email template editor feature provides a comprehensive solution for creating and managing email templates within the Yotpo review request system, with robust validation, multilingual support, and seamless integration with external email editing services.