Skip to main content

Blocks and editable regions

Louise MacBean
  • Updated

This guide is for users who create their own HTML templates to use in Ometria and is written for email developers with knowledge of HTML.

You can use special attributes in email templates which mark certain elements as editable, i.e. they can be configured in the visual editor, or as blocks, which can be replicated and moved about in the template.

Blocks can contain editable regions.

Editable regions

To make an HTML element editable, you need to add the following attributes to it:

  • om:editable 
  • om:id - this must be unique per template, and can be any value, e.g. om:id=“qwerty”.

You can also add a display label by using om:label=“display name”.

Be aware that Ometria only supports the following names for om:editable:

  • image
  • text
  • html
  • rich-text
  • link

Using anything else will cause an error.

Note: Editable regions can’t be nested (i.e. one element inside another) as this may lead to unexpected behaviour and blocks rendering images in unintended ways.

The following tag types can be made editable:

Image tags

Example: 

<img om:editable"image" om:id="1" src="" />

will make the image editable (changing size/source/alt) in the UI.

You can also add a hyperlink to the element, which wraps it in an <a> tag.

If you want to link your image tag, you can wrap it in an <a> tag with the om:editable="image"

Note: If the image is linked (i.e. wrapped in an anchor tag <a>), the om:editable="image" should be added to the <a> tag and not to the <img> tag, as in the example below.

Example:

<a href="" om:editable="image" om:id="3"><img src=""></a>

Text content

You can apply copy to any of your elements using text content (div, span, a etc.).

E.g. 

<div om:editable"text" om:id="4" >Content goes here</div>

HTML content

You can apply HTML content to any element (div, span, a, etc.).

E.g. 

<div om:editable="html" om:id="5" >Content goes here</div>

Product selector

Allow products to be injected into the data and rendered as a loop with Jinja, click here for more details.

Rich text

Rich text areas provide an interface for a small subset of HTML and CSS.

Rich text can be applied to any block element (div).

Currently supported features are:

  • headings (h1-h6)
  • font colour (color)
  • bold (strong)
  • italic (em)
  • underline (u)
  • text alignment (text-align)
  • links (a)
  • clear formatting.

Rich text editable regions require support from the template author to work as expected.

The purpose of this element is to provide styling for the rich text area. When it creates new elements, it will use these styles for them. The styles are automatically inlined.

Each rich text editable block should contain a comment tag, immediately followed by a div tag, immediately followed by a comment tag (see below).

There should be no text nodes between the opening editable tag and the comment.

The style div may contain spaces.

It is probably best practice to add style="display: none" to the style div. If this is not correct, an error message displays when the user clicks to edit the block, e.g. "No rich text style element found."

This style element should contain an example of each of the following tags:

  • h1
  • h2
  • h3
  • h4
  • h5
  • h6
  • a
  • strong
  • em
  • u
  • p
  • s
  • span
  • ul
  • ol 
<div om:editable="rich-text" om:id="1"><!-- ometria_remove_begin --><div style="display: none">
        <h1></h1>
        <h2></h2>
        <h3></h3>
        <h4></h4>
        <h5></h5>
        <h6></h6>
        <a></a>
        <strong></strong>
        <em></em>
        <u></u>
        <p></p>
        <s></s>
        <span></span>
        <ul><li></li></ul>
        <ol><li></li></ol>
    </div><!-- ometria_remove_end -->
</div>
<div om:editable="rich-text" om:id="1"><!-- ometria_remove_begin --><div style="display: none">
        <strong style="color: darkgreen;"></strong>
        <h1 style="font-family: Helvetica, Arial, sans-serif; font-size: 18px; font-weight: normal; line-height: 1.3; margin: 0 0 10px; padding: 0; text-align: center"></h1><span class="fr-marker" data-id="0" data-type="false" style="display: none; line-height: 0;"></span><span class="fr-marker" data-id="0" data-type="true" style="display: none; line-height: 0;"></span>
        <p style="color: #000000; font-family: Helvetica, Arial, sans-serif; font-size: 14px; font-weight: normal; line-height: 1.3; margin: 0 0 10px; padding: 0; text-align: center; width: 100%"></p>
        <a style="color: #2199e8; font-family: Helvetica, Arial, sans-serif; font-weight: normal; line-height: 1.3; margin: 0; padding: 0; text-align: left; text-decoration: none"></a>
    </div><!-- ometria_remove_end -->
</div>

Limitations of rich text

The CSS inlined in these elements will be parsed by the user's browser. Hacks like Margin: 0 will be removed.

If the editable region does not have (either directly or via inheritance) CSS like text-align: left then there will be a "jump" in text when the user attempts to edit.

text-align on tags (h1, p) should work as expected.

If the template uses a custom font for body text, the rich text editor will not load this. It will display correctly in the preview.

Extra colours in colour picker

The colour picker supports a number of colours by default.

For more flexibility and to support brand colours, add a styles property to the attribute om:extra-styles.

<div om:editable="rich-text" om:id="1" om:extra-styles='{"colours": ["red", "#ee8d76"]}'></div>

Custom fonts

The om:extra-styles attribute also accepts information on custom fonts.

This displays the font menu in the rich text editor.

<div om:editable="rich-text" om:id="1" om:extra-styles='{"fonts": [{"family": "Hasklig"}]}'></div>

This is supported in three formats. The chosen format does not affect the email, only the display in the rich text editor.

The first does not load the font from any link and relies on the user having the installed font to display in the rich text editor.

{"fonts": [{"family": "Hasklig"}]}

The next format is suitable for including a CSS file. This is popular with Google fonts.

{ "fonts": [{"family": "Indie Flower","import": "https://fonts.googleapis.com/css?family=Indie+Flower"}]}

The final format allows linking directly to font files.

For more control, "fontFace" should be provided. This can contain any CSS that is valid in an @font-face rule.

Note: The properties should be camel-case and not kebab-case.
{"fonts": [{
    "family": "My Font",
    "eot": "https://example.com/font.eot",
    "woff2": "https://example.com/font.woff2",
    "woff": "https://example.com/font.woff",
    "ttf": "https://example.com/font.ttf",
    "fontFace": {
      "fontWeight": "bold",
      "fontStyle": "normal" }  }]}

Link tags

This allows for editable links (<a/> tags).

In the Visual editor, the user will be able to edit the target URL (href), text content, styles (as a CSS string) and link name (shown in the link click report).

<a om:editable="link" om:id="1" href="https://ometria.com" om:linkname="homepage link">
    the link text
</a>

Blocks

In order to support blocks a template needs two things:

  • A parent 'blocks' container to insert the blocks into. Currently Ometria only supports one blocks region per template. This is marked by applying the om:blocks attribute to a tag (typically div or table). The HTML element with the om:blocks attribute should be empty and placed where you would like the block elements to be placed when in the visual editor.
  • One or more 'block' elements which are the repeatable blocks inside the blocks container. These are marked by applying the om:block attribute and giving them a name, e.g. om:block="My block". Each block must have a name and it must be unique in the template.

An example of a minimum viable template:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta charset="utf-8"> <!-- utf-8 works for most cases -->
        <meta name="viewport" content="width=device-width"> <!-- Forcing initial-scale shouldn't be necessary -->
        <meta data-fr-http-equiv="X-UA-Compatible" content="IE=edge"> <!-- Use the latest (edge) version of IE rendering engine -->
        <title>{{ email.subject }}</title> <!-- The title tag shows in email notifications, like Android 4.4. -->
    </head>
    <body>
        <div id="header">
            <img src="http://www.example.com/logo.jpg" om:editable om:id="1"/>
            <span om:editable om:id="2">Strapline</span>
        </div>
        <div om:blocks></div>
        <div om:block="block type 1">
            <h1 om:editable om:id="3">Hello there</h1>
            <p om:editable="html" om:id="4">Some editable <i>HTML</i> content</p>
        </div>
        <div om:block="Product block">
            {% if products %}
                <h3>Lovely products</h3>
                <ul>
                {% for product in products%}
                    <a href="{{ product.url }}"><img src="{{ product.image_url }}" /></a><br />
                    <a href="{{ product.url }}">{{ product.title }}</a>
                    {{ product.price }}
                {% endfor %}
                </ul>
            {% else %}
                <h3>Sorry no products</h3>
            {% endif %}
        </div>
    </body>
</html>

Blocks in Automation campaigns

Blocks can also be used in Automation templates.

See: Code examples for automation blocks

Related articles

Comments

0 comments

Please sign in to leave a comment.