The pain of coding EDM (Email Direct Marketing) HTML is essentially a technical gap between modern design tools and rendering engines from twenty years ago.

In MasterGo or Figma, designers are accustomed to free 2D absolute positioning or modern Flexbox layouts. However, in email clients (especially Outlook), frontend developers still face the old-era table nesting, fully inline styles, and collective immunity to modern CSS properties. For an average marketing page, visual design might take just half an hour, but frontend development can take several times longer to manually translate the code. Once spacing or images need slight adjustments, it's back to square one.

To end this inefficient repetitive work, I developed a MasterGo plugin. Its core goal is simple: select a canvas and directly output a fully compatible email HTML.

The core value of this project lies in converging a tedious visual translation task into a clear layout tree reconstruction algorithm problem. Below is a detailed breakdown of this solution.

Core Contradiction: Converting Absolute Positioning to Constrained Flow Layout

Node data exported from design tools is inherently flat, 2D absolute positioning information:

interface SceneNode {
    x: number;
    y: number;
    width: number;
    height: number;
    // ... styles and hierarchy tree
}

An efficient and compatible EDM HTML, however, requires a highly constrained flow layout system:

Vertical direction: Relies on the natural document flow for stacking, controlling distances via spacer nodes or margin.
Horizontal direction: Fully abandons modern flex properties, reverting to using table with tr and td for deterministic multi-column layouts.
Style representation: Must implement pixel-level inline style injection to prevent styles from being blocked by email clients.

Thus, the core problem of the conversion is defined as: How to reconstruct absolutely positioned 2D nodes into a semantic layout tree (AST) suitable for flow rendering?.

Pipeline Design for Conversion

To ensure logical decoupling and extensibility, the entire core conversion process (located in the core package) is designed as a pure functional pipeline:

export function json2html(jsonData: IBaseComponent): string {
    const pipeFunc = pipe(
        transTreeStructData,  // 1. Structure reconstruction: Identify vertical hierarchy and horizontal alignment
        removeExcessEl,       // 2. Node cleaning: Remove meaningless visual template noise
        generateStructData,   // 3. Style derivation: Convert coordinates to flow layout styles
        generateHTMLCode      // 4. Code downgrade: Output highly compatible Table HTML
    );
 
    return pipeFunc(deepClone(jsonData)) as string;
}

The data evolution through the pipeline is illustrated below:

Core Algorithm: Reconstruction of the 2D Layout Tree

The most critical and complex step in the entire pipeline is transTreeStructData. Although the design file contains a layer tree, this tree structure is often just a grouping of visual containers and is not equivalent to the HTML DOM structure.

The algorithm re-derives the true layout relationships between nodes through two-pass scanning:

First Pass: Y-axis Segmentation, Building Vertical Flow

First, all child nodes under the current container are multi-level sorted by spatial coordinates:

arr = arr.sort((a, b) => {
    if (a.globalY !== b.globalY) {
        return a.globalY - b.globalY; // Rule 1: Sort by Y-axis top to bottom first
    }
    else if (a.height !== b.height) {
        return b.height - a.height;   // Rule 2: When Y-axis is the same, larger height nodes are processed first
    }
    else {
        return a.globalX - b.globalX; // Rule 3: Otherwise, sort by X-axis left to right
    }
});

Why are larger height nodes processed first?

In actual design files, the starting Y coordinates of outer large containers and inner small components often overlap. Prioritizing larger nodes allows for more stable identification of "containment" parent-child relationships during subsequent linear scans.

After sorting, linear scanning performs spatial merging:

If the current node's globalY exceeds the vertical range of the previous node, it is determined to be a new row.
If the current node's globalY and height are completely enveloped by the vertical range of the previous node, the X-axis is further checked. If the X-axis is also enveloped, it is mounted as a child node under the previous node, forming a nested structure.

Second Pass: X-axis Segmentation, Identifying Horizontal Alignment

After the vertical structure is determined, the horizontal arrangement of multiple elements at the same hierarchy needs to be resolved.

If multiple elements are within the same Y-axis interval, the algorithm implicitly creates a virtual flex container in the abstract syntax tree (AST) to wrap these adjacent nodes.

if (isSameYAxisArea(v, newArr[newArr.length - 1])) {
    // Create a virtual parent flex node
    const newFlexEl = createParentFlexEl(newArr[newArr.length - 1], v);
 
    newArr[newArr.length - 1] = {
        ...newFlexEl,
        children: sortByXAxis([
            newArr[newArr.length - 1],
            modifyAreaAndXY(v, newFlexEl),
        ]),
    };
}

It's important to emphasize that flex here is only an intermediate abstract semantic node, not the final generated CSS property. Its purpose is to explicitly mark "these elements are visually on the same row," providing a basis for the subsequent rendering layer to convert to a table structure.

Boundary and Tolerance Handling in Engineering Practice

Real engineering projects are not perfect algorithmic problems; design files often come with pixel-level errors.

1. 5px Spatial Tolerance Mechanism

Theoretically, for a horizontally centered component, the left and right spacing should be absolutely equal. However, when designers manually drag components, slight deviations often occur, such as a left spacing of 201px and a right spacing of 204px. If a strict mathematical equality check is used, the system might misjudge it as simple left alignment, causing a global visual shift in the final generated HTML.

To avoid this hard issue, the algorithm introduces a practical tolerance mechanism:

function isComponentXCenter(curNode: TComponent, parentNode: TComponent): boolean {
    const leftWidth = Math.abs(parentNode.globalX - curNode.globalX);
    const rightWidth = parentNode.globalX + parentNode.width - curNode.globalX - curNode.width;
 
    // Allow pixel error within 5px
    return Math.abs(leftWidth - rightWidth) <= 5;
}

By sacrificing absolute mathematical precision, it gains strong engineering stability for real design files.

2. Height Compensation Node (Bottom Padding Spacer)

In design files, containers often have a fixed height (Height). In HTML flow layout, however, container height is determined by its internal content. If there is blank space between the bottommost child node and the parent container edge, this space would be lost in flow rendering without handling.

To accurately reproduce the visual effect, a height compensation mechanism is added to the logic. When trailing remaining space is detected, a virtual placeholder node is automatically appended:

function getBottomHeightEl(el: IContainer, childrenLastEl: TComponent): IContainer {
    const newHeight = el.globalY + el.height - childrenLastEl.globalY - childrenLastEl.height;
 
    return {
        type: 'container',
        name: 'auto-height-spacer',
        structure: [`height: ${newHeight}px`],
        style: {},
        x: 0,
        y: 0,
        globalX: el.globalX,
        globalY: childrenLastEl.globalY + childrenLastEl.height,
        width: 0,
        height: newHeight,
    };
}

Rendering Layer Downgrade: Generating Highly Compatible HTML

In the final generateHTMLCode stage, abstract nodes from the AST are translated into low-level tags that email clients can reliably parse. Since engines like Outlook have very poor support for div margin and flex, the conversion strategy is thoroughly downgraded:

AST Node Type	Final Output HTML Structure	Core Logic and Compatibility Considerations
`flex` Container	`<table><tbody><tr>`	Use table rows to replace flex boxes, ensuring absolute horizontal alignment
`flex` Child Item	`<td>`	Inherit width, use `td` to break the vertical flow
Normal Block Node	`<div>` or `<table>`	Used for vertical flow stacking, with inline `margin-top` or empty rows for padding

When a flex abstract node is detected, the code constructs it as follows:

// Core abstraction conversion
case 'flex': {
    tag.push('<table border="0" cellpadding="0" cellspacing="0" width="100%">');
    tag.push('<tbody>');
    tag.push('<tr>');
    createFlexChildren(node, html);
    tag.push('</tr>');
    tag.push('</tbody>');
    tag.push('</table>');
    break;
}

Research Efficiency and Collaboration Conventions

In daily iteration, the interaction cost of a tool determines whether it can truly be adopted. Many efficiency tools ultimately reduce efficiency due to overly complex configuration panels.

This plugin uses layer naming conventions to replace a complex configuration UI. Designers simply append specific tags to the layer name to control the semantic output of the code:

Banner #image -> Forces recognition as an image component, automatically extracts assets.
CTA Button #link -> Automatically wraps with an <a> tag, reserves link placeholders.
Product Group #containerLink -> Makes the entire card have a global click behavior.

export const isImage = (nodeData: SceneNode): boolean => nodeData.name.toLowerCase().includes('#image');
export const isLink = (nodeData: SceneNode): boolean => nodeData.name.toLowerCase().includes('#link');

This design keeps the contract between development and design directly on the canvas, eliminating configuration costs and making the design file itself the single source of truth.

Conclusion

After introducing this plugin, the team achieved significant efficiency improvements in the EDM delivery process:

Time Reduction: The restoration time for a single complex marketing page was drastically reduced from the traditional 2-3 hours to 10-15 minutes.
Low Rework Cost: Faced with frequent visual adjustments, simply re-export from the design file with one click, without needing frontend developers to manually modify within the table source code.

Abstracting disorderly "manual labor" into structured algorithms is an effective path to eliminate repetitive work in the frontend development chain. By properly defining the data structures and boundaries, the subsequent code generation naturally falls into place.

0 Comments

Leave a Comment