How can we help?

Search

Sculpt blocks

Overview

Sculpt blocks are HTML elements you can drag into Sculpt templates during message creation to build custom layouts and content. Elements within each block can be referenced with Smarty variables and customized using forms you create when building a block.

For example, the following HTML can be set up as a Sculpt block. The text "Hello World" can be referenced with a variable and then updated by using a form input during message creation.

<table>
  <tbody>
    <tr>
      <td>Hello World</td>
    </tr>
  </tbody>
</table>

Blocks must be saved as complete and valid HTML elements. We strongly recommend that all blocks start and end with a table tag and are fully self-contained.

Our example

For our example, we'll create four blocks—a banner block, CTA block, headline block, and product block—that can be dragged into the Sculpt template we created. For each block, we'll define the desired editable elements and create a form input field for each one using the Form Builder.

Block Name Editable Elements Field Type
Banner Image Path Image Selector
  Image Link Text
  Alt Text Text
CTA Headline Text Text
  Body Text Text Area
  Button Text Text
  Button Link Text
Headline Headline Text Text
Product (repeatable) Title Text
  Description Text Area
  Button Text Text
  Button Link Text
  Image Path Image Selector

The product block will be set to repeatable. This will allow your team to add additional products without the need to drag a new block into the editor.

Banner block example

Our example banner block consists of a <table> tag with a nested image.

<table width="579" border="0" align="center" cellpadding="0" cellspacing="0" class="mobile_width">
  <tbody>
    <tr>
      <td><a href="http://cordial.com"><img alt="30% Off Sunglasses" class="mobile_width" src="https://d1ok0qgebci2d3.cloudfront.net/34/579x272/banner-CTA-3.jpg" /></a></td>
    </tr>
  </tbody>
</table>

Create a new block

1. Navigate to Content > Sculpt Blocks > New to create a new block.

2. Fill out the fields for the new block:

  • Block name: The block name will be used to identify it in the block list and edit screens.
  • Block key: The block key is used to reference the block inside a Sculpt template for pre-defined layouts. For example, if you want a block to be present in a template by default, you can include it in the template HTML code using the following tag:
    <block type="block_key"></block>
  • Block description: Used to describe the block. The description will display in the block list during message creation.
  • Block tags: Tags can be used for filtering blocks during message creation.
  • Allow blocks to be used in: Used to restrict a block's availability per message type.
    • Batch messages and automation: Block will be available in both message types.
    • Batch messages only: Block will be available in batch messages only.
    • Automations only: Block will be available in automations only.
    • None: Block will not be available in any message type. This is useful when building a block and restricting usage until block development is complete.

3. Click Continue. You'll be presented with the Block Markup Editor.

4. You can paste in your block HTML here and preview it using the Preview Block Markup button.

5. Next, you'll need to set up the form to define the editable elements of the block.

Create the block form

For our banner block example, we identified three editable elements: image path, image URL, and image alt text. We'll create a form your team can use to customize those values during message creation.

1. To create the form, click the Form Builder button above your Block Markup Editor. You'll be taken to the Form Builder page.

2. Create a new section and give it a title. The section title will be used to name the section of the form containing the associated field(s).

3. Click on New Field to create a new field. Give the field label a name. The field will be used to enter the image path URL during message creation.

4. Select the Field Type. The field type will be used to determine which data type the field will collect. We'll collect an image URL for this field, so we'll choose the Image Selector field type. This will also display a button to access the image library.

5. Give the field a Default value. The field will be pre-populated with the default value during message creation. In this case, we'll have a default image path.

If no default value is given for an image selector field type, a placeholder image path will be automatically provided.

6. As you build out your form, you will see a preview in the left pane.

7. Create the remaining form fields for Image Link and Image Alt Text using the Text field types. When finished, your form should look like this:

Add variable key names to HTML

As you create your sections, fields, and default values, the variable key names and data schema will automatically generate in the background. Add the Smarty variables that reference these keys to your HTML in order for the values to populate correctly.

Access variable key names

1. To view the variable key names and schema structure, click the Data Output button. This will open an overlay window with the option to view the data schema in JSON format or each of the variable names in Smarty format. You can keep this window open when referencing the variable keys in your HTML.

2. For our Banner Block example, the following data schema was created for us based on the section name, the field names, and the default values entered:

The auto-generated data output will convert your section titles and field labels to code-friendly formats by making all characters lowercase and replacing spaces with underscores.

3. Click on the Variable names icon to access the variables you'll paste into the HTML document.

4. For our example, we'll replace the banner image URL with the following Smarty tag:

{$blockData.banner_image.image_url}

5. Replace the image link with the following Smarty tag:

{$blockData.banner_image.image_link}

6. Replace the image alt text with the following Smarty tag:

{$blockData.banner_image.image_alt_text}

7. Our banner HTML with the replaced Smarty variables now looks like this:

<table width="579" border="0" align="center" cellpadding="0" cellspacing="0" class="mobile_width">
  <tbody>
    <tr>
      <td><a href="{$blockData.banner_image.image_link}"><img alt="{$blockData.banner_image.image_alt_text}" class="mobile_width" src="{$blockData.banner_image.image_url}" /></a></td>
    </tr>
  </tbody>
</table>

Paste HTML, preview, and save

1. Once the variables are updated in the HTML, paste it into the Sculpt HTML editor.

2. You can then preview the HTML by selecting Preview in Sculpt Editor from the dropdown up top.

3. You'll see a preview of how the block will appear during message creation.

4. To save your block, switch back to the Edit Block view in the upper drop-down menu, and then click Save Block to save your work.

The use of proper HTML markup is highly recommended to avoid message rendering issues. Using HTML block elements within inline elements could cause undesirable rendering of content.

Call to Action (CTA) block

Using the same techniques as the banner, we'll create the CTA block. The editable fields for this block will be Headline Text, Body Text, Button Text, and Button Link.

Starting HTML

<table width="579" border="0" align="center" cellpadding="0" cellspacing="0" class="mobile_width">
      <tbody>
    <tr>
          <td style="font-family: arial, san-serif; text-align: center; padding: 30px; background: #fff; color: #666; line-height:22px;"><h1 style="color:#292929; font-size:30px; line-height:34px;">Huge 48 Hour Sale!</h1>
        <p>Don't miss your chance to get 30% off your favorite sunglasses.<br>
          Hurry,
sale is this weekend only!</p>
        <table align="center" border="0" cellpadding="0" cellspacing="0">
              <tbody>
            <tr>
                  <td align="center" bgcolor="#1B9BA3" class="body-text" style="border-radius: 4px;"><a class="body-text" href="#" style="font-size: 14px; font-family:Arial, sans-serif; color: #ffffff; text-decoration: none; text-decoration: none; border-radius: 4px; padding: 12px 22px; text-transform:uppercase; font-weight:bold; display: inline-block" target="_blank">Shop Now</a></td>
                </tr>
          </tbody>
            </table></td>
        </tr>
  </tbody>
  </table>

Form fields

After building out our form fields to collect the data for the editable elements, the form preview will look like this:

Data output

The variable keys names and data schema are generated automatically for us so we can populate our HTML with the proper variables. Here's the data output:

{
	"$blockData": {
		"body_cta": {
			"headline_text": "Huge 48 Hour Sale!",
			"body_text": "Don't miss your chance to get 30% off your favorite sunglasses. 
Hurry, sale is this weekend only!",
			"button_text": "Shop Now",
			"button_link": "http://cordial.com"
		}
	}
}

Smarty variables

Using the supplied variable keys, we'll add the following Smarty variables to our HTML:

{$blockData.body_cta.headline_text}
{$blockData.body_cta.body_text}
{$blockData.body_cta.button_text}
{$blockData.body_cta.button_link}

Final block HTML

After adding the Smarty variables to our HTML, here's the final code block:

<table width="579" border="0" align="center" cellpadding="0" cellspacing="0" class="mobile_width">
      <tbody>
    <tr>
          <td style="font-family: arial, san-serif; text-align: center; padding: 30px; background: #fff; color: #666;"><h1 style="color:#292929">{$blockData.body_cta.headline_text}</h1>
        <p>{$blockData.body_cta.body_text.content}</p>
        <table align="center" border="0" cellpadding="0" cellspacing="0">
              <tbody>
            <tr>
                  <td align="center" bgcolor="{$templateSettings.colors.button_color}" class="body-text" style="border-radius: 4px;"><a class="body-text" href="{$blockData.body_cta.button_link}" style="font-size: 14px; font-family:Arial, sans-serif; color: #ffffff; text-decoration: none; text-decoration: none; border-radius: 4px; padding: 12px 22px; text-transform:uppercase; font-weight:bold; display: inline-block" target="_blank">{$blockData.body_cta.button_text}</a></td>
                </tr>
          </tbody>
            </table></td>
        </tr>
  </tbody>
 </table>

Headline block

We'll create the headline block using the same approach. The editable fields for this block will be Headline Text.

Starting HTML

<table width="579" border="0" align="center" cellpadding="0" cellspacing="0" class="mobile_width">
  <tbody>
    <tr>
      <td bgcolor="#f8f8f8" style="font-family: arial, san-serif; text-align: center; padding: 10px; color: #292929; font-size: 24px">Our Best Sellers</td>
    </tr>
  </tbody>
</table>

Form fields

After building out our form fields to collect the data for the editable elements, the form preview will look like this:

Data output

The variable keys names and data schema are generated automatically for us so we can populate our HTML with the proper variables. Here's the data output:

{
	"$blockData": {
		"headline": {
			"headline_text": "Our Best Sellers"
		}
	}
}

Smarty variables

Using the supplied variable keys, we'll add the following Smarty variable to our HTML:

{$blockData.headline.headline_text}

Final block HTML

After adding the variable key to our HTML, here's the final block:

<table width="579" border="0" align="center" cellpadding="0" cellspacing="0" class="mobile_width">
  <tbody>
    <tr>
      <td bgcolor="#f8f8f8" style="font-family: arial, san-serif; text-align: center; padding: 10px; color: #292929; font-size: 24px">{$blockData.headline.headline_text}</td>
    </tr>
  </tbody>
</table>

Repeatable product block

We'll treat the product block a bit differently because it's repeatable: when creating messages, your team can add additional products by clicking a button as opposed to dragging in a new block from the library. The editable elements will be Title, Description, Button Text, Button Link, Image URL and Image Link.

Original HTML

<table dir="rtl" width="579" border="0" align="center" cellpadding="0" cellspacing="0" class="mobile_width">
  <tbody>
    <tr>
      <td dir="ltr" valign="top" bgcolor="#FFFFFF" class="block" style="padding: 10px"><table width="269" border="0" align="center" cellpadding="0" cellspacing="0">
          <tbody>
            <tr>
              <td><img src="https://cdn.shopify.com/s/files/1/1070/1848/products/3467238-p-MULTIVIEW_large.jpg" width="269"></td>
            </tr>
          </tbody>
        </table></td>
      <td dir="ltr" bgcolor="#FFFFFF" class="block" style="padding: 10px"><table width="269" border="0" align="center" cellpadding="0" cellspacing="0">
          <tbody>
            <tr>
              <td style="font-family: arial, san-serif; text-align: center; padding: 10px; color: #666; font-size: 14px; line-height: 22px;">QUAY AUSTRALIA<br>
                Retro and modern influences merge seamlessly on lightweight sunglasses featuring tortoiseshell frames and flashy mirrored lenses.</td>
            </tr>
            <tr>
              <td><table align="center" border="0" cellpadding="0" cellspacing="0">
                  <tbody>
                    <tr>
                      <td align="center" bgcolor="#1B9BA3" class="body-text" style="border-radius: 4px;"><a class="body-text" href="#" style="font-size: 14px; font-family:Arial, sans-serif; color: #ffffff; text-decoration: none; text-decoration: none; border-radius: 4px; padding: 12px 22px; text-transform:uppercase; font-weight:bold; display: inline-block" target="_blank">BUY Now</a></td>
                    </tr>
                  </tbody>
                </table></td>
            </tr>
          </tbody>
        </table></td>
    </tr>
  </tbody>
</table>

Form fields

1. We want this block to be repeatable, so we'll select the Yes, make this repeatable checkbox when creating the section.

2. After building our form fields to collect the data for the editable elements, the form preview will look like this:

3. The Add Another Featured Product option will display because we chose to make this section repeatable. Click the button to add another set of fields without the need to drag in a new block.

Data output

The variable keys names and data schema are generated automatically for us so we can populate our HTML with the proper variables. Here's the data output:

{
	"$blockData": {
		"featured_products": [
			{
				"title": "QUAY AUSTRALIA",
				"description": "Retro and modern influences merge seamlessly on lightweight sunglasses featuring tortoiseshell frames and flashy mirrored lenses.",
				"button_text": "Buy Now",
				"button_link": "http://www.cordial.com",
				"image_url": "https://cdn.shopify.com/s/files/1/1070/1848/products/3467238-p-MULTIVIEW_large.jpg",
				"image_link": "http://www.cordial.com"
			}
		]
	}
}

The key/value pairs within featured_products were generated as an array (as denoted by the square brackets). This is because the section was set to be repeatable.

When writing the final HTML for the block, we'll need to use the Smarty {foreach} function to loop though the data and populate the values.

Final block HTML

After adding the Smarty variables to our HTML, the final block will look like this:

{foreach $blockData.featured_products as $product}
<table dir="rtl" width="579" border="0" align="center" cellpadding="0" cellspacing="0" class="mobile_width">
  <tbody>
    <tr>
      <td dir="ltr" valign="top" bgcolor="#FFFFFF" class="block" style="padding: 10px"><table width="269" border="0" align="center" cellpadding="0" cellspacing="0">
          <tbody>
            <tr>
              <td><a href="{$product.link}"><img src="{$product.image_url}" width="269"></a></td>
            </tr>
          </tbody>
        </table></td>
      <td dir="ltr" bgcolor="#FFFFFF" class="block" style="padding: 10px"><table width="269" border="0" align="center" cellpadding="0" cellspacing="0">
          <tbody>
            <tr>
              <td style="font-family: arial, san-serif; text-align: center; padding: 10px; color: #666; font-size: 14px; line-height: 22px;">{$product.title}<br>
                {$product.description}</td>
            </tr>
            <tr>
              <td><table align="center" border="0" cellpadding="0" cellspacing="0">
                  <tbody>
                    <tr>
                      <td align="center" bgcolor="#1B9BA3" class="body-text" style="border-radius: 4px;"><a class="body-text" href="{$product.button_link}" style="font-size: 14px; font-family:Arial, sans-serif; color: #ffffff; text-decoration: none; text-decoration: none; border-radius: 4px; padding: 12px 22px; text-transform:uppercase; font-weight:bold; display: inline-block" target="_blank">{$product.button_text}</a></td>
                    </tr>
                  </tbody>
                </table></td>
            </tr>
          </tbody>
        </table></td>
    </tr>
  </tbody>
</table>
{/foreach}

Experiment block

You can add multiple experiments to a message using the Experiment block. The experiment block is a system block that's always present as the first block in the block library when you create messages.

1. To add an experiment to your message, locate the Experiment block in the Block Library, drag it into the template, configure its settings, and then drag in content blocks for each variant in the experiment.

2. Once the experiment block is added to the template, click on the block and edit the settings.

  • Experiment name: Add a name for the experiment (underscores will automatically replace spaces in the name).
  • Optimize: Choose a method for optimization.
  • Experiment strategy: Choose a strategy:
    • Batch messages: Split or Split with champion
    • Automated messages: Multi-armed bandit
  • Variants: Choose how many variants you want the experiment to contain.

3. After you've configured the experiment settings and added the desired amount of variants, you can drag blocks into each variant using the variant dropdown button.

4. You can preview experiments using the variant dropdown in the experiment block, or by using the Experiment Preview button and choosing the desired variants.

HTML content include block

The Select menu of all HTML content Sculpt block field creates a dropdown menu consisting of all content in your HTML library. The menu will list HTML content by name, and it's dynamically updated based on available items in your library. When used in Sculpt messages, blocks containing this field allow you to select specific HTML content that the block will render.

1. Create a new Sculpt block with the Select menu of all HTML content field created in your form. We're labeling our section "HTML Include" and our field "Select HTML Content."

2. Switch to the Block Markup Editor and navigate to Data Output. Copy your field variable for use in the next step. Our example field variable is {$blockData.html_include.select_html_content}.

3. Return to the Block Markup Editor. For the block to render HTML content as expected, we must write the include using one of the following methods:

  • Conditional Statement:if condition and the include Smarty function. You can reuse the fully compiled example below but replace the field variable with your own:
{if $blockData.html_include.select_html_content != ""}
{include 'content:'|cat:$blockData.html_include.select_html_content}
{/if}
    • The if condition preemptively sets the expectation of default HTML content selection being null.
    • The cat: Smarty modifier concatenates the field variable to the include function.
  • Set a Default: Alternatively, you can specify a default value with the following Smarty modifier: 
{include "content:{$blockData.include_key.htmlinclude|default:'html_default'}"}

4. Preview the block and test the HTML content select menu. (We saved the raw HTML of our banner block as HTML content for use in this example.)

Update existing blocks

When an existing Sculpt block is updated, any newly created Sculpt messages will use the updated block. Any existing messages will retain the version of the block you used when creating the message. This prevents existing Sculpt messages from malfunctioning if a Sculpt block is updated with changed code.

When editing a message using a past version of a block, you can click the yellow exclamation point next to the block in your library, and then choose to either Update or Keep Existing. This makes it possible to lock down a block within a Sculpt message (Keep Existing) or roll forward to the updated block (Update).

Export and import blocks

You can export and import blocks by navigating to Content > Sculpt Blocks. The exported/imported files contain all block data, including the HTML and the form builder, making it easy to share blocks across different accounts.

Export blocks

1. To export a block, hover over the arrow next to the desired block and choose Export.

2. To export multiple blocks, select the desired blocks, then click the Export Sculpt Blocks button in the menu.

3. Once an export has been initiated, you can download the file on the Jobs page. The file can then be imported into another account.

Import blocks

1. To import a block, navigate to Content > Sculpt Blocks  and click the Import Blocks button.

2. Choose one or more Sculpt files (in either .ZIP or .JSON format) and click the Add Files button. You'll be taken to the Jobs page to see the status of the import. Once the import is complete, the imported block will be available in the Block Library.

When importing blocks with the same key as an existing block, the key and name of the imported block will be appended with "_copy". Existing blocks cannot be overwritten during import.

Download our example template and blocks

We made it easy to use our example template and blocks in your account.

Download and import the example template

1. Download the example template ZIP file.

2. Import the ZIP file using the Import Template feature.

Download and import the example blocks

1. Download the example block ZIP file.

2. Import the ZIP file using the Import Blocks feature.

In the next article, you can learn how to create message content using the Sculpt editor.

Comments

0 comments

Please sign in to leave a comment.