Skip to content

Area: User guide

How layouts work

A layout is the markup Releva fills with products when it draws a product block: on a page of your site, inside an email, or under your shop’s search box. Releva keeps them under Assets › Layouts. The product block decides which products to show; the layout decides how they look. This page explains what a layout is made of and where it is used. To make one, follow Create a layout for email product blocks or Copy a layout and change its HTML.

Every layout has a Scope that you choose once, when you create it:

Scope Draws Where you pick it Loops over
Web A product block on a page of your site Layout in the product block form under Personalization › Product Blocks response
Email The product block inside an email The template picker of the product block in the email editor under Marketing Channels › Emails products
Search As You Type The results dropdown under your search box Layout for Search Results under Personalization › Search As You Type the search results

The scope is fixed after you choose it, and the pickers list only layouts with the matching scope. A Web layout never appears in an email’s picker. If you need the same design elsewhere, create a layout with the other scope.

A banner block can also embed a product block and refer to a layout by id. Releva does not count that as usage: such a layout shows Not used in the list and can be deleted while a banner still refers to it.

  • Visual builds the markup for you from style sections: General, Discount Badge, Product Name, Product Price, Product List Price and Product Discount Price, plus Block Styles, Top Call to Action, Block Title, Slider Navigation Styles and Bottom Call to Action for Web layouts. Each section has text fields, drop-downs and colour swatches, and the preview updates as you type.
  • HTML shows the markup itself in a code editor. The layout is HTML with Handlebars expressions. Custom Helper Functions lists the helpers Releva adds, such as formatPrice, addUtm, truncate, discountPercentage and date helpers.

Switching from Visual to HTML asks for confirmation (Setting Layout Form to Advanced action cannot be undone!) and is one way. A Search As You Type layout always uses the HTML editor. The list shows which editor a layout uses with the VISUAL EDITOR or HTML EDITOR badge.

  • Email layouts loop with {{#each products}}, Web layouts with {{#each response}}. Inside the loop you print product fields such as {{name}}, {{imageUrl}}, {{url}}, {{listPrice}}, {{discountPrice}} and {{custom.…}}.
  • Only Releva’s registered helpers work. Emails are compiled with unknown helpers disabled.
  • Keep styles inline for email layouts. Many email clients ignore <style> blocks.
  • Inside a Handlebars expression that sits in an HTML attribute, use single quotes: class="{{#if a}}'x'{{/if}}". Double quotes there make the save fail with The layout markup could not be parsed: Parse Error: ….
  • Releva minifies the markup when it saves it: whitespace is collapsed, comments are removed, inline CSS and JavaScript are minified. Emails render the minified version, so nothing may depend on a comment. Web and Search layouts render the markup as you wrote it.
  • The preview in the editor draws up to four products from your catalog, up to two with a discount and two without, so both price branches are visible. Pictures are loaded from your shop. Web and Search layouts written in the HTML editor have no preview in the admin: they depend on your shop’s CSS, so you check them with Edit on my site.
  • Names are unique per shop. The check ignores upper and lower case and surrounding spaces: a second demo grid next to Demo Grid is refused with Layout Name must be unique!.
  • The list under Assets › Layouts shows the newest layout first. Scope and Usage (Used / Not used) filter it; the search box matches the beginning of words in the name.
  • Each card shows the scope badge, the editor badge, one badge per email or per page - block that uses the layout, or Search-as-you-type when the search configuration uses it, and a clock badge with the created and updated dates. A layout with no usage badge shows Not used.

A layout opens read-only (This layout is read-only. Click Edit to make changes.). After Edit, an orange notice says which account and shop you are editing in. Save keeps you on the page and shows Layout saved; Save & close returns to the list.

If the layout is used by a product block or an email, saving asks once more: You are saving changes to “<name>” in <account> / <shop>. This layout is live: it is used by N recommender(s) and N email(s). Please make sure this is the right account and domain. (“Recommender” is the old name of a product block.) The change applies to every block and email that uses the layout as soon as you confirm. To try a change without touching live emails, select Make a copy, change the copy, and switch the block or email to it when you are happy.

A Web or Search layout can be previewed on your own shop while you edit it. The button Edit on my site sits under the editor once the layout is saved:

  • For a Web layout, Releva opens one of the pages the layout’s product blocks are placed on (Page to edit on when there are several). A layout used by no block cannot be opened: This layout is not used on any page yet, so there is no page of your site to edit it on.
  • For a Search layout, you enter Page to search on and a Sample query. Search as you type does not need to be switched on yet; the editor shows the results with your draft.

While the session runs, the editor shows Editing on <page> — <status>, for example waiting for your page to pick it up, rendered on 2 blocks or nowhere to put it on that page, and a notice if the layout’s own script throws on your page. Every change you type is sent to the open shop page as a draft and re-rendered there within a second or two; product blocks shown as a popup or banner are not re-rendered. Nothing is saved to the layout until you select Save; the session ends with End session, when you leave the editor, or 30 minutes after your last change. The browser must allow the pop-up window.

This works on web pages with the Releva JavaScript SDK only; the mobile SDKs have no edit mode. Email layouts have no Edit on my site: check them in the preview and with a test email.

  • Make a copy opens a new layout named Copy of <name> with the same scope, editor and markup. Scope and editor are locked on the copy.
  • Delete asks Are you sure? This action cannot be undone! and is disabled while a product block or an email uses the layout (hover over the button to see which). Deleting a layout that the search configuration uses is allowed; the search results then have no layout until you choose another one under Personalization › Search As You Type. A layout used only inside a banner block is not protected either.
  • A deleted layout cannot be restored. Copy it first if you may need it again.

Assets › Email Templates Gallery is a different thing: a catalogue of complete email designs from the email editor’s provider, filtered by Categories (Premium, Standard, Core), Feature, Type, Industry and Season. Use Template starts a new email from the design; opened from an existing email, it replaces that email’s design after you confirm (Are you sure you want to proceed? This action will overwrite any saved changes to your email.). It does not create or change layouts. Read How emails work for the email editor.