Control

Core class for creating custom controls in the Stripo Email Editor Extensions SDK.

class Control

Description

The Control class provides the foundation for creating custom settings panel controls that allow users to modify email elements. Controls appear in the settings panel when an element is selected and provide an interface for editing properties such as colors, sizes, fonts, and other attributes. By extending this class, you can create rich, interactive controls with custom UI elements and behavior.

Import

import { Control } from '@stripoinc/ui-editor-extensions';

Constructor

The constructor is typically called by the extension framework when instantiating your control.

Properties

api

api: ControlApi

Provides access to editor functionalities specific to this control instance, including document access, UI element management, and template modification capabilities. Automatically injected by the framework.

Methods

getId()

Retrieves the unique identifier for this control type.

getId(): string

Returns

string - Unique identifier for the control

Usage Notes

• Must be unique across all controls
• Used for registration and internal referencing

Example

public getId(): string {
    return 'custom-gradient-control';
}

---

getTemplate()

Retrieves the HTML template string that defines the control's UI structure.

getTemplate(): string

Returns

string - HTML template containing UI elements

Usage Notes

• Use custom UI element tags (e.g., <${UIElementType.LABEL}>, <${UIElementType.SWITCHER}>)
• Can include custom HTML for layout and styling
• Template is parsed and rendered by the editor

Example

public getTemplate(): string {
    return `
        <div class="container two-columns">
            <${UIElementType.LABEL} ${UEAttr.LABEL.text}="Settings:"></${UIElementType.LABEL}>
            <${UIElementType.SWITCHER} ${UEAttr.SWITCHER.name}="enableFeature"></${UIElementType.SWITCHER}>
        </div>
    `;
}

---

onTemplateNodeUpdated()

Called whenever the underlying template node associated with this control is updated.

onTemplateNodeUpdated(node: ImmutableHtmlNode): void

Parameters

Parameter	Type	Description
node	ImmutableHtmlNode	The updated HTML node representing the control's context

Usage Notes

• Called on every modification to the selected element
• Use to sync control values with the actual element state
• Update UI elements to reflect current node properties
• Avoid heavy computations - called frequently

Example

public onTemplateNodeUpdated(node: ImmutableHtmlNode): void {
    // Extract values from the template
    const currentCount = parseInt(node.getAttribute('data-count') || '3');
    const style = node.getAttribute('data-style') || 'classic';

    // // Update UI to reflect template state
    this.api.updateValues({
        'itemCount': currentCount,
        'styleSelect': style
    });
}

isVisible()

Determines if the control should be visible in the control panel.

public isVisible(node: ImmutableHtmlNode): boolean

Parameters

Parameter	Type	Description
node	ImmutableHtmlNode	The selected node

Returns

boolean - true to show control, false to hide

Default Implementation

Returns true (always visible)

Usage Notes

• Override to conditionally show/hide control
• Called on every node selection and modification
• Use for context-sensitive controls

Example

public isVisible(node: ImmutableHtmlNode): boolean {
    // Hide for locked elements
    if (node.hasClass('data-locked')) {
        return false;
    }

    return true;
}

---

onRender()

Hook called when the control is initially rendered.

onRender(): void

Usage Notes

• Called once after the control's template is rendered
• Use for initial setup and event listener attachment

Example

public onRender(): void {
    // Set up value change handlers
    this.api.onValueChanged('backgroundColorPicker', (newColor, oldColor) => {
        this.applyBackgroundColor(newColor);
    });
    
    //...
}

---

onDestroy()

Optional cleanup hook called when the control is being destroyed.

onDestroy(): void

Usage Notes

• Called when control is removed from the panel
• Use to clean up resources
• Prevent memory leaks by proper cleanup
• Clear any timers or intervals

Example

public onDestroy(): void {
    // Clear any timers
    if (this.updateTimer) {
        clearTimeout(this.updateTimer);
    }
}

---

getElementLockCategory()

Version Availability

This method is available starting from v3.11.0

Returns the Element Lock category governing this control.

public getElementLockCategory(): ElementLockCategory

Returns

ElementLockCategory - The Element Lock category of the control. Defaults to ElementLockCategory.CONTENT

Usage Notes

• Used by the Lock Element feature: when an element prevents content editing, the editor disables controls categorized as CONTENT and rejects their patches; when it prevents style editing, the same applies to controls categorized as STYLE
• Override and return ElementLockCategory.STYLE for controls that edit visual styling (colors, spacing, borders, etc.)
• Keep the default for controls that edit content (texts, links, images, block data)

Example

public getElementLockCategory(): ElementLockCategory {
    return ElementLockCategory.STYLE;
}