Locator Upgrade - Contao CMS Steps
Search engines and AI assistants often cannot see your store finder. When they visit the page, your stores are not on it yet: they only appear later, on the visitor's screen. So your stores can be missing from search results and from the answers AI assistants give.
After these steps, every store finder page arrives with its stores already on it, with names, addresses and opening hours. Search engines and AI assistants can find each of your stores and show it. Your visitors see the store finder as usual.
It works for a store finder already on your site and for a new one. Contao builds the page, and Apache, in front of it, adds the stores. Steps 1 and 2 happen in Apache's configuration, step 3 in Contao, and step 4 in both. Step 5 restarts Apache and checks the result.
What you need
Contao 3.5, on Apache 2.4
Rewrite URLs on, in Contao's back end at System → Settings → Front end configuration: your addresses have no index.php/ in them. If they have, talk to your developer first: turning it on changes every address of your site, and Contao then answers the old ones, with index.php/, as not found
Access to your Apache configuration, or someone who has it. A .htaccess file is not enough
An administrator account in Contao's back end, and access to the files of your Contao installation, for steps 3 and 4
Your render token, from Uberall
Your locator key, from Uberall. If the store finder is already on your site, it is the data-key of its snippet:
<div id="store-finder-widget" data-key="YOUR_LOCATOR_KEY"></div>
Your store finder's address: the page it is on, such as https://www.example.com/store-locator.html. Each store gets its own address under it
How your site serves the store finder page
Some lines differ with how your addresses end. To find out, look at the store finder's address in your browser, or in Contao's back end at System → Settings → Front end configuration → URL suffix:
-
a) The addresses end in
.html, Contao's default URL suffix, such ashttps://www.example.com/store-locator.html. A store's page is thenhttps://www.example.com/store-locator.html/l/berlin/.... -
b) The addresses end in
/, or in nothing, such ashttps://www.example.com/store-locator/. A store's page is thenhttps://www.example.com/store-locator/l/berlin/....
In the examples, store-locator is the store finder page's alias, its Page alias in Layout → Site structure. Use yours.
If Add the language to the URL is on in the same settings, your addresses start with the language, such as https://www.example.com/de/store-locator.html. Then put the language in front of the page's address wherever this guide shows it: /de/store-locator.html, and de/store-locator.html in step 4's initconfig.php.
If Contao is in a folder of your site, such as https://www.example.com/shop/, put the folder in front of the page's address in steps 2 and 4 on Apache: /shop/store-locator.html. Not in initconfig.php.
How Apache runs PHP matters in step 4 too. Find out: look in your Apache configuration for a ProxyPassMatch line with \.php in it. If there is one, your PHP runs through PHP-FPM that way, and step 4 has one more block for you. With SetHandler, in a <FilesMatch> or a <Files>, or with Apache's own PHP module, it does not.
If the store finder is already on your site
After these steps, your store finder pages use only the settings saved at Uberall. What is set on the page itself no longer applies there:
- attributes on the store finder's
div, other than the ones theincludes repeat (step 3), anddata-baseurl, which you remove in step 3 - settings your site's scripts pass to
UberallStorefinderMountorUberallStorefinderRestart, other thanwithoutMap
To find them, look in two places:
-
The store finder's
div, in the page's source: anydata-attribute other than the ones theincludes repeat. -
Your site's scripts, in the page's source and in your theme's JavaScript files: calls to
UberallStorefinderMountorUberallStorefinderRestart.
If you find any of these settings, send them to Uberall before you start, to be saved with your store finder. Until then, leave the page as it is: the store finder keeps working as it does today.
Your pages' title and description
Uberall gives every store finder page its own canonical link. The title, the description and the preview image for social media come from Uberall only when they are set up there:
- The store finder's main page, and its directory pages (the lists of stores by country, region or city): only what is set up at Uberall. With nothing set up, these pages have no title and no description.
- A store's page: always a title and, when the store has one, a description: the store's name and short description, unless others are set up. The image is the store's photo.
In step 3 you take Contao's title and description off these pages. So check with Uberall first that a title and a description are set up for your store finder, or send yours to be saved with it.
Step 1: Connect your web server to Uberall
These Apache modules must be on: include, proxy, proxy_http, ssl, headers, rewrite and deflate. Most servers have them already. If not, your hosting provider can turn them on.
Open your site's configuration, the file with your <VirtualHost>, and paste this inside the <VirtualHost> block. Replace YOUR_RENDER_TOKEN with your token:
SSLProxyEngine on
SSLProxyVerify require
SSLProxyVerifyDepth 10
SSLProxyCACertificateFile /etc/ssl/certs/ca-certificates.crt
<Location "/api/locator-fragments/">
Require expr %{IS_SUBREQ} == 'true'
RequestHeader set x-uberall-render-token "YOUR_RENDER_TOKEN"
RequestHeader unset Accept-Encoding
RequestHeader unset Cookie
RequestHeader unset Authorization
RequestHeader unset Proxy-Authorization
RequestHeader unset Via
ProxyAddHeaders Off
ProxyPass "https://uberall.com/api/locator-fragments/" connectiontimeout=2 timeout=10
ProxyErrorOverride On
</Location>
The token stays on your server. Visitors never see it.
The certificate file lists the authorities your system trusts, and where it is depends on the system:
| System | File |
|---|---|
| Debian, Ubuntu, Alpine | /etc/ssl/certs/ca-certificates.crt |
| Red Hat, CentOS, AlmaLinux, Rocky, Amazon Linux | /etc/pki/tls/certs/ca-bundle.crt |
| openSUSE | /etc/ssl/ca-bundle.pem |
If yours is not there, openssl version -d shows the folder where OpenSSL keeps it.
Step 2: Turn on includes for the store finder page
In the same <VirtualHost>, below the block from step 1, paste this. Replace /store-locator.html with your store finder page's address, without your domain. For b), leave out the / at the end: /store-locator.
<Location "/store-locator.html">
Options +IncludesNOEXEC
SetOutputFilter INFLATE;INCLUDES;DEFLATE
SSIErrorMsg "<!-- -->"
</Location>
Contao builds every page with its index.php, so the includes are turned on for the page's address, not for a file. INFLATE and DEFLATE keep them working when PHP compresses the page: Apache does not run the includes in a compressed page. Visitors still get the page compressed.
Paste it below the <Location> blocks your <VirtualHost> already has. When two <Location> blocks set the same thing for an address, the later one wins.
This block works together with the RewriteRule of step 4. Without that RewriteRule, Contao's .htaccess passes the page on to index.php under another address, and the includes stay off.
Step 3: Put the store finder on its page
The page needs two includes and the store finder snippet. Replace YOUR_LOCATOR_KEY with your locator key, in all three places:
<!--#include virtual="/api/locator-fragments/head?key=YOUR_LOCATOR_KEY&path=${REQUEST_URI}" -->
<div id="store-finder-widget" data-key="YOUR_LOCATOR_KEY">
<!--#include virtual="/api/locator-fragments/body?key=YOUR_LOCATOR_KEY&path=${REQUEST_URI}" -->
</div>
<script src="https://locator.uberall.com/locator-assets/storeFinderWidget-v2.js"></script>
Keep path=${REQUEST_URI} at the end of each include. In Contao, they go in three places.
A page template without Contao's title and description
Contao writes the title and the description of every page from its page template. The store finder page gets a copy of that template without them.
The template is the one your layout names under Expert settings → Page template, or fe_page if it names none. Contao takes the first file of that name it finds: in your theme's Templates folder (in Layout → Themes, edit the theme), then in the templates folder of your installation, then among the templates of Contao and its extensions under system/modules. Contao's own fe_page is system/modules/core/templates/frontend/fe_page.html5.
Copy that file into the templates folder as fe_page_storefinder.html5. In Contao's own fe_page, delete these two lines from the copy:
<title><?= $this->title ?></title>
<meta name="description" content="<?= $this->description ?>">
A template of your theme can look different: delete its <title>, its description meta, and any canonical link, og:url or og:type tag in it. If its first line is <?php $this->extend(...); ?>, the title can come from the template it names: ask your developer to make the copy.
If the layout's Expert settings → Output format is XHTML, the file is fe_page.xhtml, and the copy fe_page_storefinder.xhtml. Its description line ends in />.
A page layout for the store finder page
Find the layout your store finder page uses: in Layout → Site structure, edit the page, and look under Layout settings. If Assign a layout is not ticked there, the page takes its layout from the nearest page above it that has it ticked, often the website root: look there.
In Layout → Themes, open your theme's Layouts, and duplicate that layout. In the copy:
-
Expert settings → Page template: choose
fe_page_storefinder. -
Expert settings → Additional <head> tags: paste the first
include. -
JavaScript → Custom JavaScript code: paste the
script, if the page does not load the store finder yet.
Then edit the store finder page in Layout → Site structure. Under Layout settings, tick Assign a layout, and choose the copy as Page layout. Pages under the store finder page in Site structure take this layout too: on each of them, tick Assign a layout and choose the layout they had.
If the page you found the layout on also has a Mobile page layout under Layout settings, visitors on mobile devices, and the smartphone crawlers of search engines, get that one. Duplicate it too, make the same three changes, and choose that copy as Mobile page layout on the store finder page. If you add a module to the layout's copy below, add it to this copy too.
The store finder's div
Paste the div, with the second include inside it, in the store finder page's content: in Content → Articles, as an element of the type HTML in the page's article. Or in a front end module of the type Custom HTML, in Layout → Themes → Modules, added to the layout's copy under Front end modules → Included modules, or to the article as an element of the type Module.
Paste only the div there: Contao turns a <script> in these fields into text on the page. If a module or template your developer made shows the store finder, the second include goes inside its div, in that template.
If the div has data-baseurl, remove it. With any address in it other than https://locator.uberall.com, the store finder does not take over the stores in the page: it shows them again on the visitor's screen.
On the store finder pages, your site must not add its own canonical link, og:url or og:type tag: Uberall always sends them. With two canonical links, search engines may ignore both, or take yours, which is the same address for every store. Leave out your own title, description and other Open Graph tags there too, once they are set up at Uberall (see above).
If the page already has the store finder snippet, keep it, once its settings are at Uberall (the section above): add the two includes.
The store finder's address comes from what is set up at Uberall. Check with Uberall that it is set up, and without #!: the server only sees the part of an address before #. To use another address on this page, set it on the snippet and on the includes (below).
The snippet and the includes must match
These attributes of the snippet are also parameters of both includes. Whatever the snippet sets, the includes must set too, with the same value, before &path=:
| Snippet attribute | Include parameter | Without it |
|---|---|---|
data-key |
key |
Required |
data-widgetoriginurl |
widgetOriginUrl |
The store finder's address set up at Uberall |
data-language |
lang |
The language set up at Uberall |
data-countries |
countries |
The stores of every country set up at Uberall |
With data-language="de", data-countries="US,DE" and data-widgetoriginurl="https://www.example.com/store-locator.html" on the snippet, the first include reads:
<!--#include virtual="/api/locator-fragments/head?key=YOUR_LOCATOR_KEY&lang=de&countries=US,DE&widgetOriginUrl=https://www.example.com/store-locator.html&path=${REQUEST_URI}" -->
If your page loads storeFinderWidget-v2-withoutMap.js, or starts the store finder with withoutMap: true, add withoutMap=true to both includes too, before &path=.
If they differ, search engines get a page built with the values of the includes, and your visitors' browsers build the page again with the values of the snippet.
Step 4: Send every store's address to the store finder page
Each store's page lives at an address under the store finder, such as /store-locator.html/l/berlin/.... Apache and Contao have to answer all of them with the store finder page. On their own, they answer that the page is not found.
On Apache
In the same <VirtualHost>, paste this above any other RewriteRule lines it has, except a rule that redirects to www. or to https://: that one stays above it.
For a):
RewriteEngine on
RewriteRule ^/store-locator\.html(/|$) %{DOCUMENT_ROOT}/index.php [END]
For b):
RewriteEngine on
RewriteRule ^/store-locator(/|$) %{DOCUMENT_ROOT}/index.php [END]
If Contao is in a folder of your site, put the folder in both places: ^/shop/store-locator\.html(/|$) and %{DOCUMENT_ROOT}/shop/index.php.
For b), this also answers the page's address without the / at the end, which is the one Uberall puts in the page's canonical link, instead of sending you on to the address with /. It also sends to the store finder any other page whose address starts with /store-locator/. Contao gives the pages under the store finder page such addresses when Enable folder URLs is on in System → Settings. Give those pages another Page alias first: moving a page does not change its address.
[END] makes Apache skip the RewriteRule lines in your .htaccess for these addresses. Without it, a rule there that adds a / or www. to addresses can send visitors to index.php. So a redirect in your .htaccess, for example to www., no longer applies to these addresses. To keep one for them, write it in the <VirtualHost>, above these lines, in this form, with your domain:
RewriteCond %{HTTP_HOST} ^example\.com$ [NC]
RewriteRule ^ https://www.example.com%{REQUEST_URI} [R=301,L]
If your <VirtualHost> has a rule of its own that sends every address to index.php, put this line just above it, so that it leaves the includes alone:
RewriteCond %{REQUEST_URI} !^/api/locator-fragments
If your PHP runs through ProxyPassMatch (see above), add this too. Replace unix:/run/php/php-fpm.sock|fcgi://localhost with the address at the start of the second part of your ProxyPassMatch line, without the folder after it, such as fcgi://127.0.0.1:9000:
<Files "index.php">
SetHandler "proxy:unix:/run/php/php-fpm.sock|fcgi://localhost"
</Files>
Without it, Apache sends the store finder's visitors the text of index.php instead of the page. It needs Apache 2.4.10 or later (apachectl -v), and PHP-FPM has to find your files in the same folder as Apache, the one in your ProxyPassMatch line. If either is not so, ask your hosting provider.
In Contao
Create the file system/config/initconfig.php in your Contao installation, with this. If the file is there already, add the lines from if on at its end, before a closing ?> if it has one.
For a):
<?php
if (preg_match('#^store-locator\.html(/|\?|$)#', Environment::get('request'))) {
Environment::set('request', 'store-locator.html');
}
For b), with addresses that end in /:
<?php
if (preg_match('#^store-locator(/|\?|$)#', Environment::get('request'))) {
Environment::set('request', 'store-locator/');
}
With addresses that end in nothing, use Environment::set('request', 'store-locator');.
Contao reads this file on every request, before it looks up the page. The addresses in it start without /, and without the folder Contao is in.
Step 5: Restart and check
Restart Apache:
sudo apachectl configtest && sudo apachectl graceful
Then purge Contao's page cache: System → Maintenance → Purge data, with Purge the page cache. If the store finder page, or a page above it, has a cache timeout under Cache settings, Contao otherwise keeps sending the page it cached before step 3.
Open your store finder in the browser, right click, and choose View page source. Search the source for __ubSfSsr. If you find it, it works. Check in the browser, or with curl --compressed: a plain curl gets the page uncompressed, and can show the stores while browsers still get the include lines.
Search the same source for <title and rel="canonical". Each should appear exactly once. If one appears twice, the page still has its own: see step 3. If <title is missing, the store finder has no title set up at Uberall yet.
Then open one of your stores and copy its address into a new tab. The store's page should open. For b), open the store finder's address without the / at the end too: it should open the store finder, and keep its address.
More than one store finder on the site
Each store finder has its own render token, and the <Location> from step 1 sends one. So the second store finder gets a <Location> of its own. Paste this below the one from step 1, and replace YOUR_OTHER_RENDER_TOKEN with the second store finder's token:
<Location "/api/locator-fragments-2/">
Require expr %{IS_SUBREQ} == 'true'
RequestHeader set x-uberall-render-token "YOUR_OTHER_RENDER_TOKEN"
RequestHeader unset Accept-Encoding
RequestHeader unset Cookie
RequestHeader unset Authorization
RequestHeader unset Proxy-Authorization
RequestHeader unset Via
ProxyAddHeaders Off
ProxyPass "https://uberall.com/api/locator-fragments/" connectiontimeout=2 timeout=10
ProxyErrorOverride On
</Location>
It differs from the first only in its address, /api/locator-fragments-2/, and in the token. Do not paste the first one twice with another token: Apache would send the last token for both store finders.
Then follow steps 2 to 5 for the second store finder's page, with two changes: its includes start with /api/locator-fragments-2/ instead of /api/locator-fragments/, and in initconfig.php you add a second if block, with its address.
For a third store finder, use /api/locator-fragments-3/, and so on.
The same store finder on a page of its own per language needs no other token: follow steps 2 to 5 for each page, with its own address, with its data-language and lang, and with its address in data-widgetoriginurl and widgetOriginUrl (see step 3).
If it does not work
| What you see | What to do |
|---|---|
configtest reports an error |
A module from step 1 is off, or the certificate file does not exist. Ask your hosting provider. |
The store finder page shows or downloads text that starts with <?php
|
Your PHP runs through ProxyPassMatch: add the <Files> block from step 4. |
| The page still has Contao's title, as before step 3 | Purge Contao's page cache: see step 5. |
The source still shows the include lines |
Check step 2: its address is the page's, as in the browser, no <Location> below it sets SetOutputFilter for the page, and the deflate module is on (apachectl -M lists deflate_module). Check step 4 on Apache: the RewriteRule is in the <VirtualHost>, as written. |
The page shows the script line as text |
Move the script from the HTML element or module to the page layout: see step 3. |
| The page shows "[an error occurred while processing this directive]" | Add the SSIErrorMsg line from step 2. |
__ubSfSsr is in the source, but rel="canonical" is not |
The page does not use the layout from step 3. On mobile devices only: its Mobile page layout is not the copy from step 3. |
| A store's page says "Not Found", in plain text | Check step 4 on Apache. |
| A store's page is your site's page for addresses it does not know | Check step 4 in Contao: the file's name and place, and the page's address in it. |
For b), the store finder's address without / sends you on to the address with /
|
Check step 4 on Apache: the RewriteRule comes before the one that adds the /. |
__ubSfSsr is not in the source |
Check the token in step 1, the key in step 3, and that your store finder's address is set up at Uberall. If your <VirtualHost> sends every address to index.php, see step 4. Then contact Uberall. |
When the store finder content does not arrive
The store finder keeps working in every case. If the content does not arrive, because your server cannot connect to Uberall, the connection takes too long or it returns an error, the page loads without it, and the store finder appears on the visitor's screen as usual.
When changes show
A change at Uberall, to your stores or to your store finder's settings, takes a few minutes to show on these pages.
Contao's page cache does not keep the stores as they were: Apache brings them in each time it sends the page, also when Contao sends it from its cache. But with a cache timeout, and System → Settings → Front end configuration → Cache mode as Contao ships it, Contao lets browsers and proxies keep the page for that long too: add that time.
If your server or your CDN caches your pages, add the time your cache keeps them: each store finder page in that cache keeps the content it had when it was cached. And a page your cache stored while the content did not arrive stays without its stores, for search engines, until your cache stores it again.