# Surface and Volume Quantity Calculator: installation and configuration

> Installation Install the module from Modules > Module Manager > Upload a module by sending the ZIP file, or copy the dfsurfacecalculator folder into the /modules/ directory of your shop…

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

## Installation

Install the module from **Modules > Module Manager > Upload a module** by sending the ZIP file, or copy the `dfsurfacecalculator` folder into the `/modules/` directory of your shop and click Install.

On installation, the module creates three tables (product settings, values per combination, calculations saved on carts), registers its hooks and adds the **Quantity calculator** tab under the Catalog menu. The Configure button in the Module Manager opens the same page.

The calculator does not appear on any product page until a product is configured, so you can install the module on a live shop without any immediate visible change.

## The five calculation types

- **Tiles and flooring (m²)**: length × width of each room, or known area. The content of one unit is the area covered by one box or pack.
- **Paint (litres)**: length × height of each wall, number of coats, coverage in m² per litre, doors and windows subtracted. The content of one unit is the volume of the can.
- **Wallpaper (rolls)**: width and height of each wall. The module counts strips, rounds each strip length up to the pattern repeat and calculates the number of full strips per roll.
- **Volume: concrete, gravel, soil (m³)**: length × width × thickness in centimetres, or known volume. The result is given in m³ per unit, or in bags if you enter the density of the material and the weight of one bag.
- **Length: skirting boards, trims (m)**: length of each wall or section. The content of one unit is the length of one piece.

## Configuring a product

Open the product page, **Modules** tab, **Quantity calculator** block.

1. Tick **Show the calculator on this product**.
2. Choose the **Calculation type** and the sales unit in **Sold by** (box, pack, can, bucket, roll, bag, piece, pallet or unit). This is the unit shown to the customer: “You need 12 boxes”.
3. Enter the content of one unit. The field label changes with the calculation type: surface covered by one unit, volume of one can, rolls per unit, volume of one unit or length of one piece.
4. Fill in the fields specific to the calculation type (see below).
5. Click **Save calculator settings**. The settings are also saved with the main save button of the product page.

### Paint

Enter the **Coverage** in m² per litre, as printed on the can, and the number of **Coats suggested by default**. The **Let the customer subtract doors and windows** option adds two fields to the calculator; the area subtracted per door and per window is set in the module configuration (1.7 m² and 1.5 m² by default).

### Wallpaper

Enter the **Roll width** in centimetres, the **Roll length** in metres and the **Pattern repeat** in centimetres (0 or empty for a plain wallpaper). If the product is sold by the roll, leave the “Rolls per unit” field empty. Each strip is the wall height plus 10 cm for trimming, rounded up to the next pattern repeat.

### Volume sold in bags

For a product sold by weight, leave the volume per unit empty and enter the **Density of the material** in kg/m³ and the **Weight of one unit** in kg. The module then converts the volume into weight, then into a number of bags. Typical values: gravel 1500 to 1700, sand 1600, dry concrete mix 2000.

### Product-specific waste margin

The **Default waste margin for this product** field replaces the preselected margin for this product only. Leave it empty to use the module value. If the value entered is not among the offered choices, it is added to the choices of this product.

## Values per combination and pack size mix

If the product has combinations, a **Values per combination** table appears. Only fill in the combinations whose content differs from the product value, for example a 2.5 L can and a 10 L can. For a product sold by weight, the value entered is the weight of one unit in kg.

If your combinations are pack sizes, tick **The combinations are pack sizes: suggest the cheapest mix of sizes**. Below the result, the calculator then shows the combination of sizes that covers the need at the lowest price, the saving compared with the selected size, and a button that adds every line to the cart. The search covers the five sizes with the best price per unit of content.

## Using a product feature

If your catalogue already states the content of one unit in a feature (for example “Coverage per box: 1.44”), select it in **Feature holding the content per unit** in the configuration. It is used as the default value when the product field is empty. The same principle applies to paint coverage with **Feature holding the paint coverage**. The module reads the first number in the value, with a comma or a dot.

## Bulk activation by category

On the module page, the **Bulk assignment by category** block enables or disables the calculator on all products of the selected categories, subcategories included if the box is ticked. Choose the calculation type and sales unit to apply. By default, products already configured keep their settings; tick **Also change the type and unit of products already configured** to overwrite them. Packaging values already entered are never erased.

A product enabled without packaging information, neither in its field nor in the selected feature, stays hidden in the shop. It is listed with the **Incomplete** status in the configured products list, with a link to open its product page.

## Complementary products

In the Modules tab of the product page, the **Complementary products** block links up to 6 products calculated together with the main product: adhesive and grout for tiles, primer for paint, paste for wallpaper, sand for concrete.

1. Type at least two characters of the name or reference in **Add a complementary product**, then choose the product or combination in the list. Arrow keys and Enter also work.
2. Enter the **Consumption** per measurement unit of the calculation: per m² for tiles, paint and wallpaper, per m³ for volume, per metre for linear.
3. Enter the **Content of one unit** of the complementary product, in the same unit as the consumption.
4. Save the calculator settings.

The quantity offered is the net area, volume or length entered by the customer, multiplied by the consumption, divided by the content of one unit and rounded up. Example: an adhesive used at 5 kg per m² and sold in 25 kg bags is set with 5 and 25; for 14.7 m², the customer is offered 3 bags. To allow for losses, include them in the consumption.

On the shop side, the products appear under the result, ticked by default, with their quantity, price and total. The **Add the ticked items to cart** button adds them in one go. An out-of-stock product, when out-of-stock orders are not allowed, is greyed out and unticked. Inactive products or products not available for order are not shown.

## Quantity discounts and stock

The estimated price applies the quantity discounts set in PrestaShop for the selected combination, with the note “Quantity discount included”. Cart rules and shipping costs are not included.

If stock management is enabled and the calculated quantity exceeds the available stock, the customer sees the remaining stock. When out-of-stock orders are not allowed, the add to cart button is hidden and only the **Use this quantity** link remains. When they are allowed, the customer is told that the rest will ship when back in stock. The pack size combination never offers more than the available stock of a size and respects the minimum order quantity of each combination.

## Statistics

The module page shows a **Results of the calculator** block, over the last 30 days and since installation: carts with a product added from the calculator, validated orders from these carts, conversion rate and revenue excluding tax of calculated and complementary products, converted to the default currency. A table lists the five products that generated the most revenue.

Only products added with the calculator buttons are counted, and the **Save the calculation with the cart line** option must be enabled for data to be collected.

## Module settings

### Display

- **Position on the product page**: below the add to cart button (`displayProductAdditionalInfo` hook), next to the product actions (`displayProductActions`) or custom hook.
- **Accent colour**: colour of the buttons, margin choices and result.
- **Price per m², litre, metre or m³**: shows “i.e. €22.85 / m²” under the price, on the product page and in product lists.
- **Save the calculation with the cart line**: keeps the customer's measurements for the cart and the back office order page.
- **Show the calculator folded**: the product page shows a “Calculate the quantity I need” button that opens the calculator. It opens by itself when the customer already entered measurements, for example on a calculator page.
- **Door area subtracted** and **Window area subtracted** in m².

### Waste margins

For each calculation type, enter the choices offered to the customer, as percentages separated by commas (for example `5,10,15`), and the preselected margin. Installed values: tiles 5, 10 and 15% (10 by default), paint 0 to 15% (10), wallpaper 0 to 10% (5), volume 0 to 10% (5), skirting boards 5 to 15% (10).

### Custom hook

To place the calculator elsewhere on the product page, choose the “Custom hook” position and add this line to the product template of your theme:

```
{hook h='displayDfSurfaceCalculator' product=$product}
```

## SEO calculator pages

Each calculation type can have its own public page, containing the calculator, your products of the same type with the quantity and price calculated for the visitor's measurements, an explanation of the method and links to the other calculators. Addresses follow the pattern `/calculator/tiles-flooring`, `/calculator/paint`, `/calculator/wallpaper`. The list of published pages and their links appears at the top of the module page.

- **Enable the calculator pages** and **Pages to publish**: only publish the types that match your catalogue.
- **URL prefix**: shared by all languages, set on installation from the default language of the shop.
- **Products listed per page**: 12 by default, 0 hides the list.
- For each page and each language: **Friendly URL**, **Title** (H1 and title tag), **Meta description** and **Introduction text**. Titles and addresses written for common searches are prefilled in 8 languages.

The pages declare a canonical, hreflang tags for the active languages and a breadcrumb. They are added automatically to the sitemap of the PrestaShop **gsitemap** module at its next generation. The address of another language redirects with a 301 to the one of the displayed language. If you change a friendly URL, the old address is no longer served: set up a redirect if the page was already indexed.

The introduction text is a good place for your installation tips and the words your customers use. Avoid copying the explanation of the method word for word, as it is already displayed under the calculator.

## What the customer sees

The customer enters one or several rooms, walls or areas. Each block shows its subtotal. From the second area onwards, the **Subtract this zone** box removes an island, a bay or a cupboard. They then choose the margin among your values.

The result shows the area or volume, the need including the margin, the number of units, the total covered with the spare, and the estimated price. The **Add 12 boxes to cart** button fills in the quantity field and triggers the theme's add to cart button. The **Use this quantity** link only fills in the field. If the product is out of stock, only this link is offered.

A non-numeric value is outlined in red and blocks the result. A very large value, for example 120 m for a room length, shows a reminder of the expected unit. Measurements are kept for the session, so visitors find them again between the calculator page and the product page.

## Cart and orders

When the customer adds to cart from the calculator, their measurements are saved with the cart line. The cart shows a summary under the product, for example “Surface 14.7 m² + 10% = 16.17 m². Calculated: 12 boxes”, and flags if the quantity was changed afterwards. In the back office, the order page shows a **Quantity calculations** block with the same information.

## Troubleshooting

### The calculator does not appear on the product page

Check in the configured products list that the product is active and that its status is not **Incomplete**. Then check that the hook of the chosen position exists in your theme; if in doubt, try the other position or the custom hook. Clear the shop cache after any change.

### The message “Packaging information is missing for this option”

The selected combination has no content, and neither does the product. Enter the product value, or the combination value in the values per combination table.

### The calculator page returns a 404 error

Check that the pages are enabled and that the type is ticked in **Pages to publish**. If friendly URLs are disabled in the shop, the page remains available at its long address, shown at the top of the module page.

### The pack size mix is not shown

The option must be ticked, at least two combinations must have a content and a price, and the mix is only offered when it costs less than the selected size.

### The price per m² does not appear in product lists

It is displayed through the `displayProductPriceBlock` hook of type `unit_price`, which some themes do not call in product miniatures. Add the call to the miniature template or disable the option.

## Compatibility

- PrestaShop 8.0 to 9.x, the same ZIP covers both branches.
- Multistore and multilingual.
- ModuleAdminController architecture, no Composer dependency.
- Interface and calculator texts available in French, English, Spanish, German, Italian, Dutch, Polish and Portuguese.