Email tutorial

This tutorial is for developers with basic knowledge of Vue.js. It will guide you through creating a basic email project using eWizard.js and CLI. You'll learn how to:

• Create email project

• Add components and blocks

• Apply styling

• Preview and test your email

For this, you need to have the eWizard CLI installed locally.

Read about breaking changes in new Sass versions.

Create email project

To create an email, run

wiz init email my-email

where:

• email refers to the email content item type
• my-email is the project name

eWizard CLI adds the email project with a scaffolding template and a directory structure. This scaffolding provides a basic pre-configured project setup, which includes:

• App.vue is the main Vue component where you'll define the structure and content of your email.

• common/ is a directory containing reusable assets and configurations:

  • components.js is where you register your email's components.
  • blocks-library/ is a directory to store and manage reusable blocks.
  • media/ is a directory for storing images, fonts, and other media files.

• build/ (created during the development build) contains the output files of your project.

Select Vuex for state management, if required, and enter description and author name. For more information, see email directory structure.

Run development build

You can run a development build locally to preview your email before archiving.

To run a live development build:

1. Go to your email directory.

2. Run:

   wiz dev --live

   • This starts the local server at http://localhost:3000/, which is hot-reloaded to reflect any changes you make to your project.
     Read more about wiz dev options.

   • The build directory is created in your project.
     Read more about email directory structure.

App.vue

App.vue is the main Vue component of your email template with the following structure:

<i18n>
  // Text localization
</i18n>

<template>
  // Email markup
</template>
<script>
  // JavaScript functions
</script>
<style>
  // CSS styles
</style>

Use the <template> tag to define the structure and layout of your email using eWizard.js components.

Click to open a sample App.vue

<i18n>
{
  "eng": {
    "title": "<div style=\"line-height: 34px;text-align: left;\"><a href=\"http://viseven.com\"><span style=\"font-size: 29px; font-family: arial, sans-serif;color:#000000;\">Your email is there - fill it with content!</span></a></div>",
    "image_alt_1": "Viseven",
    "image_align_1": "center"
  }
}
</i18n>

<template>
  <div>
    <wiz-root align="center" style="background: #ffffff; width: 700px;">
      <wiz-block style="padding: 10px 10px 10px 10px;">
        <wiz-placeholder style="padding: 0;">
          <wiz-column :width="100">
            <wiz-image src="./common/media/images/logo.png" class="m-full-width" :width="100" style="width: 100px;" :alt="$t('image_alt_1')" :align="$t('image_align_1')"></wiz-image>
          </wiz-column>
        </wiz-placeholder>
      </wiz-block>
      <wiz-block style="padding: 10px 10px 10px 10px;">
        <wiz-placeholder style="padding: 0;">
          <wiz-column :width="100">
            <wiz-title class="m-center" :text="$t('title')"></wiz-title>
            <wiz-text :text="$t('text_1')"></wiz-text>
            <wiz-divider align="center" divider-color="transparent" :divider-height="0"></wiz-divider>
          </wiz-column>
        </wiz-placeholder>
      </wiz-block>
    </wiz-root>
  </div>
</template>

<script>
export default {
  name: 'wiz-app',
};
</script>

<style>
body {
  margin: 0;
  padding: 0;
  font-family: Arial, sans-serif;
  color: #333333;
}

.email-container {
  max-width: 700px;
}

.text-primary {
  color: #000000;
}

.image-center {
  display: block;
}

.content-block {
  background-color: #ffffff;
}

.cta-button {
  background-color: #0066cc;
  color: #ffffff;
}
</style>

Filling in the email with content is available in two ways:

• Adding individual components

• Adding pre-designed blocks

Table: Key distinctions between component-based and block-based email development

Key distinction	Component-based development	Block-based development
Scope of elements	Small elements like text, image, button, etc.	Larger container elements that group multiple components logically
Focus	Build finer details and specific layout elements	Build structural parts of the email layout like header, body, and footer
Control	Precise control over each component	Organized content for section management
Reusability	Each component is managed and styled individually	Modules or templates that are reusable
Effort vs. efficiency	Granular control, can require more effort to assemble complex layouts	Simplified email creation with ensured consistency
App.vue role	Serves as the main container for loading and organizing components	Serves as the main container for blocks

Component-based development

You can add individual eWizard.js components to your email layout. In this tutorial, we focus on the text and image components. eWizard.js provides a variety of components for email development.

Before adding any component, do the following:

1. Install it to your email, running

   wiz i component-name

2. Register the component in ./common/components.js.

Text

To add text to the email layout:

1. Navigate to your email's App.vue.

2. Add the wiz-text component within the <template> tag.

Click to open a sample App.vue fragment

   <!--./App.vue -->
    
    <template>
    <wiz-root align="center" style="background: #ffffff; width: 700px">
      <wiz-text :text="$t('wiz_text_1064')" id="wiz-text-4e75"></wiz-text>
    </wiz-root>
    </template>

• id refers to the unique identifier for your text component

• $t() is the translation function to bind the localized text with your text component

3. Specify the text component content within the <i18n> tag.

Click to open a sample App.vue fragment

<!--./App.vue -->

<i18n>
{
"eng": {
    "wiz_text_1064": "Clinical trials"
    }
}
</i18n  >

Read more about text component.

Image

To add image to the email layout:

1. Navigate to your email's App.vue.

2. Add the wiz-image component within the <template> tag.

Click to open a sample App.vue fragment

    <!--./App.vue -->

    <template>
    <div>
      <wiz-root align="center" style="background: #ffffff; width: 700px;">
        <wiz-image
                  id="wiz-image-b7e1"
                  :link="'https://viseven.com'"
                  :width="90"
                  :height="90"
                  alt="Image"
                  src="./common/media/images/37022210-5d7b-11ec-b91a-85800ef85ec4.png"
                ></wiz-image>
      </wiz-root>
    </div>
    </template>

• id defines the component styles display in eWizard Editor

3. Specify the alternative text for your image component within the <i18n> tag.

Click to open a sample App.vue fragment

<!--./App.vue -->

<i18n>
{
"eng": {
    "wiz-image-b7e1": "A logo"
    }
}
</i18n>

Read more about image component.

Block-based development

A block is a fundamental component in eWizard that serves as a container for other components. Blocks provide a structured way to organize content and are essential for developing different types of eWizard content items.

This approach involves the following steps:

1. Set up block library.
   Select blocks to be structural parts of your email.

2. Develop or customize the blocks.

   2.1. Initiate a block with eWizard CLI.
   While you can manually create blocks, using the eWizard CLI to create them as npm modules provides streamlined management and reusability.

   2.2. Use the wiz-placeholder component to create a structured layout.

   2.3. Add the required components to your block.

3. Add blocks to your email template and import them to the main App.vue file.

Set up block library

Follow these steps to set up a block library:

1. In the common/blocks-library directory, add a folder to store a new block within your email. Each block must have a separate folder in the common/blocks-library directory.

2. Navigate to your created folder. Run wiz init block.

3. Specify block description, name, id, and author.

As a result, the block instance is generated. It includes the index.vue file. Use it the same way as the App.vue file of your email—add individual components you need this block to include.

Prepare blocks

For each block, add the following components:

1. wiz-block

2. wiz-placeholder

3. wiz-column

Add other components as it described in the component-based development flow.

Add blocks to email

To add a block to your email:

1. List the required blocks in ./common/blocks-library/blocks.json.

2. Register the block in the blocks.json file.

3. Import the block in your App.vue file.

Click to open a sample block index.vue

//@formatter:off
<i18n>
  {
    "eng": {
      "title": "<div style='line-height: {lineHeightToken}; text-align: {textAlignToken}'><span style='color: {textColorToken}; font-size: {fontSizeToken}; font-family: {fontFamilyToken};'>{titleToken}</span></div>",
      "text": "<div style='line-height: {lineHeightToken}; text-align: {textAlignToken}'><span style='color: {textColorToken}; font-size: {fontSizeToken}; font-family: {fontFamilyToken};'>{textToken}</span></div>"
    }
  }
</i18n>
//@formatter:on

<template>
  <wiz-block
    class="block block-content01a m-full-width m-mw-auto"
    align="center"
    :style="{
      padding: $DT.blocks.BlockContent01A.firstBlockPadding || '0',
      background: $DT.blocks.BlockContent01A.firstBGColor || '#0023AE',
    }"
    :class="$DT.blocks.BlockContent01A.firstBlockClass || ['m-p-lr-0', 'm-p-b-20']"
  >
    <wiz-placeholder
      :style="{
        padding: $DT.blocks.BlockContent01A.firstPlaceholderPadding || '0',
        direction: $DT.blocks.BlockContent01A.firstPlaceholderDirection || 'rtl'
      }"
      dir="rtl"
      :class="$DT.blocks.BlockContent01A.firstPlaceholderClass || ['m-p-lr-0']"
    >
      <wiz-column
        :style="{direction: $DT.blocks.BlockContent01A.firstColumnDirection || 'ltr'}"
        dir="ltr"
        :width="49"
      ><wiz-image
        :data-element-type="$DT.blocks.BlockContent01A.firstImageDataElementType || 'Image'"
        :src="
          $DT.blocks.BlockContent01A.firstImageSrc ||
            $DT.images.placeholder342x342.src
        "
        :alt="
          $DT.blocks.BlockContent01A.firstImageAlt ||
            $DT.images.placeholder342x342.alt
        "
        :width="
          $DT.blocks.BlockContent01A.firstImageWidth ||
            $DT.images.placeholder342x342.width
        "
        :class="
          $DT.blocks.BlockContent01A.firstImageClass ||
            $DT.images.placeholder342x342.class + [' m-image-full-width']
        "
        :align="$DT.blocks.BlockContent01A.firstImageAlign || 'right'"
        :style="{
          padding: $DT.blocks.BlockContent01A.firstImagePadding || '0',
        }"
      ></wiz-image></wiz-column>
      <wiz-column
        :style="{direction: $DT.blocks.BlockContent01A.secondColumnDirection || 'ltr'}"
        dir="ltr"
        :width="51"
      >
        <wiz-placeholder
          :style="{
            padding:
              $DT.blocks.BlockContent01A.secondPlaceholderPadding ||
              '0 15px 0 40px',
          }"
          :class="$DT.blocks.BlockContent01A.secondPlaceholderClass || ['m-p-lr-20']"
        >
          <wiz-column>
            <wiz-title
              :data-element-type="$DT.blocks.BlockContent01A.firstTitleDataElementType || 'Headline'"
              :text="
                $t('title', {
                  titleToken:
                    $DT.blocks.BlockContent01A.firstTitleToken ||
                    $DT.texts.title1,
                  lineHeightToken:
                    $DT.blocks.BlockContent01A.firstTitleLineHeight || '38px',
                  textAlignToken:
                    $DT.blocks.BlockContent01A.firstTitleAlign || 'left',
                  textColorToken:
                    $DT.blocks.BlockContent01A.firstTitleColor || '#FCFDFF',
                  fontSizeToken:
                    $DT.blocks.BlockContent01A.firstTitleFontSize || '28px',
                  fontFamilyToken:
                    $DT.blocks.BlockContent01A.firstTitleFontFamily ||
                    $theme.firstFontFamily,
                })
              "
              :style="{
                padding:
                  $DT.blocks.BlockContent01A.firstTitlePadding || '50px 7px 22px 0',
              }"
              :class="$DT.blocks.BlockContent01A.firstTitleClass || ['m-p-t-20 m-p-b-10 m-p-lr-0']"
            ></wiz-title>
            <wiz-text
              :data-element-type="$DT.blocks.BlockContent01A.firstTextDataElementType || 'Copy'"
              :text="
                $t('text', {
                  textToken:
                    $DT.blocks.BlockContent01A.firstTextToken ||
                    $DT.texts.body1,
                  lineHeightToken:
                    $DT.blocks.BlockContent01A.firstTextLineHeight || '24px',
                  textAlignToken:
                    $DT.blocks.BlockContent01A.firstTextAlign || 'left',
                  textColorToken:
                    $DT.blocks.BlockContent01A.firstTextColor || '#FCFDFF',
                  fontSizeToken:
                    $DT.blocks.BlockContent01A.firstTextFontSize || '16px',
                  fontFamilyToken:
                    $DT.blocks.BlockContent01A.firstTextFontFamily ||
                    $theme.firstFontFamily,
                })
              "
              :style="{
                padding: $DT.blocks.BlockContent01A.firstTextPadding || '0 0 50px 0',
              }"
            ></wiz-text>
          </wiz-column>
        </wiz-placeholder>
      </wiz-column>
    </wiz-placeholder>
  </wiz-block>
</template>

<script>
export default { name: 'block-content01a' };
</script>

4. After all required blocks are in place, archive your email template and upload it to the eWizard platform.

Customize blocks

You can make initial content and styling adjustments to the block directly within the eWizard Editor. As you edit, eWizard synchronizes these changes and copies the updated markup to email's App.vue file. For further, more complex edits, modify the block directly within the App.vue file, instead of the original block files.

You can also style your block, as well as add and style components within it, using its index.vue file. For this:

1. Open the ./blocks-library/my-block/index.vue file.

2. Set the required CSS styles using the inline style attribute within the <wiz-block> tag.

3. Add any required components the same way as described in the Component-based development section, placing them to the index.vue files of your required blocks and wrapping them into the <wiz-placeholder> and wiz-column components.

Click to open a sample block index.vue

<!-- ./blocks-library/my-block/index.vue -->

<template>
  <wiz-block
    class="block bg-ae-block-c2 m-full-width m-mw-auto m-p-tb-16 m-p-lr-0"
    align="center"
    style="min-width: 640px; width: 640px;padding: 24px 0;"
  >
    <wiz-placeholder
      :break-columns="false"
    >
      <wiz-column
        :width="100"
      >
        <wiz-text
          class="m-p-b-12"
          :text="$t('text1')"
          style="padding: 0 0 16px;"
        >
        </wiz-text>
        <wiz-text
          :text="$t('text2')"
          style="padding: 0;"
          class="m-p-b-0"
        >
        </wiz-text>
      </wiz-column>
    </wiz-placeholder>

  </wiz-block>
</template>

Export email as image

You can convert your email blocks and components into images when exporting the email to HTML.

The as-image attribute forces blocks and components to be rendered as a single, unified image in the exported HTML email. This decreases the lines of code in the email markup, reducing email's size and simplifying the overall email's markup in the resulting HTML.

Use the as-image attribute when:

• You need to optimize the size of your exported HTML email

• You need to avoid known display issues in target email clients

To use the as-image attribute, do the following:

1. Open App.vue of your email or index.vue of your required block or component instance.

2. Add as-image with the target image properties to the block or component template markup.

Table: as-image attribute properties

Property	Description
alt	Alternative text to be displayed if an image fails to upload
src	Path to the image
style	Inline styles for the image

An example of the as-image attribute:

<template>
  <wiz-placeholder class="m-full-width" align="center" style="padding: 0;" as-image="{'alt': 'wiz-BlockB8', 'style': 'vertical-align:bottom;'}">
</template>

Click to open the App.vue fragment

<!-- ./App.vue -->

<template>
    <wiz-wrapper style="width: 100%;" class="editable-block">
        <wiz-root class="m-full-width editable-block main" align="center" style="background: rgb(255, 255, 255);width: 100%;">
            <wizHeader1d></wizHeader1d>
            <wizContent2b></wizContent2b>
            <wizContent2a></wizContent2a>
            <wizBlockMyBlock as-image="{'alt': 'My image'}"></wizBlockMyBlock>
            <wizFooter3a></wizFooter3a>
        </wiz-root>
    </wiz-wrapper>
</template>

Click to open the index.vue fragment

<!-- ./common/blocks/my-block/index.vue -->

<template>
  <wiz-block class="block wiz-block-b8 m-full-width m-mw-auto" align="center" style="width: 600px;min-width: 600px; padding: 20px 0;" as-image="{'alt': 'My image'}">
  </wiz-block>
</template>

It's recommended to add as-image to the blocks and components in the ./common/blocks or ./common/components directories. If you add as-image to the blocks in the ./node_modules/@blocks directory, you can lose changes when updating the modules.

As a result, after exporting your email for one of the target systems in the eWizard platform, your HTML email displays the images for the blocks and components where you added as-image.

If a block or component includes a hyperlink, eWizard.js appends this link to the block or component image in the resulting HTML email.

Adjust generated image properties

When using the as-image attribute, you can configure settings of the resulting image with additional attribute, as-image-options.

For this, define this attribute within the required block or component tag:

<wiz-button as-image="" as-image-options="{'type': 'png', 'omitBackground': true}"></wiz-button>

The properties of as-image-options are as follows:

Property	Type	Default	Description
type	String	png	Specifies the image file format. Supported formats: png | jpeg | webp
omitBackground	Boolean	false	When set to true, this option removes the background from the block or component. Only applicable when type: png
asImageInPdf	Boolean	false	When set to true, this option ensures that the block or component is exported as an image during email PDF export

Next steps

Once your email is ready to go, archive it and upload to the eWizard platform.

To create an archive with a specific name, run:

wiz archive --name [ARCHIVE_NAME]