# PrestaShop 8 & 9 Buying Guides: documentation > Overview The module creates buying guide pages from your catalog. Each guide answers a customer question, for example "Which robot vacuum to choose for a flat with pets?". You choose… - Page: - Language: en - Last updated: 2026-09-24 - Other languages: [fr](https://www.datafirefly.com/documentation/buying-guide-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/buying-guide-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/buying-guide-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/buying-guide-prestashop/index.md), [pl](https://www.datafirefly.com/pl/documentation/buying-guide-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/buying-guide-prestashop/index.md), [pt](https://www.datafirefly.com/pt/documentation/buying-guide-prestashop/index.md) - Index: ## Overview The module creates buying guide pages from your catalog. Each guide answers a customer question, for example "Which robot vacuum to choose for a flat with pets?". You choose the products compared and the criteria, the module calculates a score out of 100 for each product, picks three products and generates the ranking, the comparison table, the statistics and the FAQ. The ranking is recalculated when the catalog changes. ## Installation 1. In **Modules > Module Manager**, click **Upload a module** and select `dfbuyingguide-1.1.0.zip`. 2. Installation creates the **Catalog > Buying guides** tab, the module tables and the `img/dfbuyingguide/` folder for cover images. 3. The module **Configure** button opens this tab directly. From version 1.0.0, simply upload the 1.1.0 ZIP: the upgrade script adds the columns and the statistics tables without touching your guides. ## General settings The **Settings** panel, below the list of guides, contains: - **URL prefix**: `guides` by default. Guides are served at `/guides/guide-url` and the index of all guides at `/guides`. - **Maximum age of a ranking**: 12 hours by default. After this delay, a ranking is recalculated on the next visit even without catalog changes, which follows scheduled discounts. - **Products analysed per guide**: 300 by default. The best selling products of the scope are analysed first. Raise it for large categories, up to 5,000. - **Show the guide badge on product pages**: products that hold a pick or a top 3 rank show a link to the guide. - **Show the guides on category pages**: a block at the bottom of categories lists the guides whose scope contains the category. - **Measure audience and sales**: enables statistics and the `dfbg_attr` attribution cookie (see below). ## Creating a guide Click **Add a buying guide**. The main fields: - **Title**: write it as the customer's question. A guide is only published in the languages where it has a title. - **Friendly URL**: generated from the title when left empty. - **Cover image**: shown at the top of the guide, on the guides page and in social shares. Landscape, at least 1,200 px wide. It is resized to 1,600 px wide at most. - **Author** and **Author role**: shown under the title and included in the structured data. - **Introduction**: who the guide is for and what matters for this use. - **Products compared**: the categories of the scope. No category ticked means the whole catalog. **Include subcategories** is on by default. - **Minimum price** and **Maximum price**: 0 means no limit. The price is the one displayed to visitors, in the default currency. Useful for a guide such as "the best models under $300". - **Products in stock only**: leaves out out-of-stock products when stock management is enabled. - **Products in the ranking**: 1 to 20, 5 by default. The picks are always shown, even outside this ranking. - **Small budget pick threshold**: 50% by default (see "The three picks"). - **Let visitors adapt the ranking**, **Show the comparison table**, **Show the FAQ**. - **Additional questions**: one question per line, in the form `Question | Answer`. They are added after the generated questions. - **Conclusion**, **Meta title** and **Meta description**: the title and the start of the introduction are used as defaults. - **Published**: an unpublished guide can still be previewed from the back office. Click **Save and stay**: the criteria, current ranking, audience and history panels appear below the form. ## Criteria Without criteria, products are ranked by sales. Click **Add a criterion** and choose a type. ### Criterion types - **Feature: preferred values**: you give 0 to 100 points to each value of a feature, for example Material: stainless steel 100, aluminium 70, plastic 30. After the first save, the form lists every value of the feature with a slider and buttons to fill all values at once. A product with several values keeps the best one. - **Feature: numeric value**: the module reads the number in the value ("90 min", "1,200 W", "2.5 kg") and compares products. Choose in **Best values** whether higher or lower is better. **Minimum value** and **Maximum value** leave out products outside the range or without a value. **Unit** is added to the figures of the statistics. - **Price (lower is better)**. - **Sales (popularity)**: based on quantities sold. - **Recent products**: based on the date the product was added. ### Weight, requirement and texts - **Weight**: 0 to 10. Weight 0 shows the criterion in the comparison table without using it in the score. - **Required** (feature criteria): products without this feature, or whose value scores 0 points, are left out of the guide. - **Label shown to visitors**: the feature name is used when left empty. - **Buying advice**: explains why this criterion matters. It appears in the "How to choose" section, above the catalog statistics. The arrows of the criteria list change their display order in the comparison table and the "How to choose" section. ## How the score is calculated For each criterion, product values are brought to a 0 to 100 scale: the best product of the scope gets 100 and the weakest 0 for numeric, price, sales and newness criteria, and the points you gave apply to value criteria. The overall score is the average of the scores weighted by the criterion weights. Prices are compared in the default currency. The **Current ranking** panel lists the first 20 products with their overall score, price, pick and one score column per criterion. Use it to tune the weights before publishing. ## The three picks - **Best overall**: the product ranked first. - **Best value for money**: among products cheaper than the best overall with a score of at least 60% of its score, the one with the best ratio between score and price. - **Best on a small budget**: the cheapest product reaching the percentage set in **Small budget pick threshold** of the best overall score, when it is cheaper than the two other picks. A pick only appears when a product meets the condition. The strengths of a product are its criteria scored 70 or more (3 at most), the points to consider those scored 30 or less (2 at most). ## Ranking updates Changing a product, a specific price, a feature value or a category flags the rankings for recalculation. A stock change only flags the guides set to "Products in stock only". Recalculation happens: - on the next visit of the guide; - through the cron task, if you schedule it; - with the **Rebuild now** button of a guide or **Rebuild all rankings now** in the list. ### Cron task The cron URL is shown above the list of guides. Call it every hour so that visitors never wait for a recalculation. Add `&force=1` to rebuild every guide. The **New token** button replaces the token, the old URL then stops working. Example: ``` 0 * * * * curl -s "https://your-shop.com/index.php?fc=module&module=dfbuyingguide&controller=cron&token=YOUR_TOKEN" > /dev/null ``` ### Displayed date and history The "Ranking updated on" date shown to visitors only changes when the top of the ranking or the picks change. The **Recommendation history** panel lists these changes with the first 5 products at each date. Module hooks do not run for an employee whose profile lacks the "View" right on the module. If your team edits the catalog with such a profile, the cron task and the maximum age of rankings act as a safety net. ## The guide page In order: title, author, number of products compared and update date, cover image, introduction, table of contents, picks, ranking, comparison table, "How to choose" section, conclusion, FAQ, a method note and related guides (published guides sharing a category). ### Adapt the ranking When the option is on and the guide has at least 2 weighted criteria, a panel above the ranking offers an importance slider per criterion and a maximum budget slider. The ranking is recalculated in the browser among the 20 best products, without reloading, and a link restores the ranking of the guide. Without JavaScript, the panel stays hidden. Search engines always see the ranking of the guide. ### Add to cart Products that can be added to the cart directly, without a combination to choose, show an **Add to cart** button that uses the theme add to cart. Others show **View the product**. In catalog mode, no cart button is shown. ### Preview of an unpublished guide The **Preview the guide** button opens the page with a preview banner. The link carries a token specific to the guide, the page is set to `noindex` and statistics are not counted. ### Customising colors Colors are defined by CSS variables your theme can override: `--dfbg-accent`, `--dfbg-accent-soft`, `--dfbg-muted`, `--dfbg-line`, `--dfbg-surface`, `--dfbg-low` and `--dfbg-radius`. Fonts come from the theme. ## Placements and SEO - **Guides index**: `/guides`, with the cover image or the top ranked product of each guide. - **Category pages**: `displayFooterCategory` hook. - **Product pages**: `displayProductAdditionalInfo` hook, pick badge or "Ranked #X" with a link to the guide. - **Free placement**: `{hook h='displayDfBuyingGuides' id_category=12}` in a theme template. Without `id_category`, all guides are listed. - **Sitemap**: when the native gsitemap module is installed, the index and the guides are added with the date of their last recommendation change. - **Structured data**: Article (with author and image), ItemList of the ranking and FAQPage. Open Graph tags are added to the head. - **Multilingual**: canonical, hreflang to each language where the guide has a title, and 301 redirect when a URL is opened in another language. ## Audience and sales The list of guides shows views and revenue for the last 30 days, and four overall indicators at the top. Each guide has an **Audience and sales** panel for 30 days and since the start: - **Views**: one per visitor, per guide and per day, bots excluded. - **Product clicks** and click rate compared with views. - **Add to cart clicks** from the ranking. - **Visitors who adapted the ranking**. - **Orders** and conversion rate compared with views. - **Revenue tax excluded**: amount excluding tax of the products that came from the guide, converted to the default currency. ### Sales attribution When a visitor clicks a product from a guide, the first party cookie `dfbg_attr` remembers the product and the guide for 30 days. When the product enters the cart, the attribution is copied to the cart. When the order is validated, including through a payment webhook, the order and the amount excluding tax of that product are attributed to the guide. Only validated orders (paid status or equivalent) are counted. The `dfbg_attr` cookie is set on click without going through your consent manager. List it in your cookie policy or turn off **Measure audience and sales**. ## Duplicating a guide The **Duplicate** action of the list copies the guide with its criteria, value points, shops and image. The copy is created unpublished, with a suffixed URL, and opens directly for editing. ## Multistore Each guide is assigned to the shops chosen in its form. Rankings, history and statistics are calculated shop by shop. ## Troubleshooting - **"No product matches this guide"**: check the categories, the price range, the stock option and the required or threshold criteria. - **An expected product is missing**: it must be active, visible in the catalog and among the analysed products. Raise "Products analysed per guide" for large categories. - **The guide returns a 404 error**: it is not published, has no title in this language or is not assigned to this shop. - **The ranking does not follow a change**: click "Rebuild now" and schedule the cron task. - **The cover image is refused**: check that the `img/dfbuyingguide/` folder is writable.