Template Aliases Usage Guide

What is a Template Alias?

Template aliases are special markup shortcuts designed to simplify extension development by eliminating the need to learn complex standard block markup. When a block is created, these aliases are automatically converted into the appropriate HTML markup.

We strongly recommend using template aliases for the following reasons:

• Cross-client compatibility: Aliases ensure consistent appearance across different email clients
• Built-in functionality: Leverage pre-configured standard controls that work seamlessly with the generated markup
• Reduced complexity: Eliminate the need to manually implement layout logic, such as padding adjustments
• Maintenance efficiency: Simplify code maintenance and reduce potential markup errors

Examples

Creating a Simple Block

Template aliases can be used within simple blocks to create structured content elements. When using aliases in this context, wrap them in a <table> tag, as each alias generates a <tr> root element.

import {Block, BlockAttr, BlockCompositionType, BlockType} from '@stripoinc/ui-editor-extensions';

export class SimpleBlock extends Block {
    getBlockCompositionType() {
        return BlockCompositionType.BLOCK;
    }
    
    getTemplate() {
        const {BLOCK_IMAGE, BLOCK_TEXT, BLOCK_BUTTON} = BlockType;

        return `
            <td>
                <table width="100%" cellspacing="0" cellpadding="0">
                    <${BLOCK_IMAGE}
                        ${BlockAttr.BLOCK_IMAGE.src}="https://hpy.stripocdn.email/content/guids/CABINET_e5244175dd1729a1d6ee1f8bd0d5490f/images/50421523966142571.jpg"
                        ${BlockAttr.BLOCK_IMAGE.alt}="Lorem ipsum">
                    </${BLOCK_IMAGE}>
                    
                    <${BLOCK_TEXT}>
                        <p>Lorem ipsum dolor sit amet</p>
                    </${BLOCK_TEXT}>
                    
                    <${BLOCK_BUTTON} ${BlockAttr.BLOCK_BUTTON.href}="https://stripo.email">
                        Click me
                    </${BLOCK_BUTTON}>
               </table> 
            </td>
        `
    }

    // Additional block configuration methods...
}

Creating a Container

You can create container markup using template aliases to group related content elements. The allowInnerBlocksSelection() and allowInnerBlocksDND() methods provide fine-grained control over user interactions within the container:

• allowInnerBlocksSelection(): Controls whether users can select individual blocks within the container
• allowInnerBlocksDND(): Controls whether users can drag and drop blocks within the container

import {Block, BlockAttr, BlockCompositionType, BlockType} from '@stripoinc/ui-editor-extensions';

export class SimpleBlock extends Block {
    getBlockCompositionType() {
        return BlockCompositionType.CONTAINER;
    }

    getTemplate() {
        const {CONTAINER, BLOCK_TEXT, BLOCK_BUTTON} = BlockType;

        return `
            <${CONTAINER}>
                <${BLOCK_TEXT}>
                    <p>Lorem ipsum dolor sit amet</p>
                </${BLOCK_TEXT}>
                <${BLOCK_BUTTON} ${BlockAttr.BLOCK_BUTTON.href}="https://stripo.email">
                    Click me
                </${BLOCK_BUTTON}>
            </${CONTAINER}>
        `
    }

    allowInnerBlocksSelection() {
        return false; // Disable selection of blocks inside the container
    }

    allowInnerBlocksDND() {
        return false; // Disable drag and drop of blocks inside the container
    }

    // Additional block configuration methods...
}

Creating a Structure

Structures allow you to create multi-column layouts using template aliases. When creating structures, ensure that the combined width of all containers within the structure totals 100% for proper layout rendering.

The allowInnerBlocksSelection() and allowInnerBlocksDND() methods provide the same interaction controls as containers, allowing you to manage user behavior within the structure's containers.

import {Block, BlockAttr, BlockCompositionType, BlockType} from '@stripoinc/ui-editor-extensions';

export class SimpleBlock extends Block {
    getBlockCompositionType() {
        return BlockCompositionType.STRUCTURE;
    }

    getTemplate() {
        const {STRUCTURE, CONTAINER, BLOCK_TEXT, BLOCK_BUTTON} = BlockType;

        // Create a two-column structure:
        // - First column: 50% width containing a Text Block
        // - Second column: 50% width containing a Button Block
        return `
            <${STRUCTURE}>
                <${CONTAINER} ${BlockAttr.CONTAINER.widthPercent}="50">
                    <${BLOCK_TEXT}>
                        <p>Lorem ipsum dolor sit amet</p>
                    </${BLOCK_TEXT}>
                </${CONTAINER}>
                
                <${CONTAINER} ${BlockAttr.CONTAINER.widthPercent}="50">
                    <${BLOCK_BUTTON} ${BlockAttr.BLOCK_BUTTON.href}="https://stripo.email">
                        Click me
                    </${BLOCK_BUTTON}>
                </${CONTAINER}>
            </${STRUCTURE}>
        `
    }

    allowInnerBlocksSelection() {
        return true;  // Allow selection of blocks inside the structure
    }

    allowInnerBlocksDND() {
        return false;  // Disable drag and drop of blocks inside the structure
    }

    // Additional block configuration methods...
}

Adding an Empty Container

Empty containers serve as placeholders that users can populate with content. You can define empty containers using template aliases to create flexible layout structures.

import {Block, BlockAttr, BlockCompositionType, BlockType} from '@stripoinc/ui-editor-extensions';

export class SimpleBlock extends Block {
    getBlockCompositionType() {
        return BlockCompositionType.STRUCTURE;
    }

    // Create a two-column structure:
    // - First column: 50% width containing an Empty Container
    // - Second column: 50% width containing a Button Block
    getTemplate() {
        const {STRUCTURE, CONTAINER, EMPTY_CONTAINER, BLOCK_BUTTON} = BlockType;

        return `
            <${STRUCTURE}>
                <${EMPTY_CONTAINER} ${BlockAttr.EMPTY_CONTAINER.widthPercent}="50">
                </${EMPTY_CONTAINER}>
                
                <${CONTAINER} ${BlockAttr.CONTAINER.widthPercent}="50">
                    <${BLOCK_BUTTON} ${BlockAttr.BLOCK_BUTTON.href}="https://stripo.email">
                        Click me
                    </${BLOCK_BUTTON}>
                </${CONTAINER}>
            </${STRUCTURE}>
        `
    }

    allowInnerBlocksSelection() {
        return true;  // Allow selection of blocks inside the structure
    }

    allowInnerBlocksDND() {
        return true;  // Allow drag and drop of blocks inside the structure
    }

    // Additional block configuration methods...
}

Customizing Quick-Add Icons

You can customize the quick-add icons that appear inside empty containers to provide users with specific block options. This is accomplished by specifying block IDs in the blocks attribute of the empty container.

import {Block, BlockAttr, BlockCompositionType, BlockType} from '@stripoinc/ui-editor-extensions';

export class SimpleBlock extends Block {
    getId() {
        return 'simple-block';
    }
    
    getBlockCompositionType() {
        return BlockCompositionType.STRUCTURE;
    }

    getTemplate() {
        const {STRUCTURE, EMPTY_CONTAINER, BLOCK_IMAGE, BLOCK_TEXT} = BlockType;

        // Specify block IDs that will appear as quick-add icons in the empty container        
        return `
            <${STRUCTURE}>
                <${EMPTY_CONTAINER} 
                    ${BlockAttr.EMPTY_CONTAINER.widthPercent}="100"
                    ${BlockAttr.EMPTY_CONTAINER.blocks}="${BLOCK_IMAGE}, ${BLOCK_TEXT}, simple-block">  
                </${EMPTY_CONTAINER}>
            </${STRUCTURE}>
        `
    }

    allowInnerBlocksSelection() {
        return true;  // Allow selection of blocks inside the structure
    }

    allowInnerBlocksDND() {
        return true;  // Allow drag and drop of blocks inside the structure
    }

    // Additional block configuration methods...
}