Extension System¶

Transform your e-commerce experience with Badger Commerce's powerful extension system. Add new features, customize your storefront, and create unique customer experiences—all without modifying core platform code.

What Are Extensions?¶

Extensions are self-contained modules that add functionality to your store. Think of them as apps for your e-commerce platform. Whether you need seasonal effects, social proof, advanced search, or payment integrations, extensions let you compose the perfect experience for your customers.

Why Extensions?¶

🚀 Fast Deployment Add new features in minutes, not weeks. No core platform changes required.

🎨 Customization Without Code Changes Business users can configure extensions through an intuitive admin interface.

🔄 Theme-Agnostic Extensions work across all themes—Nova, Bootstrap, Hardware, Wedding, and custom themes.

📊 Data-Driven Built-in analytics show how extensions impact conversion and engagement.

🔌 Mix and Match Combine multiple extensions to create unique customer experiences.

Real-World Extension Examples¶

🎄 Christmas Mode¶

Add festive magic to your store during the holidays: - Falling snowflakes with realistic physics - Snow accumulation on product cards - Subtle festive color accents - User-controlled disable option

Perfect for: Seasonal campaigns, holiday shopping experiences, brand personality

🔥 Trending Products¶

Show customers what's hot right now: - Real-time tracking of popular products - Configurable time windows (last 24h, 7 days, etc.) - Automatic updates based on user behavior - Placement anywhere on the site

Perfect for: Social proof, discovery, cross-selling

🎠 Interactive Carousels¶

Showcase your best content with rich media carousels: - High-quality image and video support - Auto-play with configurable timing - Mobile-optimized touch gestures - Call-to-action overlays

Perfect for: Hero sections, featured collections, storytelling

💳 Apple Pay¶

Enable frictionless checkout: - One-click purchasing - Secure tokenized payments - Express checkout from product pages - Cart and checkout integration

Perfect for: Mobile conversion, premium customers, impulse purchases

🔍 Algolia Search¶

Supercharge product discovery: - Instant search results - Typo tolerance - Faceted filtering - Personalized ranking

Perfect for: Large catalogs, complex product hierarchies, power users

Extension Categories¶

📦 Product & Catalog¶

Enhance how customers discover and view products: - Product Galleries: Interactive image viewers with zoom and 360° views - Quick View: Modal product previews without page navigation - Size Guides: Interactive sizing tools and fit finders - Product Bundles: "Complete the look" suggestions - Stock Notifications: Back-in-stock alerts and waitlists

🛒 Checkout & Payments¶

Streamline the path to purchase: - Express Checkout: Apple Pay, Google Pay, PayPal - Address Validation: Real-time address verification - Gift Options: Gift wrap, messages, and delivery scheduling - Discount Displays: Smart coupon suggestions - Order Confirmations: Enhanced post-purchase communication

🎨 Content & Marketing¶

Tell your brand story: - Hero Carousels: Full-width image and video sliders - JSON Components: AI-assisted custom UI with semantic styling and data binding - HTML Fragments: Custom content areas with rich formatting - Video Embeds: YouTube, Vimeo, and native video - Testimonials: Customer reviews and social proof - Blog Integration: Editorial content alongside products

🧭 Navigation & Discovery¶

Help customers find what they need: - Mega Menus: Rich navigation with images and categories - Breadcrumbs: Clear path tracking - Collection Choosers: Visual category selection - Faceted Search: Filter by attributes, price, brand - Related Products: AI-powered recommendations

👥 Social & Engagement¶

Build community and trust: - Product Reviews: Star ratings and written feedback - Social Sharing: One-click sharing to social platforms - User Photos: Customer-generated product images - Live Chat: Real-time support integration - Wishlists: Save for later functionality

🎯 Personalization¶

Deliver tailored experiences: - Geolocation: Region-specific content and offers - User Segments: Show different content to different audiences - A/B Testing: Compare extension performance - Behavioral Targeting: Content based on browsing history - Recommendations: Personalized product suggestions

🎪 Seasonal & Special Events¶

Celebrate moments that matter: - Christmas Mode: Festive effects and theming - Valentine's Day: Romantic overlays and gift guides - Black Friday: Countdown timers and urgency indicators - Flash Sales: Limited-time offer banners - Anniversary Celebrations: Brand milestone features

How It Works¶

For Business Users¶

1. Browse Extensions Visit the extension library in your admin panel

2. Configure Settings Use the visual editor to customize behavior

3. Place Extensions Drag and drop extensions into page slots

4. Preview & Publish See changes before customers do

5. Monitor Performance Track engagement and conversion impact

For Developers¶

1. Create Extension Class Extend base classes with your logic

2. Design Templates Build Thymeleaf templates for rendering

3. Add Resources Include CSS/JS for interactivity

4. Register Extension Spring Boot auto-discovers your extension

5. Test & Deploy Use built-in testing utilities

👉 Developer Guide: See /docs/developers/building-extensions.md for detailed technical documentation

Extension Composition¶

Combine extensions to create powerful experiences:

Example: High-Converting Product Page

┌─────────────────────────────────────┐
│ [Breadcrumbs Extension]             │
├─────────────────────────────────────┤
│ [Product Gallery Extension]         │
│ + [Size Guide Extension]            │
├─────────────────────────────────────┤
│ [Product Reviews Extension]         │
├─────────────────────────────────────┤
│ [Trending Products Extension]       │
├─────────────────────────────────────┤
│ [Recently Viewed Extension]         │
└─────────────────────────────────────┘

Example: Festive Homepage

┌─────────────────────────────────────┐
│ [Christmas Mode Extension]          │ ← Global effects
├─────────────────────────────────────┤
│ [Hero Carousel Extension]           │ ← Holiday messaging
├─────────────────────────────────────┤
│ [Featured Collections Extension]    │ ← Gift guides
├─────────────────────────────────────┤
│ [Email Capture Extension]           │ ← Holiday newsletter
└─────────────────────────────────────┘

Built-In Extensions¶

Badger Commerce includes a rich library of pre-built extensions:

Product Gallery Modes¶

The Product Gallery extension renders a product's images in one of several layouts, chosen from a Gallery Mode picker in the extension's admin settings (Nova theme):

All modes share the same PhotoSwipe lightbox and support variant-aware image switching, so the gallery updates automatically when a shopper selects a different variant. New modes can be added with a single GalleryMode enum entry plus a matching Thymeleaf fragment.

Featured Product Display Modes¶

The Featured Product extension merchandises a set of products — a fixed list of SKU IDs, a named collection, or the current collection when Use Page Context is on — in one of three layouts, chosen from the Display Mode picker:

Cover Flow¶

Cover Flow is built for scrubbing rather than stepping. Cards are dragged with the mouse or a finger and carry momentum on release, so a flick crosses several products and a nudge settles back. Vertical scrolling always belongs to the page — the strip only claims a gesture that is clearly horizontal — and arrows, indicator bars and the left/right keys all still work.

Titles and prices stay legible on the cards either side of the centre, not just the middle one. Only the centre card's View Details button is live. Clicking or tapping a card off to the side brings it to the centre instead of opening it. The button stays dead while the strip is travelling, so a flick can't carry live buttons past under a finger, but it wakes up on the final approach, within a quarter of a card of rest. A tap on a card that is all but home opens it rather than being rejected. Touching the strip mid-glide catches it, and releasing without a drag lets it finish settling on the nearest card.

Two settings shape it:

• Cover Flow Looping — Auto (the default) wraps around once there are five or more products, and stops at the ends below that, where a wrapping card would have to fade out almost at the centre. Always wrap around and Never wrap force either behaviour.
• Maximum Number of Products — set to 0 to load the whole collection (capped at 250) and get a catalogue-flicking strip rather than a short highlight reel. Cover Flow only ever paints the handful of cards near the centre, so a long strip stays smooth; the indicator dots are dropped past a dozen products, where they stop being a useful position readout.

Collection Product Grid¶

A collection page's product grid (the title, sort row, sub-category links, product cards and pagination) is the collectionProductGrid extension. That means it can be moved, hidden or restyled per collection or per stereotype, from the admin extension panel or by an AI agent through the MCP manageExtensionConfig tool, like any other block.

It's opt-in. A collection page renders its long-standing built-in grid unless collectionProductGrid renders on the page, whether it's configured on the collection itself or inherited from the collection's stereotype. The built-in grid and the extension share one fragment per theme (fragment/collection-product-grid), so with default settings the page looks exactly as before. Existing sites are unchanged. New sites get the extension through the defaultCollection stereotype (initialisation/default/stereotypes.json).

Where it renders. Its default slot is productGrid, between topBanner and bottomBanner on the Nova, Brock, Bootstrap and Hardware collection templates. It can also be placed in topBanner or bottomBanner. Anywhere else it wouldn't be seen, so the built-in grid stays.

Hiding products. The collection's admin-only Hide Products checkbox still hides the grid, whether it's built in or comes from the extension. To hide the grid through extensions on one collection whose stereotype places it, add collectionProductGrid to that collection in the same slot with showProducts=false. An item-level placement replaces the stereotype's placement of the same extension in the same slot. Disabling the collection-level placement doesn't work, because a disabled placement doesn't suppress the stereotype's.

Page size, most specific first:

1. pageSize on a collectionProductGrid placed on the collection itself
2. the collection's pageSizeOverride configuration property
3. pageSize on the stereotype's collectionProductGrid
4. the site's defaultCollectionPaginationPagesSize config (default 12)

View-only by design. CollectionController still fetches, sorts and paginates the products. The extension's template only lays out the page model (products, paginationParams, sortingBean, collection, childCollections). The one setting the controller reads up front is pageSize, through ExtensionService.findEffectiveConfiguration. Sorting, pagination and the Nova and Bootstrap AJAX re-sort all behave as before, because the grid still renders inside #ajax-body. After rendering the extensions, the controller sets productGridExtensionRendered when the extension's model (marked collectionProductGrid: true) landed in one of the page's grid slots, and the templates skip their built-in grid on that flag.

Hero Background Effects¶

The hero extension (five presets: Centered, Split Image, Video Background, Gradient Overlay, Minimal) can draw an ambient animated background behind its copy, in the style of the Stripe and Accenture homepages. It is off by default, so existing heroes are unchanged. Set it from the Animated Effect picker in the hero's admin Background section, or through MCP (manageExtensionConfig) as keys in the heroConfig JSON:

{"preset": "gradient", "backgroundEffect": "constellation", "slots": {...}}

Where it draws. Gradient Overlay (light marks on the dark brand gradient), Minimal (brand-tinted marks on the light surface) and Split Image (behind the text column only). Centered and Video Background already carry a photo or video, so they ignore the setting.

How it renders. The template (nova/extensions/hero/background-effect.html, used by Brock and the other Nova-layered themes too) inserts an aria-hidden <canvas> with pointer-events: none between the background layers and the content, and loads nova/js/hero-background.js with defer only when a hero on the page uses an effect. The script is plain JavaScript with no libraries:

• Colours follow the Design Brief. It resolves --color-primary, --color-secondary, --color-accent and --color-on-dark-accent at runtime, so each tenant's palette restyles it.
• Text stays legible. Marks are drawn at low alpha, and a CSS mask fades the canvas out behind the copy (to the left on Gradient and Split Image, the centre on Minimal). The content sits above the canvas.
• Reduced motion. Under prefers-reduced-motion: reduce it draws a single still frame and never animates.
• Cheap when idle. It pauses when the hero scrolls offscreen (IntersectionObserver) or the tab is hidden, sizes the canvas for the device pixel ratio (capped at 2) with a ResizeObserver, and scales the particle count with the hero's area, capped lower on phones.

Platform Benefits¶

For Merchants¶

• Add features without developer time
• Test ideas quickly with low risk
• Seasonal campaigns made easy
• Improved conversion rates

For Developers¶

• Clean, maintainable architecture
• Reusable components
• Clear separation of concerns
• Well-documented APIs

For Customers¶

• Richer shopping experiences
• Faster page loads (lazy loading)
• Consistent cross-device experience
• Personalized content

Getting Started¶

Using Extensions¶

1. Log into your admin panel
2. Navigate to Extensions → Available Extensions
3. Click Add Extension on any page, product, or collection
4. Configure settings and save
5. Preview your changes
6. Publish when ready

Building Extensions¶

Ready to build your own extension? Check out our comprehensive developer guide:

📘 Building Extensions Guide

Learn how to: - Create extension classes - Design templates for multiple themes - Handle configuration - Add JavaScript and CSS - Test extensions - Deploy to production

Support & Resources¶

• Developer Documentation: /docs/developers/building-extensions.md
• API Reference: JavaDoc available in codebase
• Example Extensions: Browse commerce-core/src/main/java/uk/co/kedos/badger/settbuilder/extensions/
• Community Extensions: Coming soon—marketplace for sharing extensions

Next Steps: - Browse the Built-In Extensions catalog - Read the Developer Guide - Explore the Christmas Mode Tutorial