أدلة المطورين باللغة الإنجليزية.

Building a storefront template by hand

Welcome

This guide explains how to build a template for the store by hand — with any text editor, no tools to install. A template is a small folder of files; you zip it and send it to the store owner, who installs it.

You writeThe store does
index.html — the page layout and textfills in the store's data (products, cart, checkout, account…) using the element ids and classes described in this guide
styles.css — the lookadds shared styles, fonts and your brand colours before it
script.js (optional) — small extrasruns it before the storefront engine
template.json — settings: colours, fonts, texts, bannersturns them into CSS variables and page content
image/ — your picturesserves them at /image/…
Products, prices, stores, the cart and checkout are not written in your template: the store loads them into the elements you provide. Your job is the layout, the words and the look.

Rules in this guide come from the store's own code (love-ecommerce-template 1.0.0) and its 15 installed templates.

Quick start

  1. Download a starter and unzip it:
  2. Rename the folder from my-template to your template's name — letters, digits, - and _ only (e.g. sunny-market). Put the same name in theme.json → slug.
  3. Edit the files: text and layout in index.html, look in styles.css, colours and fonts in template.json, pictures in image/.
  4. Check your work with the checklist.
  5. Zip and send: zip the folder itself (the zip must contain one folder with your files inside) and send it to the store owner. See Delivering your template.
You can open index.html directly in a browser to look at the layout, but it will be unstyled and empty of products: placeholders like {WEBSITENAME} and the shop data only appear once the store runs the template. Ask the store owner for a test install to see it working.

The template folder

Folder layout
my-template/
├── index.html        required — the page
├── template.json     required — settings
├── styles.css        the stylesheet (or style.css)
├── script.js         optional
├── theme.json        optional — name and version
└── image/            optional — pictures (sub-folders allowed)
    ├── logo.svg
    └── banners/hero.jpg
  • Folder name: ^[a-zA-Z0-9_-]{1,64}$ — letters, digits, hyphen and underscore, up to 64 characters.
  • The store reads only files directly in the folder (.html, .css, .js) plus image/. Any other file in the template folder (for example logo.png at the top level) is not served by the application.
FileRequiredWhat it is
template.jsonyesConfiguration. A folder without a readable template.json is skipped by the loader ("Error loading template").
index.htmlyesThe page markup rendered by the template engine. The loader accepts a template without it but logs "will render empty" and the storefront has no content.
styles.css or style.cssnoTemplate stylesheet, served sanitized at /templates/<name>/styles.css and linked after the shared styles. style.css is accepted as an alternative name (styles.css wins on /styles.css, style.css wins on /style.css; the page links /style.css).
script.jsnoTemplate script, served sanitized at /templates/<name>/script.js and loaded (deferred) BEFORE the shared engine, so it can define window.StorefrontTheme.
theme.jsonnoOptional installation metadata (id, slug, name, version, previewImage) used to match the store's configured theme to this folder.
image/noImages served at /image/<path> for the ACTIVE template (sub-folders allowed).

How the store builds the page

  1. render — index.html is rendered by TemplateEngine.render() with the placeholder data (see Data).
  2. strip-document — <!DOCTYPE>, <html>, <head>…</head> and <body> tags are removed: your markup becomes the body content of a page the application builds.
  3. sanitize-html — sanitizeHtml(): removes script, iframe, object, embed, base, applet, frame, frameset, meta, link, style elements, every on* event attribute, javascript:/vbscript:/data:text/html URLs, cross-origin form actions, srcdoc and style attributes with external url().
  4. image-urls — <img src> values are normalised: image/x → /image/x, external URLs → /img-proxy?url=…
  5. wrap — The application adds the <head> (approved CDN CSS, fonts, core.css, kit.css when enabled, branding tokens, your stylesheet, approved CDN scripts) and the closing scripts (your script.js, then engine.js, then the config JSON).

So: write index.html as the content of the body only. Anything in a <head> is thrown away, and these elements are removed wherever they are: <script> <iframe> <object> <embed> <base> <applet> <frame> <frameset> <meta> <link> <style>. Also removed: every on…="…" attribute (onclick, onload…), javascript: links, forms posting to other sites, and inline styles that load images from other sites.

Files load in this order: approved CDN scripts (deferred) → templates/<name>/script.js (deferred) → /assets/storefront/engine.js (deferred) → <script id="love-config-json" type="application/json"> config. Libraries already on the page: jQuery 3.7.1 ($), SweetAlert2 11 (Swal), Font Awesome 6.4 (CSS), Bootstrap 5.3.2 (CSS only) — don't add your own copies.

The page has a strict security policy: scripts, styles, fonts and images from other websites are blocked (except the store's approved CDN files). Put everything your template needs inside the template folder.

Placeholders

Write a placeholder in braces and the store replaces it with its value: <h1>{WEBSITENAME}</h1>. Values are HTML-escaped; {{{NAME}}} inserts the raw value (still cleaned afterwards). An unknown name is left on the page as typed, so typos are visible.

PlaceholderValue
{WEBSITENAME}Store name (or the host name when the store has none).
{STORE_NAME}Store name from the store record.
{DESCRIPTION}Store description, else template.json website.description.
{THEME}Name of the active template folder.
{CURRENCY}Store currency code (e.g. NGN).
{CURRENCY_SYMBOL}Store currency symbol.
{USER_JSON}JSON of the signed-in customer (or null).
{DAYS_ONLINE}Days since the store record was created.
{TEMPLATE_IMAGES}Array of { name, url } for the files directly inside image/. Use with FOREACH. (array)
{STORE_ADDRESS} storeSelected store's address line (empty when no store is selected).
{STORE_CITY} storeSelected store's city.
{STORE_STATE} storeSelected store's state.
{STORE_PHONE} storeSelected store's phone.
{STORE_PHONE_LINK} storePhone digits for tel: links.
{STORE_EMAIL} storeSelected store's email.
{STORE_HOURS} storeOpening hours joined with " · ".
{STORE_HOURS_STATUS} store"Open now" / "Closed now · opens …".
{USER}Signed-in customer object { id, username, name, email, role } or null (use in IF). (object)
{MENU_ITEMS}Menu items for the signed-in customer ([] when signed out). (array)
{PRODUCTS}Always [] — catalogue data is loaded in the browser through the store-scoped APIs. (array)
{TESTIMONIALS}Always [] (kept for compatibility; use content.testimonials). (array)
{YEAR}Current year.
{FEATURED_PRODUCTS}Always [] (kept for compatibility). (array)
{CATEGORIES}Always [] (kept for compatibility). (array)
{SOCIAL_LINKS}Always [] (kept for compatibility; use template.json social). (array)
{RECENT_PRODUCTS}Always [] (kept for compatibility). (array)

store values belong to the store the shopper has chosen and are empty until a store is chosen (and always empty in a shop without branches). Wrap them so nothing is shown empty:

index.html
<!-- IF STORE_PHONE -->
<a href="tel:{STORE_PHONE_LINK}">{STORE_PHONE}</a>
<!-- ENDIF -->

Inside a list block: {ITEM} (FOREACH), {INDEX} (FOREACH), {EVEN_ODD} (FOREACH), {LOOP_INDEX} (LOOP).

Conditions and repeats

WriteMeaning
<!-- IF PATH -->…<!-- ELSE -->…<!-- ENDIF -->Renders the first branch when PATH is truthy (arrays: non-empty). Comparisons: ==, ===, !=, !==, >, >=, <, <= against a data path, number, true/false/null or quoted string.
<!-- FOREACH LIST -->…<!-- ENDFOREACH -->Repeats the body for each item of an array; inside, {ITEM.x}, {INDEX} (1-based) and {EVEN_ODD} are available.
<!-- LOOP n -->…<!-- ENDLOOP -->Repeats the body n times; {LOOP_INDEX} and {INDEX_MOD_k} are available.
<!-- COUNT LIST -->, <!-- COUNT LIST WITH prop -->, <!-- COUNT LIST WITH prop == value -->Prints a count.
<!-- AVG LIST prop -->Prints the average of a numeric property (2 decimals).
Blocks must be balanced (IF/ENDIF, FOREACH/ENDFOREACH, LOOP/ENDLOOP). An unbalanced template fails to load ("Template parse error") and the previous version stays active.
Examples
<!-- IF USER -->
  <p>Welcome back, {USER.name}!</p>
<!-- ELSE -->
  <a href="#" data-action="show-login">Log in</a>
<!-- ENDIF -->

<!-- FOREACH TEMPLATE_IMAGES -->
  <img src="{ITEM.url}" alt="{ITEM.name}">
<!-- ENDFOREACH -->

Pages and navigation

The shop is one page. Each "page" is an element with id section-<name> and class app-section; the store shows one at a time (class active marks the visible one). Give the home section class="app-section active".

PageElementLink
home<section id="section-home" class="app-section"><a href="#home" data-nav="home">
products<section id="section-products" class="app-section"><a href="#products" data-nav="products">
product-detail<section id="section-product-detail" class="app-section"><a href="#product-detail" data-nav="product-detail">
featured<section id="section-featured" class="app-section"><a href="#featured" data-nav="featured">
wishlist<section id="section-wishlist" class="app-section"><a href="#wishlist" data-nav="wishlist">
cart<section id="section-cart" class="app-section"><a href="#cart" data-nav="cart">
checkout<section id="section-checkout" class="app-section"><a href="#checkout" data-nav="checkout">
profile<section id="section-profile" class="app-section"><a href="#profile" data-nav="profile">
terms<section id="section-terms" class="app-section"><a href="#terms" data-nav="terms">
refund-policy<section id="section-refund-policy" class="app-section"><a href="#refund-policy" data-nav="refund-policy">
privacy-policy<section id="section-privacy-policy" class="app-section"><a href="#privacy-policy" data-nav="privacy-policy">
Navigation
<nav>
  <a href="#home" data-nav="home">Home</a>
  <a href="#products" data-nav="products">Shop</a>
  <a href="#cart" data-nav="cart">Cart (<span id="cartCount">0</span>)</a>
</nav>

<main id="section-home" class="app-section active"> … </main>
<section id="section-products" class="app-section"> … </section>
  • hash: Default: /#products, /#product-detail?id=…
  • path: When the store uses SEO URLs (pos_setting.store.urlStructure = "seo"): /products, /product/:id …

Only include the pages you want. A link to a page your template doesn't have shows the home page instead.

Buttons that do things

Give a button or link data-action="…" and the store wires it up — no JavaScript needed. Values the storefront understands:

cancel-order cart-clear cart-remove checkout-goto checkout-next checkout-prev checkout-retry choose-store clear-filters close-filters close-modal close-nav close-search close-store-modal coupon-remove delete-address dismiss-checkout-badge edit-address filter-brand filter-category hero-next hero-prev logout open-filters open-product order-done order-view pd-add pd-thumb pd-variant pd-wishlist place-order proceed-checkout quick-add refresh-captcha reload-products remove-wishlist retry-stores search search-all select-store show-login show-register toggle-billing toggle-nav toggle-search toggle-wishlist view-order wishlist-to-cart

Example
<button type="button" data-action="show-login">Log in</button>
<button type="button" data-action="show-register">Create account</button>

Storefront features

The store fills in features by finding elements with particular ids, classes and data-sf-… attributes. Include a feature's elements and the store does the rest; leave them out and the feature is simply absent. Each feature below lists its elements and gives working markup taken from the store's own templates — copy it, then restyle freely (keep the ids, classes and data attributes).

Elements marked made by the store are created at run time (product cards, cart rows, the store chooser…). Style them in styles.css, but don't write them in index.html.

Page sections

The page is a single HTML document. Each storefront route shows the element with id "section-<route>" and class "app-section" and hides the others (class "active" marks the visible one). Elements with data-nav="<route>" or class "nav-link" + data-section="<route>" navigate.

ElementPurposeIn store templates
.app-sectionEvery route container. Only the active one should be visible (your CSS: .app-section{display:none} .app-section.active{display:block}).15 of 15
.main-navNavigation container whose .nav-link items are de-activated on route change.14 of 15
.nav-linkNavigation link; gets class "active" for the current route when it has data-section.15 of 15
.nav-profile-itemShown only when a customer is signed in.15 of 15
#mainNavMain navigation. Gets class "open" when #mobileMenuBtn is pressed.14 of 15
#mobileMenuBtnMenu toggle button (aria-expanded is kept in sync; body gets class "sf-nav-open").15 of 15
#mobileNavOptional separate mobile navigation (takes precedence over #mainNav for the menu button).1 of 15
#section-cartCart (route "cart").15 of 15
#section-checkoutCheckout (route "checkout").15 of 15
#section-featuredFeatured products (route "featured").15 of 15
#section-homeHome page (route "home"). Also the fallback for unknown routes.15 of 15
#section-privacy-policyPrivacy policy (route "privacy-policy").15 of 15
#section-product-detailSingle product (route "product-detail").15 of 15
#section-productsProduct list with filters (route "products").15 of 15
#section-profileAccount pages (route "profile"; shows the login modal when signed out).15 of 15
#section-refund-policyRefund policy (route "refund-policy").15 of 15
#section-termsTerms page (route "terms").15 of 15
#section-wishlistSaved items (route "wishlist").15 of 15
If you include #section-cart, include all of these too (every store template that has it does): #cartContainer
If you include #section-checkout, include all of these too (every store template that has it does): #agreeTerms #billingForm #differentBilling #discountRow #paymentDetailsContainer #paymentMethods #placeOrderBtn #reviewBilling #reviewDiscount #reviewItems #reviewPayment #reviewShipping #reviewShippingCost #reviewSubtotal #reviewTax #reviewTotal #sameAsShipping #shippingFeeHint #shippingForm #shippingLocationContainer #shippingLocationSelect #shippingMethods #shippingSublocationSelect #summaryNote
If you include #section-featured, include all of these too (every store template that has it does): #featuredGrid
If you include #section-product-detail, include all of these too (every store template that has it does): #productDetailContainer
If you include #section-products, include all of these too (every store template that has it does): #applyFiltersBtn #brandSelect #categorySelect #clearFiltersBtn #pagination #priceRange #priceRangeLabel #productsGrid #resultsCount #sortSelect #subcategorySelect #totalCount
If you include #section-profile, include all of these too (every store template that has it does): #changePasswordForm #confirmPassword #currentPassword #newPassword #profile-tab-activity #profile-tab-addresses #profile-tab-info #profile-tab-orders #profile-tab-security #profileActivity #profileAddresses #profileCurrency #profileEmail #profileName #profileOrders #profileUsername
If you include #section-wishlist, include all of these too (every store template that has it does): #wishlistContainer

Markup: #section-cart

From the “prestashop” template
<section id="section-cart" class="app-section" aria-labelledby="cartHeading">
    <div class="section-header">
        <div>
            <h2 id="cartHeading">Your Basket</h2>
            <p class="section-subtitle">Review the items in your basket</p>
        </div>
    </div>
    <div id="cartContainer" aria-live="polite"></div>
</section>

Markup: #section-checkout

From the “prestashop” template
<section id="section-checkout" class="app-section" aria-labelledby="checkoutHeading">
    <div class="section-header">
        <div>
            <h2 id="checkoutHeading">Checkout</h2>
            <p class="section-subtitle">Complete your order in a few steps</p>
        </div>
    </div>

    <div class="checkout-persistence-badge" id="checkoutPersistenceBadge" hidden>
        <i class="fas fa-history" aria-hidden="true"></i>
        <span>Your checkout progress has been restored.</span>
        <button type="button" class="checkout-persistence-dismiss" data-action="dismiss-checkout-badge" aria-label="Dismiss">&times;</button>
    </div>

    <div class="checkout-steps" role="list">
        <div class="step active" data-step="1" role="listitem"><span class="step-number">1</span><span class="step-label">Delivery</span></div>
        <div class="step" data-step="2" role="listitem"><span class="step-number">2</span><span class="step-label">Billing</span></div>
        <div class="step" data-step="3" role="listitem"><span class="step-number">3</span><span class="step-label">Delivery Method</span></div>
        <div class="step" data-step="4" role="listitem"><span class="step-number">4</span><span class="step-label">Payment</span></div>
        <div class="step" data-step="5" role="listitem"><span class="step-number">5</span><span class="step-label">Review</span></div>
    </div>

    <div class="checkout-content">
        <div class="checkout-step-content active" data-step="1">
            <h3>Delivery Information</h3>
            <form id="shippingForm" class="checkout-form" autocomplete="on" novalidate>
                <div class="form-row">
                    <div class="form-group"><label for="shipFullName">Full Name *</label><input type="text" id="shipFullName" name="fullName" required></div>
                    <div class="form-group"><label for="shipEmail">Email *</label><input type="email" id="shipEmail" name="email" required></div>
                </div>
                <div class="form-row">
                    <div class="form-group"><label for="shipPhone">Phone *</label><input type="tel" id="shipPhone" name="phone" required></div>
                    <div class="form-group"><label for="shipAddress1">Address Line 1 *</label><input type="text" id="shipAddress1" name="address1" required></div>
                </div>
                <div class="form-group"><label for="shipAddress2">Address Line 2</label><input type="text" id="shipAddress2" name="address2"></div>
                <div class="form-row">
                    <div class="form-group"><label for="shipCity">City *</label><input type="text" id="shipCity" name="city" required></div>
                    <div class="form-group"><label for="shipState">State *</label><input type="text" id="shipState" name="state" required></div>
                </div>
                <div class="form-row">
                    <div class="form-group"><label for="shipPostalCode">Postal Code *</label><input type="text" id="shipPostalCode" name="postalCode" required></div>
                    <div class="form-group">
                        <label for="shipCountry">Country *</label>
                        <select id="shipCountry" name="country" required>
                            <option value="">Select Country</option>
                            <option value="NG">Nigeria</option>
                            <option value="US">United States</option>
                            <option value="CA">Canada</option>
                            <option value="GB">United Kingdom</option>
                            <option value="AU">Australia</option>
                            <option value="DE">Germany</option>
                            <option value="FR">France</option>
                            <option value="JP">Japan</option>
                        </select>
                    </div>
                </div>
                <div class="form-actions">
                    <button type="button" class="btn-primary" data-action="checkout-next">
                        Continue to Billing <i class="fas fa-arrow-right" aria-hidden="true"></i>
                    </button>
                </div>
            </form>
        </div>

        <div class="checkout-step-content" data-step="2">
            <h3>Billing Information</h3>
            <form id="billingForm" class="checkout-form" novalidate>
                <div class="form-group checkbox-group">
                    <label><input type="checkbox" id="sameAsShipping" checked data-action="toggle-billing"> Same as delivery address</label>
                </div>
                <div id="differentBilling" style="display:none;">
                    <div class="form-row">
                        <div class="form-group"><label for="billFullName">Full Name *</label><input type="text" id="billFullName" name="fullName"></div>
                        <div class="form-group"><label for="billCompany">Company</label><input type="text" id="billCompany" name="company"></div>
                    </div>
                    <div class="form-group"><label for="billAddress">Address *</label><input type="text" id="billAddress" name="address1"></div>
                    <div class="form-row">
                        <div class="form-group"><label for="billCity">City *</label><input type="text" id="billCity" name="city"></div>
                        <div class="form-group"><label for="billState">State *</label><input type="text" id="billState" name="state"></div>
                    </div>
                    <div class="form-row">
                        <div class="form-group"><label for="billPostalCode">Postal Code *</label><input type="text" id="billPostalCode" name="postalCode"></div>
                        <div class="form-group">
                            <label for="billCountry">Country *</label>
                            <select id="billCountry" name="country">
                                <option value="">Select Country</option>
                                <option value="NG">Nigeria</option>
                                <option value="US">United States</option>
                                <option value="CA">Canada</option>
                                <option value="GB">United Kingdom</option>
                            </select>
                        </div>
                    </div>
                </div>
                <div class="form-actions">
                    <button type="button" class="btn-outline" data-action="checkout-prev"><i class="fas fa-arrow-left" aria-hidden="true"></i> Back</button>
                    <button type="button" class="btn-primary" data-action="checkout-next">Continue <i class="fas fa-arrow-right" aria-hidden="true"></i></button>
                </div>
            </form>
        </div>

        <div class="checkout-step-content" data-step="3">
            <h3>Delivery Method</h3>
            <div class="shipping-methods" id="shippingMethods" aria-live="polite">
                <div class="loading-state"><div class="spinner"></div><p>Loading delivery options…</p></div>
            </div>

            <div id="shippingLocationContainer" class="shipping-location-container" style="display:none;">
                <label for="shippingLocationSelect" class="shipping-location-label">
                    <i class="fas fa-map-marker-alt" aria-hidden="true"></i> Delivery Location (State / City) *
                </label>
                <select id="shippingLocationSelect" class="sort-select shipping-location-select">
                    <option value="">Select a state / city…</option>
                </select>
                <label for="shippingSublocationSelect" class="shipping-location-label">
                    <i class="fas fa-location-arrow" aria-hidden="true"></i> Area / Locality *
                </label>
                <select id="shippingSublocationSelect" class="sort-select shipping-location-select" disabled>
                    <option value="">Select a state / city first</option>
                </select>
                <p class="shipping-fee-hint" id="shippingFeeHint"></p>
            </div>

            <div class="form-actions">
                <button type="button" class="btn-outline" data-action="checkout-prev"><i class="fas fa-arrow-left" aria-hidden="true"></i> Back</button>
                <button type="button" class="btn-primary" data-action="checkout-next">Continue <i class="fas fa-arrow-right" aria-hidden="true"></i></button>
            </div>
        </div>

        <div class="checkout-step-content" data-step="4">
            <h3>Payment Method</h3>
            <div class="payment-methods" id="paymentMethods" aria-live="polite">
                <div class="loading-state"><div class="spinner"></div><p>Loading payment options…</p></div>
            </div>
            <div id="paymentDetailsContainer" class="payment-details-container"></div>

            <div class="form-actions">
                <button type="button" class="btn-outline" data-action="checkout-prev"><i class="fas fa-arrow-left" aria-hidden="true"></i> Back</button>
                <button type="button" class="btn-primary" data-action="checkout-next">Review Order <i class="fas fa-arrow-right" aria-hidden="true"></i></button>
            </div>
        </div>

        <div class="checkout-step-content" data-step="5">
            <h3>Review Your Order</h3>
            <div class="review-section"><h4><i class="fas fa-box" aria-hidden="true"></i> Items</h4><div id="reviewItems"></div></div>
            <div class="review-section"><h4><i class="fas fa-truck" aria-hidden="true"></i> Delivery</h4><div id="reviewShipping"></div><button class="btn-link" type="button" data-action="checkout-goto" data-step="1">Edit</button></div>
            <div class="review-section"><h4><i class="fas fa-file-invoice" aria-hidden="true"></i> Billing</h4><div id="reviewBilling"></div><button class="btn-link" type="button" data-action="checkout-goto" data-step="2">Edit</button></div>
            <div class="review-section"><h4><i class="fas fa-credit-card" aria-hidden="true"></i> Payment</h4><div id="reviewPayment"></div><button class="btn-link" type="button" data-action="checkout-goto" data-step="4">Edit</button></div>

            <div class="order-summary" id="orderSummary">
                <h4><i class="fas fa-receipt" aria-hidden="true"></i> Order Summary</h4>
                <div class="summary-row"><span>Subtotal:</span><span id="reviewSubtotal">—</span></div>
                <div class="summary-row discount-row" id="discountRow" style="display:none;"><span>Discount:</span><span id="reviewDiscount">—</span></div>
                <div id="discountBreakdownContainer"></div>
                <div class="summary-row"><span>Delivery:</span><span id="reviewShippingCost">—</span></div>
                <div class="summary-row"><span>Tax:</span><span id="reviewTax">—</span></div>
                <div class="summary-row total-row"><span>Total:</span><span id="reviewTotal">—</span></div>
                <div class="summary-note" id="summaryNote"></div>
            </div>

            <div class="form-group checkbox-group">
                <label><input type="checkbox" id="agreeTerms" required> I agree to the <a href="#terms" data-nav="terms">Terms &amp; Conditions</a> *</label>
            </div>

            <div class="form-actions">
                <button type="button" class="btn-outline" data-action="checkout-prev"><i class="fas fa-arrow-left" aria-hidden="true"></i> Back</button>
                <button type="button" class="btn-primary btn-large" id="placeOrderBtn" data-action="place-order">
                    <i class="fas fa-check-circle" aria-hidden="true"></i> Place Order
                </button>
            </div>
        </div>
    </div>
</section>
From the “prestashop” template
<section id="section-featured" class="app-section" aria-labelledby="featuredHeading">
    <div class="section-header">
        <div>
            <h2 id="featuredHeading">Featured Produce</h2>
            <p class="section-subtitle">Hand-picked favourites just for you</p>
        </div>
    </div>
    <div id="featuredStoreRequired" class="store-required-state" hidden></div>
    <div class="products-grid" id="featuredGrid" aria-live="polite"></div>
</section>

Markup: #section-product-detail

From the “prestashop” template
<section id="section-product-detail" class="app-section" aria-labelledby="productDetailHeading">
    <div class="section-header">
        <div>
            <button class="btn-outline btn-small" type="button" data-nav="products">
                <i class="fas fa-arrow-left" aria-hidden="true"></i> Back to Produce
            </button>
        </div>
    </div>
    <div id="productDetailContainer" aria-live="polite">
        <div class="loading-state"><div class="spinner"></div><p>Loading product…</p></div>
    </div>
</section>

Markup: #section-products

From the “prestashop” template
<section id="section-products" class="app-section" aria-labelledby="productsHeading">
    <div class="section-header">
        <div>
            <h2 id="productsHeading">Our Produce</h2>
            <p class="section-subtitle">Browse our full harvest collection</p>
        </div>
    </div>

    <div class="filters-section" id="productsFiltersSection">
        <div class="filters-container">
            <div class="filter-group">
                <label for="categorySelect">Category:</label>
                <select id="categorySelect" class="sort-select">
                    <option value="all">All Categories</option>
                </select>
            </div>
            <div class="filter-group">
                <label for="subcategorySelect">Subcategory:</label>
                <select id="subcategorySelect" class="sort-select" disabled>
                    <option value="">All Subcategories</option>
                </select>
            </div>
            <div class="filter-group">
                <label for="brandSelect">Farm:</label>
                <select id="brandSelect" class="sort-select">
                    <option value="">All Farms</option>
                </select>
            </div>
            <div class="filter-group">
                <label for="priceRange">Max Price: <span id="priceRangeLabel">—</span></label>
                <input type="range" id="priceRange" min="0" max="500" value="500" class="price-range" aria-label="Maximum price">
            </div>
            <div class="filter-group">
                <label for="sortSelect">Sort By:</label>
                <select id="sortSelect" class="sort-select">
                    <option value="default">Default</option>
                    <option value="newest">Newest</option>
                    <option value="price-asc">Price: Low to High</option>
                    <option value="price-desc">Price: High to Low</option>
                    <option value="name-asc">Name: A-Z</option>
                    <option value="name-desc">Name: Z-A</option>
                    <option value="rating">Top Rated</option>
                </select>
            </div>
            <div class="filter-group filter-clear-group">
                <button class="btn-primary btn-small" type="button" id="applyFiltersBtn">
                    <i class="fas fa-filter" aria-hidden="true"></i> Apply Filters
                </button>
                <button class="btn-outline btn-small" type="button" id="clearFiltersBtn">
                    <i class="fas fa-times" aria-hidden="true"></i> Clear
                </button>
            </div>
        </div>
        <div class="results-counter" id="resultsCounter">
            Showing <span id="resultsCount">0</span> of <span id="totalCount">0</span> products
        </div>
    </div>

    <div id="productsStoreRequired" class="store-required-state" hidden></div>
    <div class="products-grid" id="productsGrid" aria-live="polite"></div>
    <nav class="loop-pagination" id="pagination" aria-label="Product pagination"></nav>
</section>

Markup: #section-profile

From the “prestashop” template
<section id="section-profile" class="app-section" aria-labelledby="profileHeading">
    <div class="section-header">
        <div>
            <h2 id="profileHeading">My Profile</h2>
            <p class="section-subtitle">Manage your account and view your activity</p>
        </div>
    </div>

    <div class="profile-tabs" role="tablist">
        <button class="profile-tab active" type="button" data-tab="info" role="tab" aria-selected="true"><i class="fas fa-user" aria-hidden="true"></i> Personal Info</button>
        <button class="profile-tab" type="button" data-tab="orders" role="tab" aria-selected="false"><i class="fas fa-box" aria-hidden="true"></i> Orders</button>
        <button class="profile-tab" type="button" data-tab="addresses" role="tab" aria-selected="false"><i class="fas fa-map-marker-alt" aria-hidden="true"></i> Addresses</button>
        <button class="profile-tab" type="button" data-tab="activity" role="tab" aria-selected="false"><i class="fas fa-history" aria-hidden="true"></i> Recent Activity</button>
        <button class="profile-tab" type="button" data-tab="security" role="tab" aria-selected="false"><i class="fas fa-lock" aria-hidden="true"></i> Security</button>
    </div>

    <div class="profile-tab-content active" id="profile-tab-info" role="tabpanel">
        <div class="profile-info-grid">
            <div class="profile-info-item"><span>Name</span><strong id="profileName">—</strong></div>
            <div class="profile-info-item"><span>Username</span><strong id="profileUsername">—</strong></div>
            <div class="profile-info-item"><span>Email</span><strong id="profileEmail">—</strong></div>
            <div class="profile-info-item"><span>Currency</span><strong id="profileCurrency">—</strong></div>
        </div>
        <div class="form-actions">
            <button class="btn-outline" type="button" data-action="logout"><i class="fas fa-sign-out-alt" aria-hidden="true"></i> Logout</button>
        </div>
    </div>

    <div class="profile-tab-content" id="profile-tab-orders" role="tabpanel">
        <div id="profileOrders"><div class="loading-state"><div class="spinner"></div><p>Loading orders…</p></div></div>
    </div>

    <div class="profile-tab-content" id="profile-tab-addresses" role="tabpanel">
        <div id="profileAddresses"><div class="loading-state"><div class="spinner"></div><p>Loading addresses…</p></div></div>
    </div>

    <div class="profile-tab-content" id="profile-tab-activity" role="tabpanel">
        <div id="profileActivity"><div class="loading-state"><div class="spinner"></div><p>Loading activity…</p></div></div>
    </div>

    <div class="profile-tab-content" id="profile-tab-security" role="tabpanel">
        <div class="security-panel">
            <h3>Change Password</h3>
            <p class="text-muted">Use a strong password with at least 6 characters.</p>
            <form id="changePasswordForm" class="checkout-form" novalidate>
                <div class="form-group">
                    <label for="currentPassword">Current Password *</label>
                    <input type="password" id="currentPassword" required autocomplete="current-password">
                </div>
                <div class="form-group">
                    <label for="newPassword">New Password *</label>
                    <input type="password" id="newPassword" required autocomplete="new-password" minlength="6">
                </div>
                <div class="form-group">
                    <label for="confirmPassword">Confirm New Password *</label>
                    <input type="password" id="confirmPassword" required autocomplete="new-password" minlength="6">
                </div>
                <div class="form-actions">
                    <button type="submit" class="btn-primary">
                        <i class="fas fa-lock" aria-hidden="true"></i> Update Password
                    </button>
                </div>
            </form>
        </div>
    </div>
</section>

Markup: #section-wishlist

From the “prestashop” template
<section id="section-wishlist" class="app-section" aria-labelledby="wishlistHeading">
    <div class="section-header">
        <div>
            <h2 id="wishlistHeading">My Saved Items</h2>
            <p class="section-subtitle">Produce you've saved for later</p>
        </div>
    </div>
    <div id="wishlistContainer" aria-live="polite"></div>
</section>

Header counters, account and search

Live counters, the account menu and product search with suggestions.

ElementPurposeIn store templates
#cartCountNumber of items in the cart (class "sf-empty-count" when zero).15 of 15
#searchCloseCloses the search overlay.1 of 15
#searchContainerSearch wrapper toggled with class "open"/"active" by #searchToggleBtn.9 of 15
#searchInputSearch box. Typing shows suggestions; Enter searches the products page.15 of 15
#searchOverlayFull-screen search overlay (used instead of #searchPanel when present).1 of 15
#searchPanelOptional dropdown panel toggled together with #searchContainer.7 of 15
#searchSuggestionsSuggestion list container (class "active" when open).15 of 15
#searchToggleAlternative id for the search toggle button.1 of 15
#searchToggleBtnOpens/closes the search panel.7 of 15
#userMenuReplaced with "Log in / Register" buttons or the signed-in customer's name, account and logout buttons.15 of 15
#wishlistCountNumber of saved items.15 of 15

Markup: #searchContainer

From the “prestashop” template
<div class="search-container" id="searchContainer">
                    <button class="icon-btn search-toggle-btn" type="button" id="searchToggleBtn" aria-label="Search" aria-expanded="false">
                        <i class="fas fa-search" aria-hidden="true"></i>
                    </button>
                    <div class="search-panel" id="searchPanel">
                        <label class="visually-hidden" for="searchInput">Search produce</label>
                        <input type="search" id="searchInput" placeholder="Search product here…" class="search-input" autocomplete="off">
                        <button class="search-submit-btn" type="button" aria-label="Search" data-action="search">
                            <i class="fas fa-search" aria-hidden="true"></i>
                        </button>
                        <div id="searchSuggestions" class="search-suggestions" role="listbox" aria-live="polite"></div>
                    </div>
                </div>

Markup: #userMenu

From the “prestashop” template
<div class="user-menu" id="userMenu">
                    <button class="icon-btn login-btn" type="button" data-action="show-login" title="Login" aria-label="Login">
                        <i class="fas fa-sign-in-alt" aria-hidden="true"></i> <span>Login</span>
                    </button>
                    <button class="icon-btn register-btn" type="button" data-action="show-register" title="Register" aria-label="Register">
                        <i class="fas fa-user-plus" aria-hidden="true"></i> <span>Register</span>
                    </button>
                </div>

Store selection

When several stores are active the shopper must choose one before products are shown. The engine builds the store chooser itself; a template only decides where it goes and which blocks wait for a store.

ElementPurposeIn store templates
[data-sf-store-dependent]Hidden until a store is selected (use it on anything that only makes sense for a store).9 of 15
[data-sf-store-gate]Where the full-width store chooser is inserted. Without it the chooser goes after the hero (#heroSlider/.hero/[data-sf-hero]) or at the top of #section-home.8 of 15
[data-sf-store-pill]Where the "Shopping at … / Change" button goes. Without it, it is prepended to .header-actions (or similar).8 of 15

Made by the store (style only): #sfStoreGate #sfStoreModal #sfStorePill

Markup: [data-sf-store-gate]

From the “organic” template
<div class="k-gate-slot" data-sf-store-gate></div>

Markup: [data-sf-store-pill]

From the “organic” template
<div class="k-pill-slot" data-sf-store-pill></div>

Home page blocks

Blocks filled with the selected store's data. Each hides itself when there is nothing to show.

ElementPurposeIn store templates
.announcement-barAlternative announcement bar marker.2 of 15
.footer-newsletterNewsletter block in the footer.1 of 15
.hero-slideOne slide inside #heroSlider.15 of 15
.home-featuredWrapper of #homeFeaturedGrid; hidden until a store is chosen and when empty.14 of 15
.home-productsWrapper of #homeProductsGrid.14 of 15
.newsletter-sectionNewsletter block (shown when content.newsletter is true). A form inside with an email input subscribes.8 of 15
.promo-bannersPromotion slots (.promo-banner children). Filled from content.promotions or the store's categories.6 of 15
.testimonial-sectionTestimonials wrapper (hidden when there are none).6 of 15
.two-col-bannersTwo promotion slots (.two-col-banner children).3 of 15
.usp-stripAlternative marker for service highlights.1 of 15
[data-sf-announcement]Announcement bar filled from content.announcement (hidden when empty).9 of 15
[data-sf-category-chips]Category links ("chips"). Add data-sf-chip-images for thumbnails; wrap in [data-sf-chips-wrap] to hide the wrapper when empty.2 of 15
[data-sf-chip-images]Part of [data-sf-category-chips] (home page blocks).2 of 15
[data-sf-chips-wrap]Part of [data-sf-category-chips] (home page blocks).2 of 15
[data-sf-hero]Marks a hero element (used to place the store chooser after it).0 of 15
[data-sf-newsletter]Newsletter form marker.8 of 15
[data-sf-promo]One promotion slot.0 of 15
[data-sf-promos]Generic promotion container ([data-sf-promo] children).0 of 15
[data-sf-section]Part of [data-sf-testimonials] (home page blocks).9 of 15
[data-sf-stats]Live numbers for the store (products, categories, brands, open now).3 of 15
[data-sf-testimonials]Testimonial track (inside .testimonial-section / [data-sf-section="testimonials"]). Only content.testimonials is shown.6 of 15
[data-sf-ticker]Scrolling strip of category names.2 of 15
[data-sf-usps-class]Part of [data-sf-usps] (home page blocks).8 of 15
[data-sf-usps-list]Part of [data-sf-usps] (home page blocks).2 of 15
[data-sf-usps-max]Part of [data-sf-usps] (home page blocks).5 of 15
[data-sf-usps]Service highlights. data-sf-usps="feature" renders .feature-card items; data-sf-usps-class sets the item class; data-sf-usps-max the count; [data-sf-usps-list] the inner target.10 of 15
#heroDotsDot buttons generated for each slide.15 of 15
#heroPaymentLineText replaced with the store's payment methods.3 of 15
#heroSliderSlider. Children .hero-slide (first one active), buttons [data-action="hero-prev"/"hero-next"], dots in #heroDots. content.heroSlides in template.json replaces the slides.15 of 15
#homeAnimalsGridSecondary category showcase (icon cards).1 of 15
#homeAnimalsSectionWrapper of #homeAnimalsGrid.1 of 15
#homeBrandsGridBrand tiles (shown when the store has 2+ brands).13 of 15
#homeBrandsSectionWrapper of #homeBrandsGrid.13 of 15
#homeCategoriesGridCategory tiles.14 of 15
#homeCategoriesSectionWrapper of #homeCategoriesGrid.14 of 15
#homeFeaturedGridFeatured product cards.15 of 15
#homeProductsGridNewest product cards.15 of 15
#homeRecentlyViewedRecently viewed products (from this browser, per store). Put a .products-grid inside.9 of 15
#megaBrandsListBrand links inside a mega menu.1 of 15
#megaCategoriesListCategory links inside a mega menu.1 of 15
#testimonialDotsTestimonial dots.6 of 15
If you include #heroSlider, include all of these too (every store template that has it does): #heroDots

Markup: [data-sf-announcement]

From the “prestashop” template
<div class="announcement-bar sf-hidden" data-sf-announcement>
    <div class="container">
        <p class="announcement-text"></p>
    </div>
</div>

Markup: [data-sf-category-chips]

From the “boutique” template
<div class="k-chips-row sf-hidden" data-sf-chips-wrap>
        <div class="k-container"><nav data-sf-category-chips data-sf-chip-images aria-label="Categories"></nav></div>
    </div>

Markup: [data-sf-stats]

From the “corporate” template
<div data-sf-stats class="sf-hidden"></div>

Markup: [data-sf-ticker]

From the “boutique” template
<div class="k-ticker k-ticker--top sf-hidden" data-sf-ticker></div>

Markup: [data-sf-usps]

From the “prestashop” template
<div class="usp-strip" data-sf-usps aria-label="Why shop with us"></div>

Markup: #heroSlider

From the “prestashop” template
<div class="hero-slider" id="heroSlider" aria-roledescription="carousel" aria-label="Featured banner">
        <div class="hero-slides">
            <div class="hero-slide active" data-slide="0">
                <div class="hero-content">
                    <p class="hero-eyebrow">It's about your harvest</p>
                    <h2 id="homeHeading">Farm-Fresh Produce,<br>Delivered To Your Door.</h2>
                    <p class="hero-sub">Hand-picked from local growers and delivered with care.</p>
                    <div class="hero-actions">
                        <button class="btn-primary btn-large" type="button" data-nav="products">Shop Now</button>
                    </div>
                </div>
            </div>
            <div class="hero-slide slide-alt-1" data-slide="1">
                <div class="hero-content">
                    <p class="hero-eyebrow">Make us a part of your kitchen</p>
                    <h2>Harvest Season<br>Is Here.</h2>
                    <p class="hero-sub">Explore this week's freshest arrivals from our partner farms.</p>
                    <div class="hero-actions">
                        <button class="btn-primary btn-large" type="button" data-nav="products">Browse Harvest</button>
                    </div>
                </div>
            </div>
            <div class="hero-slide slide-alt-2" data-slide="2">
                <div class="hero-content">
                    <p class="hero-eyebrow">Fast &amp; secure checkout</p>
                    <h2>Multiple Payment Options,<br>Safe Delivery.</h2>
                    <p class="hero-sub" id="heroPaymentLine">Shop with confidence — secure payments at checkout.</p>
                    <div class="hero-actions">
                        <button class="btn-primary btn-large" type="button" data-nav="featured">Shop Featured</button>
                    </div>
                </div>
            </div>
        </div>
        <button class="hero-nav hero-nav-prev" type="button" aria-label="Previous slide" data-action="hero-prev">
            <i class="fas fa-chevron-left" aria-hidden="true"></i>
        </button>
        <button class="hero-nav hero-nav-next" type="button" aria-label="Next slide" data-action="hero-next">
            <i class="fas fa-chevron-right" aria-hidden="true"></i>
        </button>
        <div class="hero-dots" id="heroDots" role="tablist" aria-label="Slides"></div>
    </div>

Markup: #homeBrandsSection

From the “prestashop” template
<div class="home-brands" id="homeBrandsSection">
        <div class="section-header centered">
            <h2>Shop By Farm</h2>
        </div>
        <div id="homeBrandsGrid" class="brands-grid" aria-live="polite"></div>
    </div>

Markup: #homeCategoriesSection

From the “prestashop” template
<div class="home-categories" id="homeCategoriesSection">
        <div class="section-header centered">
            <h2>Shop By Category</h2>
        </div>
        <div id="homeCategoriesGrid" class="categories-grid" aria-live="polite"></div>
    </div>

Markup: #homeFeaturedGrid

From the “prestashop” template
<div id="homeFeaturedGrid" class="products-grid" aria-live="polite"></div>

Markup: #homeProductsGrid

From the “prestashop” template
<div id="homeProductsGrid" class="products-grid" aria-live="polite"></div>

Markup: #homeRecentlyViewed

From the “prestashop” template
<div class="home-recent sf-hidden" id="homeRecentlyViewed">
        <div class="section-header centered"><h2>Recently Viewed</h2></div>
        <div class="products-grid" aria-live="polite"></div>
    </div>

Products page

Server-side filtering, sorting and pagination of the selected store's catalogue.

ElementPurposeIn store templates
.filter-sidebarAlternative filter drawer marker.1 of 15
#applyFiltersBtnApplies filters (filters also apply instantly unless StorefrontTheme.instantFilters is false).15 of 15
#brandSelect<select> of brands.15 of 15
#categorySelect<select> of categories (first option value "all").15 of 15
#clearFiltersBtnClears filters.15 of 15
#featuredGridFeatured products page grid.15 of 15
#featuredStoreRequiredMessage area on the featured page when no store is selected.10 of 15
#filterToggleMobileOpens the filter panel on small screens.9 of 15
#paginationPage buttons.15 of 15
#priceRange<input type="range"> maximum price.15 of 15
#priceRangeLabelShows the chosen maximum price.15 of 15
#productDetailContainerFilled with the product page (gallery, price, variants, quantity, add to cart, related products).15 of 15
#productsFiltersSectionFilter panel (class "mobile-open" when opened on small screens).10 of 15
#productsGridProduct cards for the current page.15 of 15
#productsStoreRequiredMessage area shown when no store is selected.10 of 15
#resultsCountNumber of products shown.15 of 15
#resultsCounterWrapper of the results count.10 of 15
#sortSelect<select> with values default, newest, price-asc, price-desc, name-asc, name-desc, rating.15 of 15
#subcategorySelect<select> of subcategories (enabled after a category is chosen).15 of 15
#totalCountTotal number of matching products.15 of 15
#wishlistContainerFilled with saved items.15 of 15

Cart

The engine renders the whole cart (lines, coupon, totals) into #cartContainer.

ElementPurposeIn store templates
#cartContainerCart contents.15 of 15
#stickyCartCountItem count in the sticky bar.1 of 15
#stickyCartTotalTotal in the sticky bar.1 of 15
#stickyOrderBarOptional sticky bar with #stickyCartCount and #stickyCartTotal.1 of 15

Checkout

Five steps (.checkout-step-content[data-step="1".."5"]): delivery details, billing, delivery method, payment, review. The forms and ids below are read and filled by the engine and must keep these ids.

ElementPurposeIn store templates
.checkout-contentWrapper of the step panels (the order summary is inserted next to it).15 of 15
.checkout-step-contentOne step panel (class "active" when shown).15 of 15
.checkout-stepsProgress indicator; children .step[data-step] get classes active/completed/reachable.15 of 15
[data-action="checkout-goto"]Jump to the step in data-step.15 of 15
[data-action="checkout-next"]Next step button.15 of 15
[data-action="checkout-prev"]Previous step button.15 of 15
[data-step]Part of .checkout-steps (checkout).0 of 15
#agreeTermsTerms checkbox required before placing the order.15 of 15
#billingFormStep 2 form with #sameAsShipping and the #differentBilling fields.15 of 15
#checkoutPersistenceBadge"Your checkout progress has been restored" notice.10 of 15
#differentBillingPart of #billingForm (checkout).15 of 15
#discountRowPart of #reviewSubtotal (checkout).15 of 15
#paymentDetailsContainerPayment instructions for the chosen method.15 of 15
#paymentMethodsStep 4: payment methods.15 of 15
#placeOrderBtnPlaces the order.15 of 15
#reviewBillingPart of #reviewItems (checkout).15 of 15
#reviewDiscountPart of #reviewSubtotal (checkout).15 of 15
#reviewItemsStep 5: order lines (with #reviewShipping, #reviewBilling, #reviewPayment).15 of 15
#reviewPaymentPart of #reviewItems (checkout).15 of 15
#reviewShippingPart of #reviewItems (checkout).15 of 15
#reviewShippingCostPart of #reviewSubtotal (checkout).15 of 15
#reviewSubtotalTotals: #reviewSubtotal #reviewDiscount #reviewShippingCost #reviewTax #reviewTotal (#discountRow, #summaryNote).15 of 15
#reviewTaxPart of #reviewSubtotal (checkout).15 of 15
#reviewTotalPart of #reviewSubtotal (checkout).15 of 15
#sameAsShippingPart of #billingForm (checkout).15 of 15
#shipAddress1Part of #shippingForm (checkout).15 of 15
#shipAddress2Part of #shippingForm (checkout).15 of 15
#shipCityPart of #shippingForm (checkout).15 of 15
#shipCountryPart of #shippingForm (checkout).15 of 15
#shipEmailPart of #shippingForm (checkout).15 of 15
#shipFullNamePart of #shippingForm (checkout).15 of 15
#shipPhonePart of #shippingForm (checkout).15 of 15
#shippingFeeHintPart of #shippingLocationContainer (checkout).15 of 15
#shippingFormStep 1 form: #shipFullName #shipEmail #shipPhone #shipAddress1 #shipAddress2 #shipCity #shipState #shipPostalCode #shipCountry.15 of 15
#shippingLocationContainerDelivery area pickers #shippingLocationSelect and #shippingSublocationSelect, and #shippingFeeHint.15 of 15
#shippingLocationSelectPart of #shippingLocationContainer (checkout).15 of 15
#shippingMethodsStep 3: delivery options.15 of 15
#shippingSublocationSelectPart of #shippingLocationContainer (checkout).15 of 15
#shipPostalCodePart of #shippingForm (checkout).15 of 15
#shipStatePart of #shippingForm (checkout).15 of 15
#summaryNotePart of #reviewSubtotal (checkout).15 of 15

Made by the store (style only): #sfCheckoutBlocked #sfCheckoutSummary #sfOrderConfirmation

Account, login and registration

Modals (.modal, class "active" when open) and the profile page tabs.

ElementPurposeIn store templates
.modalAny modal; clicking its backdrop closes it.15 of 15
.profile-tabProfile tab buttons (data-tab="info|orders|addresses|activity|security").15 of 15
.profile-tab-contentTab panels with ids profile-tab-<tab>.15 of 15
[data-action="close-modal"]Closes the modal named in data-modal (or the closest .modal).15 of 15
[data-action="logout"]Signs out.15 of 15
[data-action="show-login"]Opens the login modal.15 of 15
[data-action="show-register"]Opens the register modal.15 of 15
#addrCountryPart of #addressModal (account, login and registration).15 of 15
#addressFormPart of #addressModal (account, login and registration).15 of 15
#addressModalAddress editor (#addressForm with #addrId #addrFullName … #addrCountry).15 of 15
#addrFullNamePart of #addressModal (account, login and registration).15 of 15
#addrIdPart of #addressModal (account, login and registration).15 of 15
#changePasswordFormPassword form (#currentPassword #newPassword #confirmPassword).15 of 15
#confirmPasswordPart of #changePasswordForm (account, login and registration).15 of 15
#currentPasswordPart of #changePasswordForm (account, login and registration).15 of 15
#loginFormPart of #loginModal (account, login and registration).15 of 15
#loginModalLogin modal containing #loginForm (#loginUsername, #loginPassword).15 of 15
#loginPasswordPart of #loginModal (account, login and registration).15 of 15
#loginUsernamePart of #loginModal (account, login and registration).15 of 15
#newPasswordPart of #changePasswordForm (account, login and registration).15 of 15
#profileActivityRecent activity.15 of 15
#profileAddressesSaved addresses.15 of 15
#profileCurrencyPart of #profileName (account, login and registration).15 of 15
#profileEmailPart of #profileName (account, login and registration).15 of 15
#profileNameProfile fields: #profileName #profileUsername #profileEmail #profileCurrency.15 of 15
#profileOrdersOrder history.15 of 15
#profileUsernamePart of #profileName (account, login and registration).15 of 15
#registerCaptchaContainerPart of #registerModal (account, login and registration).15 of 15
#registerConfirmPasswordPart of #registerModal (account, login and registration).15 of 15
#registerEmailPart of #registerModal (account, login and registration).15 of 15
#registerFormPart of #registerModal (account, login and registration).15 of 15
#registerModalRegister modal containing #registerForm (#registerName #registerUsername #registerEmail #registerPhone #registerPassword #registerConfirmPassword, honeypot #registerWebsite, #registerCaptchaContainer).15 of 15
#registerNamePart of #registerModal (account, login and registration).15 of 15
#registerPasswordPart of #registerModal (account, login and registration).15 of 15
#registerPhonePart of #registerModal (account, login and registration).15 of 15
#registerUsernamePart of #registerModal (account, login and registration).15 of 15
#registerWebsitePart of #registerModal (account, login and registration).15 of 15
If you include #addressModal, include all of these too (every store template that has it does): #addrId #addressForm
If you include #loginModal, include all of these too (every store template that has it does): #loginForm #loginPassword #loginUsername
If you include #registerModal, include all of these too (every store template that has it does): #registerCaptchaContainer #registerConfirmPassword #registerForm #registerPassword

Markup: #addressModal

From the “prestashop” template
<div id="addressModal" class="modal" role="dialog" aria-modal="true" aria-labelledby="addressModalTitle">
    <div class="modal-content modal-medium">
        <button class="modal-close" type="button" data-action="close-modal" data-modal="addressModal" aria-label="Close">&times;</button>
        <h2 id="addressModalTitle">Edit Address</h2>
        <form id="addressForm" class="checkout-form" novalidate>
            <input type="hidden" id="addrId">
            <div class="form-row">
                <div class="form-group"><label for="addrFullName">Full Name *</label><input type="text" id="addrFullName" required></div>
                <div class="form-group"><label for="addrEmail">Email</label><input type="email" id="addrEmail"></div>
            </div>
            <div class="form-row">
                <div class="form-group"><label for="addrPhone">Phone</label><input type="tel" id="addrPhone"></div>
                <div class="form-group"><label for="addrAddress1">Address Line 1 *</label><input type="text" id="addrAddress1" required></div>
            </div>
            <div class="form-group"><label for="addrAddress2">Address Line 2</label><input type="text" id="addrAddress2"></div>
            <div class="form-row">
                <div class="form-group"><label for="addrCity">City *</label><input type="text" id="addrCity" required></div>
                <div class="form-group"><label for="addrState">State *</label><input type="text" id="addrState" required></div>
            </div>
            <div class="form-row">
                <div class="form-group"><label for="addrPostalCode">Postal Code</label><input type="text" id="addrPostalCode"></div>
                <div class="form-group"><label for="addrCountry">Country</label><input type="text" id="addrCountry"></div>
            </div>
            <div class="form-actions">
                <button type="button" class="btn-outline" data-action="close-modal" data-modal="addressModal">Cancel</button>
                <button type="submit" class="btn-primary"><i class="fas fa-save" aria-hidden="true"></i> Save Address</button>
            </div>
        </form>
    </div>
</div>

Markup: #loginModal

From the “prestashop” template
<div id="loginModal" class="modal" role="dialog" aria-modal="true" aria-labelledby="loginModalTitle">
    <div class="modal-content modal-small">
        <button class="modal-close" type="button" data-action="close-modal" data-modal="loginModal" aria-label="Close">&times;</button>
        <h2 id="loginModalTitle">Welcome Back</h2>
        <form id="loginForm" novalidate>
            <div class="form-notification" role="alert" aria-live="polite"></div>
            <div class="form-group">
                <label for="loginUsername">Email</label>
                <input type="text" id="loginUsername" required autocomplete="username">
            </div>
            <div class="form-group">
                <label for="loginPassword">Password</label>
                <input type="password" id="loginPassword" required autocomplete="current-password">
            </div>
            <button type="submit" class="btn-primary btn-block">
                <i class="fas fa-sign-in-alt" aria-hidden="true"></i> Login
            </button>
        </form>
        <p class="modal-footer-text">
            Don't have an account?
            <a href="#" data-action="show-register">Create Account</a>
        </p>
    </div>
</div>

Markup: #registerModal

From the “prestashop” template
<div id="registerModal" class="modal" role="dialog" aria-modal="true" aria-labelledby="registerModalTitle">
    <div class="modal-content modal-small">
        <button class="modal-close" type="button" data-action="close-modal" data-modal="registerModal" aria-label="Close">&times;</button>
        <h2 id="registerModalTitle">Create Account</h2>
        <form id="registerForm" novalidate>
            <div class="form-notification" role="alert" aria-live="polite"></div>
            <div class="form-group"><label for="registerName">Full Name *</label><input type="text" id="registerName" required autocomplete="name"></div>
            <div class="form-group"><label for="registerUsername">Username *</label><input type="text" id="registerUsername" required autocomplete="username"></div>
            <div class="form-group"><label for="registerEmail">Email *</label><input type="email" id="registerEmail" required autocomplete="email"></div>
            <div class="form-group"><label for="registerPhone">Phone Number *</label><input type="tel" id="registerPhone" required autocomplete="tel" placeholder="e.g. +234 801 234 5678"></div>
            <div class="form-group"><label for="registerPassword">Password *</label><input type="password" id="registerPassword" required autocomplete="new-password" minlength="6"></div>
            <div class="form-group"><label for="registerConfirmPassword">Confirm Password *</label><input type="password" id="registerConfirmPassword" required autocomplete="new-password" minlength="6"></div>

            <div class="honeypot-field" aria-hidden="true">
                <label for="registerWebsite">Website (leave blank)</label>
                <input type="text" id="registerWebsite" name="website" tabindex="-1" autocomplete="off">
            </div>

            <div id="registerCaptchaContainer" class="captcha-container"></div>

            <button type="submit" class="btn-primary btn-block">
                <i class="fas fa-user-plus" aria-hidden="true"></i> Register
            </button>
        </form>
        <p class="modal-footer-text">
            Already have an account?
            <a href="#" data-action="show-login">Login</a>
        </p>
    </div>
</div>

styles.css

Template stylesheet, served sanitized at /templates/<name>/styles.css and linked after the shared styles. style.css is accepted as an alternative name (styles.css wins on /styles.css, style.css wins on /style.css; the page links /style.css).

Styles apply in this order: Bootstrap and Font Awesome (from the store's CDN) → fonts from assets.fonts → core.css (always) → kit.css (if assets.kit is true) → your brand colours → your styles.css. Yours comes last, so it wins.

What the store changes in your CSS

  • @import rules are removed
  • url(http://…), url(https://…) and url(//…) become "none"
  • expression(), behavior: and -moz-binding: are removed
  • scroll-behavior declarations are removed too (the rule that removes behavior: also matches them).

Images in CSS

Write absolute paths: background-image: url(/image/hero.jpg);. A relative url(image/hero.jpg) does not work (the stylesheet is served from another address), and images from other websites are blocked.

Brand variables

Colours and fonts from template.json → branding become CSS variables you can use anywhere:

template.jsonCSS variable
branding.primaryColorvar(--sf-primary)
branding.secondaryColorvar(--sf-secondary)
branding.accentColorvar(--sf-accent)
branding.textColorvar(--sf-ink)
branding.surfaceColorvar(--sf-surface)
branding.mutedSurfaceColorvar(--sf-muted-surface)
branding.onPrimaryColorvar(--sf-on-primary)
branding.fontFamilyvar(--sf-font-body)
branding.headingFontvar(--sf-font-heading)
branding.displayFontvar(--sf-font-display)
branding.radiusvar(--sf-radius)
styles.css
.btn-primary { background: var(--sf-primary); color: #fff; }
.site-header { font-family: var(--sf-font-heading); }

Fonts and the layout kit

Web fonts from other websites are blocked. Use the fonts the store hosts: list them in template.json → assets.fonts and name them in branding.

Key for assets.fontsFont familyWeights
albert-sansAlbert Sans100 900
cormorant-garamondCormorant Garamond300 700
exoExo100 900
forumForum400
frauncesFraunces100 900
interInter100 900
jostJost100 900
manropeManrope200 800
nunitoNunito200 1000
pacificoPacifico400
playfair-displayPlayfair Display400 900
pt-sansPT Sans400, 700
robotoRoboto100 900
rubikRubik300 900
template.json
{
    "branding": {
        "primaryColor": "#0b6e4f",
        "fontFamily": "'Manrope', system-ui, sans-serif",
        "headingFont": "'Fraunces', Georgia, serif"
    },
    "assets": {
        "fonts": ["manrope", "fraunces"],
        "kit": true
    }
}

Layout kit: true loads /assets/storefront/kit.css (the layout kit used by the newer templates). The storefront starter uses it (classes starting with k-); set it to false if you write all the CSS yourself.

Images

  • Put pictures in the image/ folder (sub-folders are fine) and use them as /image/…: <img src="/image/logo.svg" alt="Sunny Market">.
  • Allowed types: .png .jpeg .jpg .gif .webp .bmp .svg. Other files and files starting with a dot are not served.
  • <img src="image/x.png"> and "./image/x.png" are rewritten to "/image/x.png"; CSS url() is not rewritten, so use /image/... there.
  • External <img src="https://..."> URLs are rewritten to the image proxy (/img-proxy?url=...).
  • {TEMPLATE_IMAGES} lists top-level files of image/ only.
  • Product, category and store pictures come from the store, not from your template.
Any other file in the template folder (for example logo.png at the top level) is not served by the application.

script.js

Optional. It runs before the storefront engine, so it can configure it through window.StorefrontTheme:

PropertyWhat it does
labelsObject of words the engine uses (see labels). Overridden by template.json "labels".
iconsFont Awesome classes for engine-rendered icons: cart, wishlist, emptyCart, browse, categoryDefault, brand.
categoryIconsExtra keyword → icon class pairs for category tiles (matched against category names).
buttonColorConfirm-button colour for SweetAlert2 dialogs (defaults to branding.primaryColor).
onSectionfunction(route, params, App) called after every route change.
instantFiltersSet to false so filters apply only when #applyFiltersBtn is pressed.
categoryImagesSet to false to always use icons instead of category images.
onInitfunction(App) called before the engine boots.
onReadyfunction(App) called once the store context, session and cart are loaded.
script.js
window.StorefrontTheme = {
    labels: { cart: 'Basket', addToCart: 'Add to basket' },
    icons: { cart: 'fas fa-basket-shopping' },
    onReady: function (App) {
        // the shop is loaded; App is window.Storefront
    },
    onSection: function (route, params, App) {
        // runs after every page change, e.g. route === 'products'
        document.body.dataset.page = route;
    }
};

What the store changes in script.js

script.js is rewritten with these patterns (the matching code stops working).

  • document.createElement("script")
  • .createElement("script")
  • new Function(
  • eval(
  • setTimeout/setInterval with a string
  • import() of a remote URL
  • fetch/XMLHttpRequest/WebSocket/EventSource to an absolute remote URL
  • document.write(

Use event listeners (addEventListener) instead of onclick attributes, and functions instead of strings in setTimeout.

window.Storefront

Available once the engine has started (also as window.LoveApp): addToCart api cancelOrder cart cartApi cartMismatch cartSignature cartStoreAvailable cartStoreId checkout clearFilters clearFormNotification closeModal coupon currentImageIndex currentProduct currentSection currentVariant errorMessage facets facetsLoader filterByBrand filterByCategory formatMoney goToStep hero heroSliderNext heroSliderPrev imageTag loadProducts loadProfile logout navigateTo nextCheckoutStep onSection openModal openOrderDetail openProductDetail paymentGateways performSearch placeOrder prevCheckoutStep proceedToCheckout productCardHtml quickAddToCart recentlyViewed removeFromWishlist safeImageUrl sections showFormNotification showLoginModal showRegisterModal showSection showToast store storeUI switchProfileTab toggleWishlist user util variantLabel wishlist wishlistRemote

template.json

Template configuration. Required: the application only loads folders that contain a readable template.json. It must be valid JSON (double quotes, no trailing commas, no comments). String values in template.json have <…> tags, "javascript:" and on…= removed before reaching the browser.

The Status column shows what the store actually reads: used, not used by the shop (passed on but has no effect), ignored.

KeyTypeDefaultStatusMeaning
displayNamestringusedName shown in the admin template list (GET /api/templates) and stored as the active theme name when an admin switches to this template.
descriptionstringusedDescription shown in the admin template list when set (falls back to website.description).
versionstringusedTemplate version. Used for the admin list and the installed-version check when theme.json has no version.
websiteobjectusedStore identity defaults supplied by the template.
descriptionstring""usedTagline used for the {DESCRIPTION} placeholder, the <meta name="description"> tag and the browser config when the store record has no description of its own.
namestring""ignoredNot read by the application — the store name always comes from the store record (pos_setting.store.name).
logostring""ignoredNot read by the application.
faviconstring""ignoredNot read by the application.
currencystring""ignoredNot read by the application — the currency comes from the store record.
languagestring"en"ignoredNot read by the application (the page is always lang="en").
yearstring""ignoredNot read by the application — {YEAR} is the current year.
brandingobjectusedColours, fonts and corner radius. Exposed to the browser as config.branding and converted into CSS custom properties in a <style id="sf-theme-tokens"> tag that core.css / kit.css (and your CSS) can use.
primaryColorstringusedMain brand colour. Also the default SweetAlert2 confirm-button colour when script.js sets no buttonColor. Sets the CSS custom property --sf-primary (hex colours only; anything else is ignored).
format ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
secondaryColorstringusedSecondary colour. Sets the CSS custom property --sf-secondary (hex colours only; anything else is ignored).
format ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
accentColorstringusedAccent colour. Sets the CSS custom property --sf-accent (hex colours only; anything else is ignored).
format ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
textColorstringusedBody text colour. Sets the CSS custom property --sf-ink (hex colours only; anything else is ignored).
format ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
surfaceColorstringusedCard / panel background. Sets the CSS custom property --sf-surface (hex colours only; anything else is ignored).
format ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
mutedSurfaceColorstringusedMuted background for alternate sections. Sets the CSS custom property --sf-muted-surface (hex colours only; anything else is ignored).
format ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
onPrimaryColorstringusedText colour on top of the primary colour. Sets the CSS custom property --sf-on-primary (hex colours only; anything else is ignored).
format ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
fontFamilystringusedBody font stack. Sets --sf-font-body. Must match ^[A-Za-z0-9 ,'"-]{1,160}$ (no url() or semicolons).
format ^[A-Za-z0-9 ,'"-]{1,160}$
headingFontstringusedHeading font stack. Sets --sf-font-heading.
format ^[A-Za-z0-9 ,'"-]{1,160}$
displayFontstringusedDisplay font stack. Sets --sf-font-display.
format ^[A-Za-z0-9 ,'"-]{1,160}$
radiusstringusedCorner radius such as "8px" (1–2 digits + px). Sets --sf-radius.
format ^\d{1,2}px$
homeobjectusedHome page switches read by the storefront engine.
showHerobooleantrueusedSet to false to hide #heroSlider.
showFeaturedbooleantrueusedSet to false to skip loading featured products into #homeFeaturedGrid.
showLatestProductsbooleantrueusedSet to false to skip loading #homeProductsGrid.
showCategoriesbooleantrueusedSet to false to hide #homeCategoriesSection.
showBrandsbooleantrueusedSet to false to hide #homeBrandsSection.
productsPerSectionnumber8usedHow many products the home grids request.
productsobjectusedProducts page filter switches.
productsPerPagenumber20not used by the shopNot read by the storefront engine (it always requests 20 per page).
showFiltersbooleantruenot used by the shopNot read by the storefront engine.
showBrandFilterbooleantrueusedSet to false to hide the brand filter (#brandSelect).
showCategoryFilterbooleantrueusedSet to false to hide the category filter (#categorySelect).
showSubcategoryFilterbooleantrueusedSet to false to hide the subcategory filter (#subcategorySelect).
shippingobjectusedDelivery options the template allows. The server combines them with the store settings and delivery areas.
enabledbooleantrueusedSet to false to disable delivery choices entirely.
storePickupEnabledbooleantrueusedOffer "Store Pickup" at checkout.
storePickupFeenumber0usedFee charged for store pickup, in the store currency.
standardDeliveryEnabledbooleantrueusedOffer delivery to an address (also needs delivery areas in the store data).
paymentobjectusedPayment switches applied on the server when listing payment methods.
enabledbooleantrueusedSet to false to disable online payment methods.
cashOnDeliveryEnabledbooleantrueusedSet to false to hide Cash on Delivery.
securityobjectusedPresent in existing templates. Only captcha.minFormTimeMs is passed to the browser config; nothing here is read by engine.js (CAPTCHA is decided by the server).
captchaobjectusedCAPTCHA settings.
enabledbooleantrueignoredNot read — the browser config always receives enabled:false and the server decides when CAPTCHA is required.
loginbooleantrueignoredNot read.
registrationbooleantrueignoredNot read.
typestring"server"ignoredNot read.
minFormTimeMsnumber1500not used by the shopCopied to the browser config; not read by engine.js.
legalobjectusedText of the legal pages rendered into #termsContent, #refundContent and #privacyContent. Plain text; blank lines start paragraphs; "{STORE_NAME}" is replaced with the store name.
termsstring""usedTerms & Conditions.
refundPolicystring""usedRefund policy.
privacyPolicystring""usedPrivacy policy.
socialobjectusedSocial profile links shown in #footerSocialLinks. Only https:// URLs are rendered; empty values are skipped.
facebookstring""usedFacebook URL.
instagramstring""usedInstagram URL.
twitterstring""usedTwitter URL.
x-twitterstring""usedX URL.
tiktokstring""usedTikTok URL.
linkedinstring""usedLinkedIn URL.
youtubestring""usedYouTube URL.
pintereststring""usedPinterest URL.
whatsappstring""usedWhatsApp URL.
footerobjectusedCopied to the browser config; engine.js does not read these switches (hide footer parts with your own HTML/CSS).
showSocialLinksbooleantruenot used by the shopNot read by engine.js.
showPaymentIconsbooleantruenot used by the shopNot read by engine.js.
showLegalLinksbooleantruenot used by the shopNot read by engine.js.
featuresobjectusedFeature switches read by the storefront engine.
wishlistbooleantrueusedSet to false to remove wishlist buttons from product cards and the product page.
featuredProductsbooleantrueusedSet to false to stop loading featured products.
shopByCategorybooleantrueusedSet to false to hide the home category grid.
shopByBrandbooleantrueusedSet to false to hide the home brand grid.
couponsbooleantrueusedSet to false to hide the coupon box in the cart.
reviewsbooleantruenot used by the shopNot read by engine.js.
guestCartbooleantruenot used by the shopNot read by engine.js.
contentobjectusedOptional merchandising content. The server validates it (store/theme-assets.js publicContent) and blocks that have no content are hidden by the engine.
announcementstring""usedText for [data-sf-announcement] / .announcement-bar (max 180 characters).
max 180 characters
heroSlidesarrayusedReplaces the slides inside #heroSlider (max 5). The first .hero-slide in your HTML is used as the slide template.
max 5 items
eyebrowstring""usedSmall text above the title (max 80).
max 80 characters
titlestring""usedSlide title (required, max 120). Slides without a title are dropped.
max 120 characters, required
textstring""usedParagraph (max 220).
max 220 characters
ctastring""usedButton text (max 40).
max 40 characters
linkstring"#products"usedButton link: a storefront route such as "#products" or a same-site path "/…". Anything else becomes "#products".
imagestring""usedBackground image: /image/…, /assets/… or /uploads/… path to a png/jpg/webp/svg/gif.
promotionsarrayusedPromotion cards for .promo-banner / .two-col-banner / [data-sf-promo] items (max 6). Without promotions the engine fills these slots with the store's categories.
max 6 items
eyebrowstring""usedSmall text (max 60).
max 60 characters
titlestring""usedTitle (required, max 80).
max 80 characters, required
textstring""usedText (max 160).
max 160 characters
ctastring""usedLink text (max 30).
max 30 characters
linkstring""usedStorefront route or same-site path.
imagestring""used/image/…, /assets/… or /uploads/… image path.
categorystring""usedCategory name: the card links to that category.
max 80 characters
uspsarrayusedService highlights for [data-sf-usps] / .usp-strip (max 6). Without them the engine shows facts from the selected store (pickup, delivery, hours, payments, phone).
max 6 items
iconstring"check"usedFont Awesome icon name without "fa-" (e.g. "truck-fast").
format ^[a-z0-9-]{2,40}$
titlestring""usedTitle (required, max 60).
max 60 characters, required
textstring""usedText (max 120).
max 120 characters
testimonialsarrayusedQuotes for [data-sf-testimonials] / .testimonial-section (max 8). The section stays hidden when empty: the engine never invents reviews.
max 8 items
quotestring""usedQuote (required, max 400).
max 400 characters, required
namestring""usedName (required, max 60).
max 60 characters, required
rolestring""usedRole / location (max 60).
max 60 characters
newsletterbooleanfalseusedShow newsletter blocks (.newsletter-section, [data-sf-section="newsletter"], .footer-newsletter). Hidden unless true.
labelsobjectusedOverrides for the words the engine uses (merged over script.js StorefrontTheme.labels). Keys are listed in the Runtime API section.
assetsobjectusedShared assets loaded by the page head.
kitbooleanfalseusedtrue loads /assets/storefront/kit.css (the layout kit used by the newer templates).
fontsarray[]usedSelf-hosted fonts to load (keys of /assets/fonts/<key>.css that exist in the application).
template.json — example
{
    "displayName": "Sunny Market",
    "version": "1.0.0",
    "website": { "description": "Fresh food from your neighbourhood" },
    "branding": { "primaryColor": "#0b6e4f", "accentColor": "#f2a541" },
    "assets": { "kit": true, "fonts": ["manrope"] },
    "content": {
        "announcement": "Free delivery on orders over ₦20,000",
        "heroSlides": [
            { "title": "Fresh every morning", "text": "Fruit and vegetables from local farms.", "cta": "Shop now", "link": "#products", "image": "/image/hero-1.jpg" }
        ]
    },
    "labels": { "cart": "Basket" }
}

theme.json

Optional installation metadata. The application reads it (if present) to match pos_setting.theme.activeThemeId / activeThemeName to this template and to report the installed version. It does not affect styling.

KeyMeaning
idPlatform template id (e.g. "TPL-…"). activeThemeId may match it.
nameDisplay name. activeThemeName may match it.
slugSlug. activeThemeId may match it; the admin "switch" stores it as activeThemeId.
versionInstalled version (wins over template.json version).
previewImagePreview image URL shown in the admin template list.
sourceUrlNot read by the application. (ignored)
installedAtNot read by the application (written by the platform installer). (ignored)
descriptionNot read by the application. (ignored)
theme.json
{
  "name": "Sunny Market",
  "slug": "sunny-market",
  "version": "1.0.0"
}

Checklist before you send

Go through this list — these are the things that break a template in the store.

  • The folder name uses only letters, digits, - and _, and matches theme.json → slug.
  • template.json exists and is valid JSON (paste it into any JSON checker).
  • index.html has no <head> content you rely on, and no <script>, <style>, <link>, <iframe> or on…= attributes — they are removed.
  • Every <!-- IF --> has its <!-- ENDIF -->, every FOREACH its ENDFOREACH, every LOOP its ENDLOOP — one missing and the template does not load.
  • Placeholders are spelled exactly as in the list (capitals, braces); store values are wrapped in <!-- IF … -->.
  • There is a #section-home with class app-section active, and every data-nav link points to a page your template has.
  • Each id appears only once in index.html.
  • For every feature you included, all its elements are present (see the notes in Storefront features). If the shop has several branches, the store chooser elements ([data-sf-store-gate], [data-sf-store-pill]) are in place.
  • Images are in image/, of an allowed type, and used as /image/… — also inside CSS url().
  • No fonts, images, scripts or styles from other websites; fonts come from the store's list.
  • Brand colours in template.json are hex (#0b6e4f or #fff) — other formats are ignored.
  • script.js avoids eval, new Function, document.write, string timers and loading code or data from other websites.
  • The page works on a phone (about 390 px wide) without sideways scrolling.
  • theme.json → version is raised for every new version you send.
All 62 rules the store's checks use
LevelRule
Must fix… does not exist in image/.
Must fixurl(…) resolves against /templates/<name>/…, which the application does not serve. Use an absolute /image/… path.
Must fixTemplate engine:
Must fixTemplate engine:
Must fixJavaScript syntax error:
Must fixtemplate.json is not valid JSON:
Must fixtemplate.json must contain a JSON object.
Must fix… is missing.
Must fixInstall name "…" is not allowed by the application (…).
Must fix<script> elements are removed by the application. Put JavaScript in script.js.
Must fix<style> elements are removed by the application. Put CSS in styles.css.
Should fixdata-action="…" is not handled by the storefront engine (handle it in script.js).
Should fix… … has … items; the application uses the first ….
Should fix… is … MB. Large images slow the storefront down.
Should fix… will not be served: the application only serves … files from image/ (no hidden files).
Should fixBoth style.css and styles.css exist. The page links /style.css, which serves style.css, so styles.css is ignored by the storefront page.
Should fixbehavior: is removed by the application.
Should fix-moz-binding: is removed by the application.
Should fixexpression() is removed by the application.
Should fixurl(…) is replaced with "none" by the application (no external URLs in CSS).
Should fix@import is removed by the application. Combine the CSS into this file; for fonts use template.json assets.fonts.
Should fixThe application changes parts of this stylesheet when serving it (sanitizeCss).
Should fixThe application's CSS sanitizer removes every "behavior:" declaration, which also breaks "scroll-behavior:" (it is served as a dangling "scroll-"). Set smooth scrolling from script.js instead, e.g. document.documentElement.style.scrollBehavior = "smooth".
Should fix<!-- … … -->: "…" is not provided by the application (always empty/false).
Should fixid="…" is used more than once; the engine only finds the first.
Should fix… is present but … element(s) the engine uses with it are missing: …. All … installed templates that implement … have them.
Should fix… …: font "…" is not installed in the application (available: …). It is ignored.
Should fixCross-origin form actions are removed by the application (forms may only post to the store itself).
Should fix#… is created by the storefront engine; defining it in the template causes duplicates.
Should fixEverything inside <head> is discarded by the application (title, meta, links). The application writes its own head.
Should fixsrc="…" is relative to the page URL and will not find a template file. Use image/… or /image/….
Should fix… …[…] has no "…", so the application drops this item.
Should fixThe application rewrites this line when serving script.js (… is not allowed), so it will not work as written.
Should fix… labels.… should be a string.
Should fixThere is no #section-home: unknown routes fall back to "home", so the page would show no section.
Should fix… … should be ≥ ….
Should fix…="…" is not a storefront route (…); the engine shows the home page instead.
Should fix…="…" links to a route this template does not implement (no #section-…); the engine shows the home page.
Should fixstyle attributes containing external url() are removed by the application.
Should fix{…} only has a value inside a … block; here it stays as literal text.
Should fix{…} is not a placeholder the application provides, so it appears literally on the page.
Should fix…="……" is replaced with "#" by the application.
Should fixsrcdoc is removed by the application.
Should fix…="…" is removed by the application. Bind events in script.js (or use data-action / data-nav).
Should fix<script type="
Should fix<…> elements are removed by the application.
Should fix… … "…" does not match …, so the application ignores it.
Should fix… … contains markup/script text that the application removes.
Should fix… … is … characters; the application cuts it to ….
Good to know… is not referenced by index.html, styles.css, script.js or template.json (it is still served at … and listed in {TEMPLATE_IMAGES} when it is directly inside image/).
Good to know<…> tags are removed; your markup becomes the content of the page body built by the application.
Good to know… is not used by the application… and is left out of builds.
Good to know… is loaded by the template engine but never rendered or served (only index.html, styles.css/style.css and script.js are used).
Good to know<img> without src.
Good to knowExternal image … is loaded through the application's image proxy (/img-proxy). Prefer files in image/.
Good to knowscript.js does not set window.StorefrontTheme (optional: labels, icons, colour and hooks for the storefront engine).
Good to know… …: …
Good to know… … is not read by the application.
Good to know… labels.… is not a word the engine uses (known: …).
Good to know{{{…}}} prints the value without HTML escaping (the page is sanitized afterwards).
Good to know{…} is empty until a store is selected (and when the store has no value). Wrap it in <!-- IF … -->…<!-- ENDIF --> to avoid empty markup.
Good to knowtheme.json version (…) and template.json version (…) differ; the application reports theme.json's.

Delivering your template

  1. Zip the folder (not just the files inside): the zip must contain exactly one folder named like your template, with template.json directly in it.
    Zip contents
    sunny-market-1.0.0.zip
    └── sunny-market/
        ├── index.html
        ├── template.json
        ├── styles.css
        ├── script.js
        ├── theme.json
        └── image/…

    Windows: right-click the folder → Send to → Compressed (zipped) folder. macOS: right-click → Compress. Leave out anything that isn't part of the template (notes, design files, .DS_Store).

  2. Send the zip to the store owner with the version number and what changed.

For the store owner: installing

  1. Copy the template folder to <app>/templates/<name>/ (name: letters, digits, "-" and "_").
  2. Load it: restart the application, or (signed in as admin) POST /api/templates/reload {"templateName":"<name>"}.
  3. Activate it: set pos_setting.theme.activeThemeId to the folder name / theme.json slug / theme.json id, or (admin) POST /api/templates/switch {"theme":"<name>"}.

The active template is found by matching activeThemeId against the folder name, theme.json slug or theme.json id, then activeThemeName against folder name, slug or name. If nothing matches, the first installed template (alphabetically) is used.

Common problems

What you seeWhy, and the fix
The page shows {SOMETHING}The placeholder name is misspelled or doesn't exist — see Placeholders.
The template doesn't load at all / the old one staysUsually an unbalanced IF/ENDIF block or invalid template.json, or a folder name with spaces or other characters.
No products appearWith several branches the shopper must choose a store first — include the store chooser elements. Check that the product grid keeps its id (e.g. #productsGrid, #homeFeaturedGrid).
My button with onclick does nothingEvent attributes are removed. Use data-action or script.js.
My <script> or <style> in index.html is goneThey are removed. Put code in script.js and styles in styles.css.
Background image missingUse url(/image/…) with the leading slash; external images are blocked.
My Google Font doesn't loadExternal fonts are blocked. Use a font from the store's list.
Smooth scrolling doesn't workscroll-behavior is removed by the store; use script.js (element.scrollIntoView({behavior: 'smooth'})).
A page link opens the home pageYour template has no #section-… for that page.
Store phone/address are emptyThey are empty until a store is chosen, and in shops without branches. Wrap them in <!-- IF STORE_PHONE -->.
Colours from template.json have no effectOnly hex colours are accepted, and your CSS must use the variables (var(--sf-primary)).

Appendix: every storefront element

All 201 ids, classes and attributes the storefront engine uses, by feature.

Pages and navigation

ElementPurpose
.app-sectionEvery route container. Only the active one should be visible (your CSS: .app-section{display:none} .app-section.active{display:block}).
.main-navNavigation container whose .nav-link items are de-activated on route change.
.nav-linkNavigation link; gets class "active" for the current route when it has data-section.
.nav-profile-itemShown only when a customer is signed in.
#mainNavMain navigation. Gets class "open" when #mobileMenuBtn is pressed.
#mobileMenuBtnMenu toggle button (aria-expanded is kept in sync; body gets class "sf-nav-open").
#mobileNavOptional separate mobile navigation (takes precedence over #mainNav for the menu button).
#section-cartCart (route "cart").
#section-checkoutCheckout (route "checkout").
#section-featuredFeatured products (route "featured").
#section-homeHome page (route "home"). Also the fallback for unknown routes.
#section-privacy-policyPrivacy policy (route "privacy-policy").
#section-product-detailSingle product (route "product-detail").
#section-productsProduct list with filters (route "products").
#section-profileAccount pages (route "profile"; shows the login modal when signed out).
#section-refund-policyRefund policy (route "refund-policy").
#section-termsTerms page (route "terms").
#section-wishlistSaved items (route "wishlist").

Header counters, account and search

ElementPurpose
#cartCountNumber of items in the cart (class "sf-empty-count" when zero).
#searchCloseCloses the search overlay.
#searchContainerSearch wrapper toggled with class "open"/"active" by #searchToggleBtn.
#searchInputSearch box. Typing shows suggestions; Enter searches the products page.
#searchOverlayFull-screen search overlay (used instead of #searchPanel when present).
#searchPanelOptional dropdown panel toggled together with #searchContainer.
#searchSuggestionsSuggestion list container (class "active" when open).
#searchToggleAlternative id for the search toggle button.
#searchToggleBtnOpens/closes the search panel.
#userMenuReplaced with "Log in / Register" buttons or the signed-in customer's name, account and logout buttons.
#wishlistCountNumber of saved items.

Store selection

ElementPurpose
[data-sf-store-dependent]Hidden until a store is selected (use it on anything that only makes sense for a store).
[data-sf-store-gate]Where the full-width store chooser is inserted. Without it the chooser goes after the hero (#heroSlider/.hero/[data-sf-hero]) or at the top of #section-home.
[data-sf-store-pill]Where the "Shopping at … / Change" button goes. Without it, it is prepended to .header-actions (or similar).
#sfStoreGate made by the storeGenerated by the engine — do not add it yourself.
#sfStoreModal made by the storeGenerated by the engine — do not add it yourself.
#sfStorePill made by the storeGenerated by the engine — do not add it yourself.

Home page blocks

ElementPurpose
.announcement-barAlternative announcement bar marker.
.footer-newsletterNewsletter block in the footer.
.hero-slideOne slide inside #heroSlider.
.home-featuredWrapper of #homeFeaturedGrid; hidden until a store is chosen and when empty.
.home-productsWrapper of #homeProductsGrid.
.newsletter-sectionNewsletter block (shown when content.newsletter is true). A form inside with an email input subscribes.
.promo-bannersPromotion slots (.promo-banner children). Filled from content.promotions or the store's categories.
.testimonial-sectionTestimonials wrapper (hidden when there are none).
.two-col-bannersTwo promotion slots (.two-col-banner children).
.usp-stripAlternative marker for service highlights.
[data-sf-announcement]Announcement bar filled from content.announcement (hidden when empty).
[data-sf-category-chips]Category links ("chips"). Add data-sf-chip-images for thumbnails; wrap in [data-sf-chips-wrap] to hide the wrapper when empty.
[data-sf-chip-images]Part of [data-sf-category-chips] (home page blocks).
[data-sf-chips-wrap]Part of [data-sf-category-chips] (home page blocks).
[data-sf-hero]Marks a hero element (used to place the store chooser after it).
[data-sf-newsletter]Newsletter form marker.
[data-sf-promo]One promotion slot.
[data-sf-promos]Generic promotion container ([data-sf-promo] children).
[data-sf-section]Part of [data-sf-testimonials] (home page blocks).
[data-sf-stats]Live numbers for the store (products, categories, brands, open now).
[data-sf-testimonials]Testimonial track (inside .testimonial-section / [data-sf-section="testimonials"]). Only content.testimonials is shown.
[data-sf-ticker]Scrolling strip of category names.
[data-sf-usps-class]Part of [data-sf-usps] (home page blocks).
[data-sf-usps-list]Part of [data-sf-usps] (home page blocks).
[data-sf-usps-max]Part of [data-sf-usps] (home page blocks).
[data-sf-usps]Service highlights. data-sf-usps="feature" renders .feature-card items; data-sf-usps-class sets the item class; data-sf-usps-max the count; [data-sf-usps-list] the inner target.
#heroDotsDot buttons generated for each slide.
#heroPaymentLineText replaced with the store's payment methods.
#heroSliderSlider. Children .hero-slide (first one active), buttons [data-action="hero-prev"/"hero-next"], dots in #heroDots. content.heroSlides in template.json replaces the slides.
#homeAnimalsGridSecondary category showcase (icon cards).
#homeAnimalsSectionWrapper of #homeAnimalsGrid.
#homeBrandsGridBrand tiles (shown when the store has 2+ brands).
#homeBrandsSectionWrapper of #homeBrandsGrid.
#homeCategoriesGridCategory tiles.
#homeCategoriesSectionWrapper of #homeCategoriesGrid.
#homeFeaturedGridFeatured product cards.
#homeProductsGridNewest product cards.
#homeRecentlyViewedRecently viewed products (from this browser, per store). Put a .products-grid inside.
#megaBrandsListBrand links inside a mega menu.
#megaCategoriesListCategory links inside a mega menu.
#testimonialDotsTestimonial dots.

Products page

ElementPurpose
.filter-sidebarAlternative filter drawer marker.
#applyFiltersBtnApplies filters (filters also apply instantly unless StorefrontTheme.instantFilters is false).
#brandSelect<select> of brands.
#categorySelect<select> of categories (first option value "all").
#clearFiltersBtnClears filters.
#featuredGridFeatured products page grid.
#featuredStoreRequiredMessage area on the featured page when no store is selected.
#filterToggleMobileOpens the filter panel on small screens.
#paginationPage buttons.
#priceRange<input type="range"> maximum price.
#priceRangeLabelShows the chosen maximum price.
#productDetailContainerFilled with the product page (gallery, price, variants, quantity, add to cart, related products).
#productsFiltersSectionFilter panel (class "mobile-open" when opened on small screens).
#productsGridProduct cards for the current page.
#productsStoreRequiredMessage area shown when no store is selected.
#resultsCountNumber of products shown.
#resultsCounterWrapper of the results count.
#sortSelect<select> with values default, newest, price-asc, price-desc, name-asc, name-desc, rating.
#subcategorySelect<select> of subcategories (enabled after a category is chosen).
#totalCountTotal number of matching products.
#wishlistContainerFilled with saved items.

Cart

ElementPurpose
#cartContainerCart contents.
#stickyCartCountItem count in the sticky bar.
#stickyCartTotalTotal in the sticky bar.
#stickyOrderBarOptional sticky bar with #stickyCartCount and #stickyCartTotal.

Checkout

ElementPurpose
.checkout-contentWrapper of the step panels (the order summary is inserted next to it).
.checkout-step-contentOne step panel (class "active" when shown).
.checkout-stepsProgress indicator; children .step[data-step] get classes active/completed/reachable.
[data-action="checkout-goto"]Jump to the step in data-step.
[data-action="checkout-next"]Next step button.
[data-action="checkout-prev"]Previous step button.
[data-step]Part of .checkout-steps (checkout).
#agreeTermsTerms checkbox required before placing the order.
#billingFormStep 2 form with #sameAsShipping and the #differentBilling fields.
#checkoutPersistenceBadge"Your checkout progress has been restored" notice.
#differentBillingPart of #billingForm (checkout).
#discountRowPart of #reviewSubtotal (checkout).
#paymentDetailsContainerPayment instructions for the chosen method.
#paymentMethodsStep 4: payment methods.
#placeOrderBtnPlaces the order.
#reviewBillingPart of #reviewItems (checkout).
#reviewDiscountPart of #reviewSubtotal (checkout).
#reviewItemsStep 5: order lines (with #reviewShipping, #reviewBilling, #reviewPayment).
#reviewPaymentPart of #reviewItems (checkout).
#reviewShippingPart of #reviewItems (checkout).
#reviewShippingCostPart of #reviewSubtotal (checkout).
#reviewSubtotalTotals: #reviewSubtotal #reviewDiscount #reviewShippingCost #reviewTax #reviewTotal (#discountRow, #summaryNote).
#reviewTaxPart of #reviewSubtotal (checkout).
#reviewTotalPart of #reviewSubtotal (checkout).
#sameAsShippingPart of #billingForm (checkout).
#sfCheckoutBlocked made by the storeGenerated by the engine.
#sfCheckoutSummary made by the storeGenerated by the engine.
#sfOrderConfirmation made by the storeGenerated by the engine.
#shipAddress1Part of #shippingForm (checkout).
#shipAddress2Part of #shippingForm (checkout).
#shipCityPart of #shippingForm (checkout).
#shipCountryPart of #shippingForm (checkout).
#shipEmailPart of #shippingForm (checkout).
#shipFullNamePart of #shippingForm (checkout).
#shipPhonePart of #shippingForm (checkout).
#shippingFeeHintPart of #shippingLocationContainer (checkout).
#shippingFormStep 1 form: #shipFullName #shipEmail #shipPhone #shipAddress1 #shipAddress2 #shipCity #shipState #shipPostalCode #shipCountry.
#shippingLocationContainerDelivery area pickers #shippingLocationSelect and #shippingSublocationSelect, and #shippingFeeHint.
#shippingLocationSelectPart of #shippingLocationContainer (checkout).
#shippingMethodsStep 3: delivery options.
#shippingSublocationSelectPart of #shippingLocationContainer (checkout).
#shipPostalCodePart of #shippingForm (checkout).
#shipStatePart of #shippingForm (checkout).
#summaryNotePart of #reviewSubtotal (checkout).

Account, login and registration

ElementPurpose
.modalAny modal; clicking its backdrop closes it.
.profile-tabProfile tab buttons (data-tab="info|orders|addresses|activity|security").
.profile-tab-contentTab panels with ids profile-tab-<tab>.
[data-action="close-modal"]Closes the modal named in data-modal (or the closest .modal).
[data-action="logout"]Signs out.
[data-action="show-login"]Opens the login modal.
[data-action="show-register"]Opens the register modal.
#addrCountryPart of #addressModal (account, login and registration).
#addressFormPart of #addressModal (account, login and registration).
#addressModalAddress editor (#addressForm with #addrId #addrFullName … #addrCountry).
#addrFullNamePart of #addressModal (account, login and registration).
#addrIdPart of #addressModal (account, login and registration).
#changePasswordFormPassword form (#currentPassword #newPassword #confirmPassword).
#confirmPasswordPart of #changePasswordForm (account, login and registration).
#currentPasswordPart of #changePasswordForm (account, login and registration).
#loginFormPart of #loginModal (account, login and registration).
#loginModalLogin modal containing #loginForm (#loginUsername, #loginPassword).
#loginPasswordPart of #loginModal (account, login and registration).
#loginUsernamePart of #loginModal (account, login and registration).
#newPasswordPart of #changePasswordForm (account, login and registration).
#profileActivityRecent activity.
#profileAddressesSaved addresses.
#profileCurrencyPart of #profileName (account, login and registration).
#profileEmailPart of #profileName (account, login and registration).
#profileNameProfile fields: #profileName #profileUsername #profileEmail #profileCurrency.
#profileOrdersOrder history.
#profileUsernamePart of #profileName (account, login and registration).
#registerCaptchaContainerPart of #registerModal (account, login and registration).
#registerConfirmPasswordPart of #registerModal (account, login and registration).
#registerEmailPart of #registerModal (account, login and registration).
#registerFormPart of #registerModal (account, login and registration).
#registerModalRegister modal containing #registerForm (#registerName #registerUsername #registerEmail #registerPhone #registerPassword #registerConfirmPassword, honeypot #registerWebsite, #registerCaptchaContainer).
#registerNamePart of #registerModal (account, login and registration).
#registerPasswordPart of #registerModal (account, login and registration).
#registerPhonePart of #registerModal (account, login and registration).
#registerUsernamePart of #registerModal (account, login and registration).
#registerWebsitePart of #registerModal (account, login and registration).

Legal pages and footer

ElementPurpose
[data-sf-payments]Payment badges marker.
[data-sf-social]Wrapper hidden together with #footerSocialLinks.
#footerPaymentIconsPayment method badges.
#footerSocialLinksSocial links (hidden when none are configured).
#privacyContentPrivacy policy text.
#refundContentRefund policy text.
#termsContentTerms text.

Generated by the engine

ElementPurpose
[data-sf-hide-on-error]Images with this attribute are hidden (instead of replaced by a placeholder) when they fail to load.
[data-sf-img] made by the storeSet on images rendered by the engine.
[data-sf-link] made by the storeSet by the engine on hero buttons configured in content.heroSlides.
[data-sf-state] made by the storeSet on sections by the engine: loading / ready / empty / needs-store (style hidden states with it).
#couponInput made by the storeCoupon field inside the cart.
#pdMainImageWrap made by the storeProduct page gallery (inside #productDetailContainer).
#pdQty made by the storeProduct page quantity input (with #pdQtyDown / #pdQtyUp).
#pdQtyDown made by the storeProduct page quantity button.
#pdQtyUp made by the storeProduct page quantity button.
#sfRecentWrap made by the storeRecently viewed block on the product page.
#sfRelated made by the storeRelated products block on the product page.
#sfToastStack made by the storeToast notifications.