New HTML blocks

📘

This is a new version of HTML blocks, we have developed a more suitable and scalable solution. It is now possible to use a visual parameter editor or Jinja variables as parameters of the HTML block.

The existing HTML blocks will be automatically migrated in several phases during the following weeks, as described in the Migration plan.

When creating email templates, you usually need to reuse some parts of the HTML, for example headers and footers. Therefore, Bloomreach Engagement allows you to create custom HTML blocks (also called dynamic blocks, or dynamic content) that you can create once and then easily reuse across your email campaigns.

HTML blocks are custom snippets of HTML code that are, once created, stored as templates within the Asset Manager and can be inserted into email templates.

The content of the block (i.e. the HTML code) can be then written using the classic code editor and parameters visual editor. These allow you to insert a parameter value into the block that can be specified with each usage of the block in an email template.

How to create a HTML block

All cases will open up a separate HTML builder window, where you can create, preview and test the block.

It is possible to create constant or non-constant parameters of various types to be used within the blocks, and to define the parameter values upon using the block in an email template. This is covered in more detail in the Using Parameters section.

Upon saving, all HTML blocks are stored within the project templates, and can be accessed from the Asset Manager, section Blocks.

Blocks can be created in 3 ways:

  1. Go to Data and Assets > Asset manager > Blocks -> New block
13381338
  1. You can also create a new block directly within the email editors, whether you are building the email in the "Asset manager", "Email campaigns" or through an email node in a scenario. Use the (+) button at the bottom of the editor or node modal to open the Asset picker, select Blocks in the asset selector and choose the “New block” option.
13721372 13761376
  1. You can also use one of the templates from the campaign asset picker.

There are two types of Blocks templates:

  • Predefined templates are created by Bloomreach and cover many different use cases. These are not stored in the client’s project but loaded in real time from a central repository. This means they cannot be edited directly but can be saved as copy into the project templates and then further edited using the “Save as copy” option.
  • Project templates are any custom blocks created by the client or by copying and changing the predefined templates.

Predefined templates

Users can also use a predefined template directly from the campaign asset picker.

13561356

In case the template contains parameters, the user must first save the block into the project templates via “Save as copy” and then select the project copy for use in the campaign (In order to reference a block in a campaign it must have a project copy).

In case the template does not contain parameters, the user will have two options: “Save as copy” and then use the project template copy or “Copy as code” which will copy the code of the predefined template into the clipboard.

13541354

HTML Editor

When creating a new block, simply write the HTML code which you will want to reuse later.

The content of the block (i.e. the HTML code) can be then written using the classic code editor and parameters visual editor. These allow the client to insert a parameter value into the block that can be specified with each usage of the block in an email template.

The functions available are similar to the normal email HTML builder, including multilingual support.

Using parameters

It is possible to create parameters to be used in the block. Parameters are like variable values that make it possible to insert a custom value within, e.g. each email separately. This will prompt the option to choose the value of the parameter when the block is selected within a campaign.

Parameters can be created using the parameters editor by clicking on the + Add parameter button, or can be defined directly in the code and created using the button “Load parameters from the code editor”

Each parameter can be also assigned to a category. Categories should help to better organize the parameters within the block. Categories can be created using the parameters editor by clicking on the + Add category button. Both parameters and categories also support the drag & drop functionality.

13521352

You can define following attributes of a parameter:

1. Parameter reference-> name of the reference of the parameter to be used in the code, The parameters display name is derived from it (similar to template parameters)

  • The derived parameter name will automatically split words if camel-back notation is used or word connected with underscore _
    • reference paramName -> Param Name
    • reference param_name -> Param Name

2. Parameter type -> data type of the parameter

  • Available data types:
    • string (default) – a simple one-line text, type returned is string
    • text – multi-line text, type returned is string
    • number - type returned is integer or float
    • boolean - type returned is True/False
    • list - type accepted/returned is jinja list type e.g [1,2,3]
    • object - type accepted/returned is jinja dict type e.g {"key": value}
    • datetime – datetime picker, value returned is timestamp as number
    • date – date picker, value returned is timestamp as number with default hours set to 23:59:59 currently FE seems to create timestamp at 23:59:59 (CET)
    • time – time picker, value returned is string with the time “12:00”
    • color – color picker, accepts color values in HEX, rgb or rgba format, type returned is string
    • enum - selector for defined string values
    • image - image picker from the Bloomreach file management, value returned is a string that represents the URL of the image
    • recommendation - recommendation picker, value returned is an ID of the selected recommendation model
    • metric - metric picker, value returned is an ID of the selected metric
  • For most of the data types except (datetime, date, time and boolean) it is possible to use either constant values or jinja variables such as {{ customer.first_name }}.
  • Parameters types are validated for constant values, in case a jinja variable is used as parameter, the type of the parameter is not validated.

3. Default value -> default parameter value. Default value will be used in case no specific parameter value is provided upon block usage in campaign (calling the block) and to prepopulate the parameters input.

  • For most of the data types except (datetime, date, time and boolean) it is possible to use either constant default values or jinja variables such as {{ customer.first_name }}
  • If no default value is provided, and the parameter is not filled it the jinja undefined value will be used

4. Required field -> define whether parameter must be filled in when using the block. Parameters marked as required must be filled in unless the default value is also used.

5. Tooltip -> Tooltip will be displayed by the parameter name when inputting the parameters values in campaign

Parameters can be used within the the code as standard jinja variables, using the keyword parameters and the defined reference name e.g:

{{ params.parameterName }} or {{ params["parameter name"] }}
{% set otherVariable = params.parameterName %}
{% if param.paramName = "something" %}
…
{% endif %}

Multi words param references can only be used with the params[""] notation.

Calling blocks with parameters:

{{ block('<block id>', {'parameterName': 'value'}) }}

Using jinja variables as parameters

It is allowed to use simple jinja variables/expressions as parameters of blocks.
Parameters can’t contain complicated jinja expressions within {%... %} or strings containing jinja within {%... %} such as set, if, for loop etc.

Contextual variables, such as event, webhook, or email.view, are not available directly in the block but can be used as parameters in campaigns where those variables are available.

Notation

There are two types of notation of variables as parameters depending on their usage.

1. When using blocks as the jinja reference the variables must be used directly (without {{ }})

e.g.

{{ block('<block id>', {'purchasePrice': event.total_price }) }}

{{ block('<block id>', {'finishDate': ((time + 604800) | from_timestamp('%d-%m-%y')) }) }}

{{ block('<block id>', {'products': [1,2,3] }) }}

Strings containing jinja personalization must be created using ~, otherwise they would not be rendered.

{{ block('<block id>', {'mainText': 'Hello ' ~ customer.first_name ~ ', welcome!' }) }}

2. When filling in the parameters via the inputs in the asset picker, here you need to use the {{}} notation so we can recognize its a variable and generate the reference correctly e.g without “”

In the parameters inputs, it is also possible to input a string containing jinja and it will be automatically translated into the ~ notation.

E.g

The following parameters inputs:

13721372

translate into this reference:

{{ block('606321bfe04f9d2be61e0812', {'purchasePrice': event.total_price, 'mainText': 'Hello '~ (customer.first_name) ~', welcome!', 'fallbackValue': customer.last_name}) }}

Using blocks in campaigns

Upon usage in a campaign, blocks can be copied as reference with the visual editor for the parameters values and preview, or if it does not contain any parameters, they can also be copy pasted. If the reference is used, any time the block is updated, the change is immediately reflected in the email that uses it.

A finished HTML block can be inserted into an email campaign in 2 ways:

1. Via the asset picker by clicking a (+) button on the right bottom of HTML or visual editor by choosing the desired block.

  • Blocks can be copied as either direct code (in this case HTML) or as a reference
11821182 12041204

Choosing a block will open the block preview with customer selector, block description and the parameter inputs. When entering the parameters, the preview will be regenerated once you lose focus from the input (click outside).

15021502

2. Via the Visual editor by simply dragging the “Dynamic content” node from the Contents tab into the
canvas and then choosing the desired HTML block.

13541354

Language variants behavior

The language variant of the block will be selected based on the selected main campaign template language version. To illustrate, here is how the following situations would be solved:

Case 1:

We have 2 assets: campaign template with sk variant, block with no language variant and a customer with sk language:

  • template (sk) -> using block (default)

Case 2:
We have 2 assets: campaign template with no language variant, block with no language variant and a customer with sk language:

  • template (default) -> block (default)

Insert options

1. Copy as reference
This will copy the reference to the block in jinja tags, that can be pasted into code. This will not allow changes to the block directly in the campaign and WILL be updated when the block is changed.

Referencing a block using jinja:

  • Without parameters:
{{ block('<block id>') }}
  • With parameters:
{{ block('<block id>', {'<param name>': <param value>, '<param name>': <param value> }) }}

2. Copy as code
This will take the full block content from the default language template and copy it to clipboard. The client can simply paste the code into the desired campaign part. This code can be changed as desired, and will NOT be updated when the block is changed, neither will it consider language variants.

🚧

This option is only available for blocks without parameters.

Limitations

  • Hard Limits:
    • Max size 600 kB of the template of a block per translation
    • Max 50 distinct translations per block
    • Max 50 distinct parameters can be created per block
    • Max 20 distinct snippets can be used in a single campaign template/block
    • Max length of 100 characters of a parameter name or category
    • Max length of 1000 characters for parameter tool-tip
    • Parameters can’t contain complicated jinja expressions within {%... %} or strings containing jinja within {%... %} such as set, if, for loop etc.
  • It is not possible to use block inside a block.

Migration plan

Release 1.210

  • HTML blocks created after this release will be already stored as New HTML blocks
  • All already existing HTML blocks without parameters will be automatically migrated to the New HTML blocks implementation

Release 1.220

  • Most of the existing HTML blocks with parameters will automatically be migrated to the New HTML blocks implementation.
  • For blocks, that due to their complexity, cannot be automatically migrated:
    • User interface of old HTML blocks will show a warning about future deprecation.
    • User interface of old HTML blocks will provide a possibility to manually migrate blocks to the new HTML blocks implementation.

Soon

  • Start depreciation process for old blocks with communication to clients still using old HTML blocks
  • Deprecation of old HTML blocks

Did this page help you?