Product packs & bundles: documentation

Installation

The module installs like any PrestaShop module, through the back office or by FTP.

1. From Modules then Module Manager, click Upload a module and drop the dfpackpro.zip file.
2. By FTP, extract the archive into your store’s /modules/ folder, then install DataFirefly – Packs & Bundles from the module manager.
3. Clear the cache in Advanced Parameters then Performance.

Installation creates six tables prefixed ps_dfpackpro, registers the required hooks and adds the Packs & Bundles (DF) tab under the Catalog menu.

General settings

The Configure button of the module page opens the settings applied to all packs.

• Block position on product pages: under the buy block, at the bottom of the page, or both. The block lists the packs containing the viewed product.
• Packs block enabled: turns the cross-sell display off without uninstalling. Pack pages stay reachable.
• Maximum packs displayed: 3 by default.
• Pack sorting: position, creation date, or random.
• Show unit prices: details each component’s price on the pack page.
• Show savings: badge and saved amount, on the product page block and the pack page.
• Show availability: pack stock state, computed from the components’ stock.
• Strict cart mode: if the customer removes a component, the whole pack and its discount are removed. Disabled, the removal is accepted and the discount kept on the rest.
• After add to cart: redirect to the cart, or confirm in place.
• Accent color: color of the module’s badges, buttons and block borders.

Creating a pack

Open Catalog then Packs & Bundles (DF), and click New pack.

Pack information

• Name: translated field, shown on the product page block, the pack page and the cart badge.
• URL alias: generated automatically from the name when left empty. It builds the pack page address.
• Description: translated rich text, shown on the pack page.
• Badge: short translated text, shown on the cross-sell cards. Leave empty to display the savings percentage.
• Pricing mode: the four modes described below. The form hides irrelevant fields according to the chosen mode.
• Inherit existing promotions: enabled, current catalog discounts are the starting price for the pack computation.
• Validity dates: leave empty for a permanent pack. Outside the period, the pack disappears from the front office.
• Active: equivalent to the activation toggle in the list.

Components

The Components panel manages the pack content.

• Product search: type at least two characters. The search covers name, reference and ID. Click a result to add it.
• Combination: for a product with combinations, the selector lists the variants with their price. The chosen variant becomes the default.
• Customer combination choice: enabled, the customer picks their variant on the pack page and in the product page block. Disabled, the variant is locked.
• Quantity: number of units of the component in the pack. A pack can contain a single product in quantity, for a multi-unit deal.
• Editable quantity: the customer can adjust this component’s quantity on the pack page.
• Optional: the customer can untick this component, the price recalculates.
• Per product discount: percentage or amount, visible only in the Per product discount mode. A 100 percent discount makes the component free.
• Order: up and down arrows to order the display.

The price simulator under the table recomputes the total price, the pack price and the savings live at every change.

The four pricing modes

No discount

The pack sells the components at their current price. Useful for a pure convenience pack, or to promote the composition alone.

Global percentage discount

The percentage applies to each component’s price. A pack at 15 percent off discounts every line by 15 percent.

Per product discount

Each component carries its own discount, as a percentage or an amount. This is the mode for machine plus free consumable deals: the machine at 0 percent, the consumable at 100 percent.

Fixed price

You announce the pack price, tax included in the default currency. The gap between the sum of current prices and the announced price is spread proportionally across each line, tax excluded. Each product keeps its VAT rate.

Example: a 49 pack made of product A at 40 tax incl. and product B at 30 tax incl. The current sum is 70, the discount 21. A carries 12 of discount, B 9, in proportion to their weight in the total. The invoice stays exact even if A is at 20 percent VAT and B at 5.5 percent.

The block on product pages

Every product belonging to a pack displays a “this product is also available in a pack” block. Each card shows the component thumbnails, the pack name, the crossed out total, the pack price, the savings badge and the stock state.

• View the pack opens the pack page.
• Add directly adds the pack to the cart in its default configuration. The button becomes Configure when the pack contains choices: free combination, optional component or editable quantity.

The block position, the number of cards and their sorting are set in the module configuration.

The pack page

Every pack has its page at /pack/12-my-alias, with the pack ID and the alias of the current language. The page lists the components with their combination selectors, the optional product checkboxes and the quantity fields when opened.

Every change recomputes the total price, the pack price, the savings and the availability in Ajax, without reloading the page. The add button sends the current selection to the cart.

Availability is computed from real stock: the pack is sellable when every required component is available in the requested quantity, taking each product’s out of stock ordering permissions into account.

The cart

On pack add, every component becomes a real cart line, invoiced at its pack price through a specific price scoped to that cart. No ghost product is created.

Pack badge

Every line belonging to a pack shows a badge with the pack name, a link to its page and a Remove the whole pack button. The removal deletes all the pack lines and their discounts in one action.

Extra quantities

The pack price only covers the pack quantities. If the customer raises a line quantity, the module applies a weighted average unit price: pack quantity at the pack price, surplus at the regular price.

Example: a 2 unit pack at 8 against a regular price of 10. The customer moves the line to 5 units. The unit price becomes (2 x 8 + 3 x 10) / 5 = 9.20, a 46 total. The discount stays capped to the 2 pack units.

Strict mode

Enabled, deleting a component removes the whole pack and its discount. This prevents keeping the discount while returning part of the bundle. Disabled, the removal is accepted and the discount kept on the remaining lines.

Orders and accounting

Every pack product lands on its own order line, at its pack price. Invoices, delivery slips, credit slips and partial returns work natively, item by item. Your accounting and ERP exports only see real references from your catalog.

Each order detail in the back office shows a summary of the ordered packs. The pack list shows a per pack sales counter.

Multistore and multilingual

Every pack is associated with the stores of its creation context and can be managed store by store. The Name, URL alias, Description and Badge fields are translated in the installed languages. The front office follows the customer’s language, including in the pack page alias.

Adapting the display to your theme

Three templates can be overridden. Copy them from /modules/dfpackpro/views/templates/ to /themes/your-theme/modules/dfpackpro/views/templates/ keeping the subfolders.

• hook/product_packs.tpl: the cross-sell block on product pages
• front/pack.tpl: the pack page
• hook/cart_line_badge.tpl: the pack badge in the cart

CSS is isolated under the dfpackpro prefix and the accent color is carried by the --dfpackpro-accent CSS variable. For a small adjustment, target the classes from your theme stylesheet rather than editing views/css/front.css, which would be overwritten on update.

Troubleshooting

The block does not show on the product page

1. Check that the pack is active and that today falls within the validity period.
2. Check that the viewed product is actually part of the pack components.
3. Check the Packs block enabled setting and the chosen position in the configuration.
4. Clear the Smarty cache and your server cache.

The pack shows as unavailable

Availability is the minimum of the required components’ stock divided by their quantity in the pack. A single out of stock component without out of stock ordering permission is enough to make the pack unavailable. Unticked optional components do not count.

The cart badge shows in the wrong place

The badge is rendered in the actions column by the theme, then moved by JavaScript into the product information block. On a heavily customized theme without the standard containers, the badge stays displayed at its original position. Override cart_line_badge.tpl to fit your structure.

The pack price applies to too many units

This case is covered by the weighted average price: check the unit price displayed on the line, it must sit between the pack price and the regular price as soon as the quantity exceeds the pack. If it does not, clear the cache and change the quantity to trigger a recomputation.

The pack page returns a 404

Check that the pack is active and within its validity period. After an alias change, the old address redirects with a 301 to the new one as long as the pack ID is correct.

Uninstalling

Uninstalling removes the module’s six tables, its configuration keys and the Catalog menu tab. Past orders keep their lines and prices, your accounting history is not altered.