# How layouts work

> What a layout under Assets › Layouts is, the three scopes (Web, Email, Search As You Type), the Visual and HTML editors, what the markup can use, where a layout is chosen, how Edit on my site previews a Web or Search layout on your shop, and what copying and deleting do.

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](https://releva.ai/documentation/guides/layouts/create-a-layout-for-email-product-blocks/) or [Copy a layout and change its HTML](https://releva.ai/documentation/guides/layouts/copy-a-layout-and-change-its-html/).

## One layout, one scope

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.

## Two editors

* **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](https://handlebarsjs.com/) 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.

## What the markup can do

* 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 and the list

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

## Editing a layout that is in use

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.

## Edit on my site (Web and Search layouts)

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.

## Copying and deleting

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

## Email Templates Gallery

**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](https://releva.ai/documentation/learn/emails/how-emails-work/) for the email editor.

## Next steps

* [Create a layout for email product blocks](https://releva.ai/documentation/guides/layouts/create-a-layout-for-email-product-blocks/): Build an email layout in the Visual editor and use it in a product block.
* [Copy a layout and change its HTML](https://releva.ai/documentation/guides/layouts/copy-a-layout-and-change-its-html/): Start from an existing layout and edit its markup directly.
* [How product blocks work](https://releva.ai/documentation/learn/product-blocks/how-product-blocks-work/): See where a Web layout is chosen and how a block is shown.
* [Set up search as you type](https://releva.ai/documentation/guides/search-as-you-type/set-up-search-as-you-type/): Pick a Search As You Type layout for your shop’s search box.