"Zone": Injecting HTML inside a theme

"Zone" concept is here to help if you need to inject code from your extension to a specific place inside a theme

There are several ways to add code from your extension inside your website:

• create a page template

• create a block / list, that is available in the composer with composer

• If you need to add code (without CMS variables) to the head or the end of pages:

Add code to the head / end of body

Sometimes, you need to add code to a place that does not work with the earlier options. For example, you want to add a currency switcher next to the language switcher in the header.

• Can you use a page template for this? No

• Can you use a block or a list available in the composer? No

• Can you add it to the head/bottom? No, because it needs to be at a specific place in the header

"Zones" will help you inject code at a specific line inside the header of your theme.

A theme can define zones where the extension can put code.

An extension, can put code associated to a zone.

For example:

• in my extension, I say that there is a zone currency-switcher-container

• in my theme, I can put this currency-switcher-container zone anywhere I need to display it

Create zones in the theme

Inside your theme, you can name "zones" as "places where an extension can push code".

#$extension|zone|after-logo$#

For example, you could say that extensions are allowed to add their code:

• before the header

• after the language switcher

• define a "footer-widget" zone where extensions can inject their code

Each zone is defined with a unique key used on the extension to indicate which code should be injected.

The key of the zone can be:

• generic, if you want any extension to inject code at this specific place. For example, #$extension|zone|before-header$# if you have block settings that should write html at the top of the page

• specific if this is related to an extension, for example #$extension|zone|currency-switcher-container$# to allow the theme to decide where to put the currency switcher.

So you need to ask yourself:

• What code do I want to add?

• Where should it be inside the themes?

Inject code inside zones from the extension

Inside the zones, you can inject HTML. To define the content that should go inside a zone, inside the folder zone of your extension, create an html file using the key of the zone as filename

my-extension-folder/zone/zone-key.html

For example

zone/currency-switcher-container.html

zone/before-header.html

The HTML written inside these files will be injected inside the theme using the zones

Inside zones, you can use HTML, locales, partials, blocks, lists, but you can not have CMS variables directly inside zone/your-file.html; they have to be inside a block.

Examples

1 - Currency Switcher

Let's imagine that you have a Currency Switcher that can be displayed anywhere on the page, by adding this code in the HTML

<div class="glx-ext-currency-switcher-container"></div>

So need a way to inject this code inside the themes. And each theme should be able to put the currency switcher container where they want freely.

Inside the extension

• create zone/currency-switcher-container.html

• Put the HTML inside this file

Inside the theme

Define where you want to inject the code from the currency switcher, and write:

#$extension|zone|currency-switcher-container$#

Edit your "zone" blocks

• Website > Theme extensions > Theme extensions (select your extension) > tab "Zone extensions" > choose your zone

• same block across different zones? -> will have different content for each zone

• same zone used several times -> will have the same content everywhere it is used

• syndicated block -> works as everywhere else (same content shared)

I have added a new zone in the theme, but it is not visible in Theme Extensions > (choose extension) > Zone extensions

• check that the extensions indeed uses the zone (with the same name)

If everything should work

Go to Theme extensions > Zones parameters (highlighted in blue). Sometimes, the backoffice doesn't pick up the latest zone, going here "refresh it"