HomeEngagementContentDiscoveryOther resources
Guides

HTML Blocks

Suggest Edits

📘

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 previous version was deprecated with the release of 1.210.

When creating email templates or weblayers, 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 and weblayers.

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 and weblayers.

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 or a weblayer.

How to create an 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 or a weblayer. 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.

Previously configured blocks can be edited without having to start from scratch. Each time a change is applied, the editor will add the new version to a list of block versions. Only a selected version of the block will be kept upon going to the Test tab.

Blocks can be created in 3 ways:

  1. Go to Data and Assets > Asset manager > Blocks > New block.

  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. These blocks can also be created directly within the weblayer editors, whether you are building the weblayer in the "Asset manager", "Weblayers", or through a 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.

  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 are loaded in real-time from a central repository. This means they cannot be edited directly but can be saved as copies 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.

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 (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.

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 or a weblayer.

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.

You can define the 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 the camel-back notation is used or the word is connected with an 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, the type returned is a string
    • text – multi-line text, the type returned is a 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, the value returned is timestamp as number
    • date – date picker, the value returned is timestamp as a number with default hours set to 23:59:59 currently FE seems to create a timestamp at 23:59:59 (CET)
    • time – time picker, the value returned is a string with the time “12:00”
    • color – color picker, accepts color values in HEX, RGB, or rgba format, the type returned is a string
    • enum - selector for defined string values
    • image - image picker from the Bloomreach file management, the value returned is a string that represents the URL of the image
    • recommendation - recommendation picker, the value returned is an ID of the selected recommendation model
    • metric - metric picker, the 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 }}.
  • Parameter types are validated for constant values, in case a jinja variable is used as a parameter, the type of the parameter is not validated.

3. Default value -> default parameter value. The default value will be used in case no specific parameter value is provided upon block usage in a 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, the jinja undefined value will be used

4. Required field -> define whether the 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 values of the parameters in a campaign

Parameters can be used within 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.

Since params are of type dictionary, be aware that parameter names are, essentially, keys to lookup in a dictionary. Parameter names might conflict with Python built-in dictionary methods and in that case, the params[""] notation should be used. For example, a parameter with the name "items" should be accessed using the notation params["items"].

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, you need to use the {{}} notation, so we can recognize it's 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:

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 a 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 the 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

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

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.

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: a campaign template with Slovak (sk) variant, a block with no language variant, and a customer with Slovak (sk) language:

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

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

  • template (default) -> block (default)

Insert options

1. Copy as reference
This will copy the reference to the block in jinja tags, which 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 the 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, nor will it consider language variants.

🚧

This option is only available for blocks without parameters.

Limitations

  • HTML Blocks currently cannot be used within Webhooks. Referencing a block via its ID within Webhook results in a 'block function not defined' error. Instead, use snippets in webhooks for your objetives.

Updated 12 months ago