Getting started
This chapter explains how the designer gets into your storefront and what your theme must provide for it to work.
How the bundle reaches your store
You don't add a script tag yourself. The FPD Shopify app injects everything through its theme app extension:
- The app embed (enabled under Theme editor → App embeds) injects the storefront bundle (
fpd-fe-shopify-v2.js), thewindow.FPDconfiguration object, and — on product pages — a JSON script tag#ProductJson-FPDwith the Shopify product data. - App blocks (added per section in the theme editor) render the external designer modules (image upload, texts, layouts, …) as web components.
The bundle activates only when window.FPD and window.Shopify exist; on non-FPD pages it stays passive.
Minimum theme requirements
The frontend finds your theme's elements through configurable selectors ("theme abstraction", see Configuration). Sensible selectors are auto-detected for common themes; a custom theme should verify these anchors exist:
| Element | Default selector | Needed for |
|---|---|---|
| Designer container | #fpd | Where the designer mounts |
| Add-to-cart form | form[action='/cart/add'] | Attaching design data to the cart line |
| Add-to-cart button | button[type='submit'] (within the form) | Intercepting the add |
| Product JSON | <script id="ProductJson-FPD" type="application/json"> | Injected by the app embed — don't remove it |
| Cart line rows + images | see Cart page | Thumbnail replacement and edit links |
Quick check in the browser console on a product page:
FPD.func.fpdDebug(); // highlights every resolved selector on the page
If a highlighted element is missing or wrong, override the selector (shop option or inline FPD.ta) rather than renaming your theme's markup.
Optional theme anchors
Add these elements where you want the corresponding feature to appear:
| Anchor | Feature |
|---|---|
<button id="fpd-open-designer-button"> | Builds the designer (button mode, both viewports) and removes itself. If missing, a button is auto-created inside the designer container. The frontend adds the class is-ready handling via the fpd-enabled body class — see below. |
<button id="fpd-customize-button"> | Opens the modal designer (button mode below 768px, and customize/advanced mode). In button mode it never triggers the load — it only opens the designer once #fpd-open-designer-button has built it, so keep it hidden until then (see fpd-button-mode-hidden below). If the theme has none, one is auto-created next to the add-to-cart button at that point, copying its classes. Selector configurable via shopify_ta_product_page_customize_button. |
<div id="fpd-bulk-order-container"> | Activates the bulk order form (multi-variant quantity table) in this container. |
<div id="fpd-3d-preview-placeholder"> | Mounts the 3D preview at this position. |
<div id="fpd-color-selection-placement"> | Mounts the color selection UI here (with the corresponding plugin option). |
External modules in sections
The designer modules are added as app blocks in the theme editor. Under the hood each block renders a custom element with a JSON data-config attribute — you can also place them directly in custom_liquid:
<fpd-add-elements-module
data-config='{"language":"de","designsCategoryLayout":"rows","designsImagesPerRow":4}'>
</fpd-add-elements-module>
Available elements: fpd-images-module, fpd-texts-module, fpd-layouts-module, fpd-products-module, fpd-designs-module, fpd-add-elements-module, fpd-info-popover, fpd-share-button. Details and config keys per module: Product page.
The modules are inert until the designer instance exists; in the theme editor (design mode) they render a static preview instead of live-connecting.
Body classes to build on
The frontend toggles classes on <body> that your CSS/JS can key off:
| Class | Meaning |
|---|---|
fpd-enabled | The frontend finished initializing on this page. Use this to un-hide or enable your "customize" button. |
fpd-designer-active | The designer is currently open/active. |
fpd-overflow-hidden | Scroll lock while the designer overlays the page. |
A typical pattern for the open button:
#fpd-open-designer-button { opacity: .5; pointer-events: none; }
body.fpd-enabled #fpd-open-designer-button { opacity: 1; pointer-events: auto; }
Additionally, elements with the class fpd-button-mode-hidden are hidden while the designer runs in button mode — useful for hiding the module cards that are only relevant inside the designer flow.
Verifying an integration
- Open a designable product page with
?debugappended to the URL — the console shows option loading, selector resolution, and translation lookups. - Run
FPD.func.fpdDebug()and confirm form, button, and container are found. - Customize the product, add it to the cart, and check the line item contains the
_fpd*properties (reference). - On the cart page, confirm the thumbnail shows the customized preview and the edit link reopens the design.