ControlApi

API interface for control implementations in the Stripo Email Editor Extensions SDK.

interface ControlApi extends BaseApi, BaseModifierApi

Description

The ControlApi interface provides comprehensive API functionality for custom controls in the settings panel. It extends both BaseApi and BaseModifierApi, offering methods to manage UI elements, access document nodes, handle value changes, and modify the email template. Controls use this API to create rich, interactive settings interfaces for email elements.

Import

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

Inheritance

• Extends: BaseApi, BaseModifierApi

Properties

None (all functionality provided through methods)

Methods

setVisibility()

Sets the visibility of a specific UI element within the control's scope.

setVisibility(uiElementName: string, isVisible: boolean): void

Parameters

Parameter	Type	Description
uiElementName	string	The ID of the UI element to show/hide
isVisible	boolean	True to show the element, false to hide it

Usage Notes

• Controls dynamic UI element visibility
• Useful for conditional settings
• Affects only elements within this control
• Changes are immediate

Example

// Show/hide advanced options based on toggle
public onValueChanged(elementName: string, value: any): void {
    if (elementName === 'showAdvanced') {
        this.api.setVisibility('advancedSettingsSelectPicker', value);
    }
}

---

setUIEAttribute()

Sets a specific attribute on a target UI element within the control's scope.

setUIEAttribute(uiElementName: string, attribute: string, value: unknown): void

Parameters

Parameter	Type	Description
uiElementName	string	The ID of the target UI element
attribute	string	The name of the attribute to set (use UEAttr constants)
value	unknown	The value to set for the attribute

Usage Notes

• Use with UEAttr constants for attribute names
• Dynamically modify UI element properties
• Common attributes: disabled, placeholder, min, max
• Changes apply immediately to the UI

Example

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

// Disable input based on condition
this.api.setUIEAttribute('fontSize', UEAttr.TEXT.disabled, isLocked);

// Update placeholder text
this.api.setUIEAttribute('customText', UEAttr.TEXT.placeholder,
    this.api.translate('placeholders.enterText'));

// Set min/max values
this.api.setUIEAttribute('width', UEAttr.COUNTER.minValue, 100);
this.api.setUIEAttribute('width', UEAttr.COUNTER.maxValue, 600);

---

updateValues()

Updates the values of multiple UI elements within the control's scope at once.

updateValues(valuesMap: Record<string, any>): void

Parameters

Parameter	Type	Description
valuesMap	Record<string, any>	Object where keys are UI element IDs and values are their new values

Usage Notes

• Efficient bulk updates
• Use for setting initial values

Example

// Set multiple values at once
this.api.updateValues({
    'enableFeatureSwitcher': true,
    'itemCountCounter': 5,
    'styleSelect': 'modern'
});

---

getValues()

Returns the current values of all UI elements managed by this control.

getValues(): Record<string, unknown>

Returns

Record<string, unknown> - Object with UI element IDs as keys and their current values

Usage Notes

• Get all values for saving/validation
• Useful for creating presets
• Includes only elements within this control
• Values reflect current UI state

Example

// Save current settings as preset
public saveAsPreset(name: string): void {
    const currentValues = this.api.getValues();
    const preset = {
        name: name,
        values: currentValues,
        timestamp: Date.now()
    };
    this.savePreset(preset);
}

// Validate all values
public validateSettings(): boolean {
    const values = this.api.getValues();
    return values.itemCountCounter >= 1 &&
           values.itemCountCounter <= 10;
}

---

onValueChanged()

Registers a callback function to be invoked when the value of a specific UI element changes.

onValueChanged(
    uiElementName: string,
    callback: (newValue: any, oldValue: any) => void
): void

Parameters

Parameter	Type	Description
uiElementName	string	The ID of the UI element to listen to
callback	Function	Function called when value changes, receiving new and old values

Example

public onRender(): void {
    this.api.onValueChanged('contentText', (newValue, oldValue) => {
        this.api.getDocumentModifier()
            .modifyHtml(this.currentNode.querySelector('p'))
                .setInnerHtml(newValue)
            .apply(new ModificationDescription(`Updated text to ${newValue}`));
    });
}

---

Inherited Methods from BaseApi

BaseApi - Base API interface

Inherited Methods from BaseModifierApi

BaseModifierApi - Document modification API