# DataFirefly Dealer Locator: catalog mode and dealer map

> This module turns a PrestaShop 8 or 9 shop into a brand showcase: it disables online sales on all or part of the catalog, adds a Where to buy button…

- Page: <https://www.datafirefly.com/en/documentation/dfdealerlocator/>
- Language: en
- Last updated: 2026-10-07
- Other languages: [fr](https://www.datafirefly.com/documentation/dfdealerlocator/index.md), [es](https://www.datafirefly.com/es/documentation/dfdealerlocator/index.md), [de](https://www.datafirefly.com/de/documentation/dfdealerlocator/index.md), [it](https://www.datafirefly.com/it/documentation/dfdealerlocator/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfdealerlocator/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfdealerlocator/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfdealerlocator/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

This module turns a PrestaShop 8 or 9 shop into a brand showcase: it disables online sales on all or part of the catalog, adds a Where to buy button on product pages and publishes a dealer directory with a map, opening hours, contact form and a page for each dealer.

## Installation

1. In **Modules > Module Manager**, click **Upload a module** and send the ZIP file.
2. The module creates the **Sell > Dealer network** menu with three entries: Dealers, Contact requests and Settings.
3. The directory page is created automatically with a URL translated per language: `/where-to-buy`, `/ou-acheter`, `/donde-comprar`, `/wo-kaufen`, and so on.

To update, simply upload the new ZIP: the upgrade scripts add the missing columns and hooks. If the directory or the dealer pages return a 404 error, save **Shop Parameters > Traffic & SEO** once to regenerate the .htaccess file.

Compatibility: PrestaShop 8.0 to 9.x, multistore, no Composer dependency. Translations included in English, French, Spanish, German, Italian, Dutch, Polish and Portuguese.

## Configuring catalog mode

Open **Dealer network > Settings**, **Catalog mode** block. Catalog mode is applied on the fly: the native PrestaShop setting is never changed, and everything is back to normal if you disable the module.

### Online sales

- **Enabled**: catalog mode is off, the module only works as a directory.
- **Disabled for the whole catalog**: no product can be added to the cart any more.
- **Disabled only for the selection**: only the categories, brands and products selected below switch to catalog mode.
- **Disabled for everything except the selection**: the selection is still sold online, the rest switches to catalog mode.

### Prices, message and cart

- **Hide prices**: when disabled, prices stay visible. You can then show a label under the price, Recommended retail price by default.
- **Message on the product page**: text shown above the button, for example This product is sold exclusively through our network of authorised dealers. Leave empty to hide it.
- **Redirect the cart and checkout to the dealer directory**: in full catalog mode, the cart and checkout pages send visitors to the directory.

The cart is blocked server side: an add to cart forced through a URL is refused.

### Exempt customer groups

Tick the groups that can still order online. Example: a Dealers group that orders its stock on the site while the public only sees the catalog.

## The Where to buy button

**Where to buy button** block of the settings:

- **Products concerned**: only products that cannot be bought online, or all products.
- **Button text**, translatable.
- **On click**: open a window with the map and the dealers carrying the product, or go to the directory filtered on the product.
- **Show availability under the button**: Available from 14 dealers, then the nearest dealer once the visitor has already searched a location.
- **List online retailers**: dealers of type Online retailer are listed apart, with a button to the product on their shop.

The button only lists the dealers carrying the product (see the Products sold tab of a dealer). The window opens on the last city searched by the visitor.

## Directory and map

**Dealer directory and map** block:

- **Introduction text** shown above the search, and **accent colour** of buttons, markers and clusters.
- Default map **centre and zoom**, **distance unit** (km or miles), **search radius choices**, **default radius** (0 = no limit) and **maximum number of results**.
- **Map style**: CARTO Voyager, CARTO Positron, OpenStreetMap or a custom tile server (https URL containing {z}, {x} and {y}).
- **Ask before loading the map**: for GDPR, the tile server only receives the visitor IP address after a click.
- **Group nearby markers** and **one marker colour per dealer type**, with a legend on the map.
- **Full list of dealers by country** under the map, readable by search engines.
- **A page for each dealer**: see below.

Visitors search by city or postcode, or use their location. They can filter by dealer type and tick Open now. On mobile, a button switches between the list and the map. The Leaflet map is hosted inside the module: no API key is needed.

## Geocoding

Geocoding turns an address or a city into coordinates. Results are cached in the database.

- **OpenStreetMap Nominatim**: free, limited to one request per second. Fill in the **contact email**, recommended by the Nominatim usage policy.
- **Google Geocoding API**: requires a Google API key.
- **Limit searches to these countries**: ISO codes separated by commas, for example `fr,be,ch`.

## Managing dealers

Menu **Dealer network > Dealers**. A dealer form has four tabs.

### General

- **Name**, **type** (retailer, distributor, showroom, service centre, online retailer), **logo** (JPG, PNG, WebP or GIF, 2 MB maximum).
- **Partner**: Official partner badge, listed first when no location is given.
- **Phone**, **website** and **email**: the email receives contact requests and is never shown when the contact form is enabled.
- **Product link on the dealer shop**: optional, adds a Buy online button. Available tags: `{reference}` `{ean13}` `{upc}` `{mpn}` `{name}` `{id_product}`. Example: `https://shop.example.com/search?q={ean13}`
- **Dealer area access**: email of an existing customer account (see Dealer area).

### Address and map

The dealer is placed on the map automatically when you save it. The **Find the position from the address** button runs geocoding again, and you can click on the map or drag the marker to adjust the position.

### Description and opening hours

Multilingual description, opening hours grid over 7 days with two slots per day (the second one is for a lunch break), buttons to copy Monday to the other days, and a **Good to know** field for public holidays or seasonal closures. An empty day means closed. Opening hours drive the Open now badge and filter, computed in the shop time zone.

### Products sold

Choose **The whole range** or a selection of categories, brands and products. Only the dealers carrying a product appear in its Where to buy button.

## CSV import and export

**Import CSV** button of the dealer list. Format: UTF-8, semicolon separated, first line with the column names. The easiest way is to export your dealers first to get a ready-made file.

Columns: `id;name;type;active;featured;address1;address2;postcode;city;country_iso;phone;email;website;product_url;latitude;longitude;scope;categories;manufacturers;products;description;hours;opening`

- Only `name` is required. Leave `id` empty to create a dealer, or tick the update of existing dealers.
- `type`: retailer, distributor, showroom, service or online. `country_iso`: two letter code.
- `scope`: 0 for the whole range, 1 for the categories, brands and products listed, separated by a vertical bar: `3|8|12`.
- `opening`: day number (1 = Monday) then time slots, days separated by a slash: `1=09:00-12:00,14:00-19:00/2=09:00-19:00/6=10:00-18:00`

After importing dealers without coordinates, click **Place imported dealers on the map**: geocoding runs in batches, one address per second. Keep the page open during the operation.

## Contact requests

**Contact requests** block of the settings: enable the form on each dealer, the email to the dealer, a copy to your address, the consent checkbox text and the privacy policy page.

The form is protected against spam (trap field, minimum delay, five submissions per hour and per IP address). Requests are listed in **Dealer network > Contact requests**, with filters, a detailed view, processed or to process status and CSV export.

## Dealer area

Enable **Dealer area in the customer account**, then enter the email of an existing customer account in a dealer form. Once logged in, this customer sees a **Dealer area** tile in My account. They can:

- edit their phone, website, opening hours, Good to know field and description in their language;
- read their contact requests and mark them as processed;
- see their 30-day statistics: website visits, phone clicks, directions, requests.

The address and the map position stay managed by the brand. One account can manage several dealers.

## Dealer pages and SEO

With the **A page for each dealer** option, each dealer (except online retailers) gets a page such as `/where-to-buy/12/lumiere-co-lyon`: address, map, opening hours, description, contact form and nearby dealers. Pages include Store structured data with schema.org opening hours and a canonical URL, and redirect with a 301 when the name or city change. They are added automatically to the sitemap when the Google Sitemap module (gsitemap) is installed.

## Statistics

The configuration page shows the activity over 30 days: most contacted dealers with the detail of clicks (website, phone, directions, buy online, requests) and products with the most Where to buy clicks.

## Theme integration

The button is displayed automatically through the `displayProductAdditionalInfo` hook. To place it elsewhere, use the widget:

- dealer search box: `{widget name='dfdealerlocator'}`
- Where to buy button of a product: `{widget name='dfdealerlocator' id_product=$product.id}`

## Troubleshooting

### The map stays grey

The tile server is probably blocked by a security policy (CSP) or a firewall. Allow the domain of the chosen style (basemaps.cartocdn.com or tile.openstreetmap.org) or use a custom server.

### The Where to buy button does not appear

Check that your theme calls the `displayProductAdditionalInfo` hook on the product page, and that the Products concerned setting matches the product tested. Otherwise, insert the widget in the product template.

### An address is not found

Fill in at least the city or postcode and the country, then click Find the position from the address. If the address is still not found, place the marker by hand on the map.

### 404 error on the directory or a dealer page

Regenerate the .htaccess by saving **Traffic & SEO**, and check that the friendly URL of the `module-dfdealerlocator-directory` page is filled in for each language.