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.
• Showcase product in the catalog: enables the showcase product generated for every pack (listings, search, sitemap).
• Showcase price basis: tax included for a B2C shop, tax excluded for a shop displaying prices without tax.
• Pack recap on the invoice PDF: block appended at the end of the invoice, the only spot PrestaShop exposes.
• Pack recap on order confirmation and order history.
• Combination selector on the pack page: like the product page (one selector per attribute: dropdown, color swatches or buttons, according to the type of each attribute group), one dropdown listing every combination, or clickable image thumbnails. In every mode, picking a combination switches the product photo to the image bound to it, and if the default variant of a free choice component is sold out, the page opens on a combination in stock.
• Pack page display: dedicated pack page, or product page of the shop. See the section “Displaying the pack as a product page”.
• Pack in the cart: one line per product, or one line for the pack. See the section “One single line for the pack in the cart”.

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 pack editor

The form is organized in six steps: information (name, reference, badge, visibility, friendly URL, validity period), products, price, images, description and catalog. The language selector at the top of steps 1 and 5 switches every translated field. On the right, the summary updates on every change: price of the products bought separately, discount, pack price tax included and excluded, and VAT breakdown per rate as it will appear on the invoice.

Images are added by drag and drop or by click. Drag the thumbnails to change their order: the first one becomes the cover. The category tree of step 6 decides where the pack appears in the catalog, the first checked category becoming its default category.

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.

The invoice shows the price without pack (catalog promotions included) and the pack unit price per line, plus a Pack details block at the end of the invoice: total without pack, discount as an amount and a percentage, pack total. The same recap appears on the confirmation page and in the customer order history. Each order detail in the back office shows a summary of the ordered packs. The pack list shows a per pack sales counter.

The showcase product in the catalog

Every pack generates an automatically synced showcase product: a real catalog product with no tax rule, referenced DFPACK followed by the pack id. It appears in category listings, native search, faceted filters and the sitemap, with the pack gallery, the native crossed out total and promo badge. Its displayed stock follows the computed pack availability.

Depending on the “Pack page display” setting, the showcase page redirects with a 301 to the pack page, or itself displays the pack as a product page. Depending on the “Pack in the cart” setting, a cart line referencing it is converted into product lines, each with its own VAT rate, or becomes one single pack line with its contents. It is resynced on every pack save, on every change or stock movement of a component product and after every order.

Importing native PrestaShop packs

The Import PrestaShop packs button in the pack list converts your native packs: components with combinations and quantities, categories, images and price carried over (fixed price mode). The native pack product is deactivated after import so it does not compete with the showcase; reactivate it in the catalog if needed. The PSPACK reference keeps track of the origin: running the import again never imports the same pack twice. Packs nested inside other packs are ignored.

Displaying the pack as a product page

With the “Pack page display” setting on “Product page of the shop”, the pack is shown on the page of its showcase product, built by your theme like every other product: gallery, breadcrumb, price, quantity, add to cart button, tabs, reviews. The “This pack contains” block sits above the quantity, with the products, their combination selectors, the optional products and the savings.

When the customer changes a combination, the theme price, crossed out price and discount percentage update. The theme add to cart button adds the pack with the customer selection, and the quantity field sets the number of packs. Links to the pack (cross-sell block, /packs page, cart badge) point to this page, and the former /pack/ addresses redirect to it with a 301.

One single line for the pack in the cart

With the “Pack in the cart” setting on “One line for the pack”, the pack enters the cart as one single line, under the pack name, with its contents listed below: “1 x T-shirt (Size: S, Color: White)”. Two different selections give two lines, the same pack added twice with the same selection increases the line quantity.

The line price is the sum of the product prices, computed with the VAT rate of each one: the tax excluded, tax included and VAT totals of the cart and the order are exact. On the invoice, the pack line shows its base price and discount, and the VAT is broken down per rate. The pack contents also appear at checkout, in the order detail, the emails and the invoice, and the “Packs in this order” card of the back office lists the products and combinations to pick.

The stock of each product is decremented on order, given back if the order moves to “Canceled” or “Payment error”, and taken again if it is reactivated.

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.