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 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.

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.
• 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.

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.