Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Added user documentation for customizing the PDP layout (#13289)

jaburghes71a056181163
diff --git a/docs/images/user/storefront/themes/pdp/1-themes-tab.png b/docs/images/user/storefront/themes/pdp/1-themes-tab.png
new file mode 100644
index 0000000000..442a414b26
Binary files /dev/null and b/docs/images/user/storefront/themes/pdp/1-themes-tab.png differ
diff --git a/docs/images/user/storefront/themes/pdp/10-reorder-metafields.png b/docs/images/user/storefront/themes/pdp/10-reorder-metafields.png
new file mode 100644
index 0000000000..11475b301e
Binary files /dev/null and b/docs/images/user/storefront/themes/pdp/10-reorder-metafields.png differ
diff --git a/docs/images/user/storefront/themes/pdp/11-preview-changes.png b/docs/images/user/storefront/themes/pdp/11-preview-changes.png
new file mode 100644
index 0000000000..e6eda31bb4
Binary files /dev/null and b/docs/images/user/storefront/themes/pdp/11-preview-changes.png differ
diff --git a/docs/images/user/storefront/themes/pdp/12-publish-changes.png b/docs/images/user/storefront/themes/pdp/12-publish-changes.png
new file mode 100644
index 0000000000..bb2151a770
Binary files /dev/null and b/docs/images/user/storefront/themes/pdp/12-publish-changes.png differ
diff --git a/docs/images/user/storefront/themes/pdp/2-open-theme-editor.png b/docs/images/user/storefront/themes/pdp/2-open-theme-editor.png
new file mode 100644
index 0000000000..f11f83d7e1
Binary files /dev/null and b/docs/images/user/storefront/themes/pdp/2-open-theme-editor.png differ
diff --git a/docs/images/user/storefront/themes/pdp/3-select-pdp.png b/docs/images/user/storefront/themes/pdp/3-select-pdp.png
new file mode 100644
index 0000000000..8bbda25cc1
Binary files /dev/null and b/docs/images/user/storefront/themes/pdp/3-select-pdp.png differ
diff --git a/docs/images/user/storefront/themes/pdp/4-pdp-preview.png b/docs/images/user/storefront/themes/pdp/4-pdp-preview.png
new file mode 100644
index 0000000000..d7d0ea0d2f
Binary files /dev/null and b/docs/images/user/storefront/themes/pdp/4-pdp-preview.png differ
diff --git a/docs/images/user/storefront/themes/pdp/5-pdp-sidebar.png b/docs/images/user/storefront/themes/pdp/5-pdp-sidebar.png
new file mode 100644
index 0000000000..694dfb5cbe
Binary files /dev/null and b/docs/images/user/storefront/themes/pdp/5-pdp-sidebar.png differ
diff --git a/docs/images/user/storefront/themes/pdp/6-pdp-reorder.png b/docs/images/user/storefront/themes/pdp/6-pdp-reorder.png
new file mode 100644
index 0000000000..5a2fdff287
Binary files /dev/null and b/docs/images/user/storefront/themes/pdp/6-pdp-reorder.png differ
diff --git a/docs/images/user/storefront/themes/pdp/7-design-settings.png b/docs/images/user/storefront/themes/pdp/7-design-settings.png
new file mode 100644
index 0000000000..0e85d1b45a
Binary files /dev/null and b/docs/images/user/storefront/themes/pdp/7-design-settings.png differ
diff --git a/docs/images/user/storefront/themes/pdp/8-add-sections.png b/docs/images/user/storefront/themes/pdp/8-add-sections.png
new file mode 100644
index 0000000000..f98ca650e7
Binary files /dev/null and b/docs/images/user/storefront/themes/pdp/8-add-sections.png differ
diff --git a/docs/images/user/storefront/themes/pdp/9-pdp-metafields.png b/docs/images/user/storefront/themes/pdp/9-pdp-metafields.png
new file mode 100644
index 0000000000..a3fb0cbda1
Binary files /dev/null and b/docs/images/user/storefront/themes/pdp/9-pdp-metafields.png differ
diff --git a/docs/user/storefront/product-details-page.mdx b/docs/user/storefront/product-details-page.mdx
new file mode 100644
index 0000000000..b2969e6cfc
--- /dev/null
+++ b/docs/user/storefront/product-details-page.mdx
@@ -0,0 +1,138 @@
+---
+title: "Product Details Page"
+description: "Learn how to customize the Product Details Page in Spree Commerce."
+---
+
+A well-designed Product Details Page (PDP) plays an essential role in helping customers understand your products and complete their purchase with confidence. 
+
+Spree gives you full visual control over how product information is presented by adding a flexible drag-and-drop layout editor, enhanced metafield management, and complete control over the visibility and order of core product elements - all without writing a single line of code.
+
+This guide shows you how to customize the PDP using the Spree theme editor.
+
+## Access the PDP Editor
+
+To begin customizing the Product Details Page, first navigate to **Storefront → Themes**.
+
+![Themes dashboard in Spree Commerce](/docs/images/user/storefront/themes/pdp/1-themes-tab.png)
+
+Open your active theme (i.e., the one marked Live).
+
+![The Spree Commerce theme editor](/docs/images/user/storefront/themes/pdp/2-open-theme-editor.png)
+
+In the page selector (top left), choose **Product Details Page**.
+
+![Customize the product details page in Spree](/docs/images/user/storefront/themes/pdp/3-select-pdp.png)
+
+The editor preview and sidebar will update to show all PDP-specific sections and settings.
+
+![Spree Theme editor PDP preview](/docs/images/user/storefront/themes/pdp/4-pdp-preview.png)
+
+<Warning>Remember to click Publish after making changes. Navigating away from the editor without publishing will discard all changes.</Warning>
+
+## Edit the PDP Layout
+
+The PDP layout can be controlled entirely through the sidebar, where each element is displayed as its own draggable block.
+
+![Drag and drop PDP elements in Spree](/docs/images/user/storefront/themes/pdp/5-pdp-sidebar.png)
+
+From here, you can customize the PDP in a number of ways:
+
+### Reorder Elements
+
+![Reordering PDP elements via drag and drop in Spree](/docs/images/user/storefront/themes/pdp/6-pdp-reorder.png)
+
+To change the order in which product information appears:
+
+1. Locate the PDP element list in the sidebar
+2. Click and hold the handle icon next to an element
+3. Drag it to its new position
+4. Release to drop it in place
+
+This allows you to design layouts such as:
+
+- Price at the top for conversion-focused layouts
+- Brand name above product title
+- Description above the variant selector
+- Metafields grouped under Add to Cart
+
+The editor preview updates instantly so you can see your changes immediately.
+
+<Note>Some merchants prefer a shorter “buy box” on mobile. Use the mobile preview toggle to optimize the PDP for smaller screens.</Note>
+
+### Modify Design Settings
+
+![Modifying PDP design settings in Spree](/docs/images/user/storefront/themes/pdp/7-design-settings.png)
+
+Clicking any PDP element opens up its settings, which may include:
+
+- Padding
+- Alignment
+- Borders
+- Color adjustments (if not overridden by global settings)
+
+These settings vary depending on the selected block, similar to other pages in the theme editor.
+
+Just like other customizable pages in the theme editor, you can insert page sections above or below the PDP’s main content area.
+
+### Add/Remove Page Sections
+
+![Adding page sections to the PDP in Spree](/docs/images/user/storefront/themes/pdp/8-add-sections.png)
+
+To add more page sections, click **Add Section** in the sidebar, and choose from the list of available page sections (such as Image Banner, Featured Taxon, etc.).
+
+The section will be added to the PDP layout, where you can edit and rearrange it like any other section.
+
+These sections allow you to enrich the PDP with supplementary content, such as promotional banners, brand messaging, or custom visuals.
+
+## Manage Product Metafields
+
+The Metafields block is fully configurable and can display any additional product data you’ve added - such as ingredients, materials, certifications, allergens, origin, care instructions, and more.
+
+### Show or Hide Metafields
+
+![Displaying metafields on PDP in Spree Commerce](/docs/images/user/storefront/themes/pdp/9-pdp-metafields.png)
+
+Each metafield appears in the sidebar with a simple checkbox:
+
+- **Checked** - metafield is visible on the PDP
+- **Unchecked** - metafield is hidden from the PDP
+
+This allows you to display only the information that matters most for each store.
+
+### Reorder Metafields
+
+![Reordering metafields on the PDP in Spree Commerce](/docs/images/user/storefront/themes/pdp/10-reorder-metafields.png)
+
+Metafields can also be rearranged via drag-and-drop:
+
+1. Go to the Metafields block inside the PDP editor
+2. Use the handle icon next to a metafield to drag it up or down
+3. Drop it into your preferred order
+
+This is especially useful for merchants with many metafields, allowing them to highlight the most important information first.
+
+<Note>If you have not created any product metafields, then this section will appear blank. Please refer to our [<u>Metafields</u>](https://spreecommerce.org/docs/user/settings/metafields) support article to learn more.</Note>
+
+## Preview Your Changes
+
+![Mobile preview of the PDP in Spree Commerce](/docs/images/user/storefront/themes/pdp/11-preview-changes.png)
+
+Use the controls in the top toolbar to view your PDP as customers would see it:
+
+- **Mobile View** - preview the mobile layout
+- **Desktop View** - preview the full PDP as shown on desktop
+- **Preview Mode** - open a live preview outside of the editor
+
+This ensures your PDP looks consistent and polished across all devices.
+
+## Publish Your Changes
+
+![Publishing chnages to a live storefront in Spree Commerce](/docs/images/user/storefront/themes/pdp/12-publish-changes.png)
+
+Once your PDP layout is ready:
+
+- Click **Publish** in the top right corner
+- Your changes go live immediately
+- Revisit the editor at any time to adjust the layout or metafields
+
+<Note>If you feel like you’ve made a complete mess of the layout, and would like to revert it back to its original configuration, simply exit the theme editor without clicking Publish and your changes will be discarded.</Note>