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 write | The store does |
|---|---|
| index.html — the page layout and text | fills in the store's data (products, cart, checkout, account…) using the element ids and classes described in this guide |
| styles.css — the look | adds shared styles, fonts and your brand colours before it |
| script.js (optional) — small extras | runs it before the storefront engine |
| template.json — settings: colours, fonts, texts, banners | turns them into CSS variables and page content |
| image/ — your pictures | serves them at /image/… |
Rules in this guide come from the store's own code (love-ecommerce-template 1.0.0) and its 15 installed templates.
Quick start
- Download a starter and unzip it:
- Rename the folder from
my-templateto your template's name — letters, digits,-and_only (e.g.sunny-market). Put the same name intheme.json→slug. - Edit the files: text and layout in
index.html, look instyles.css, colours and fonts intemplate.json, pictures inimage/. - Check your work with the checklist.
- 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.
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
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) plusimage/. Any other file in the template folder (for example logo.png at the top level) is not served by the application.
| File | Required | What it is |
|---|---|---|
template.json | yes | Configuration. A folder without a readable template.json is skipped by the loader ("Error loading template"). |
index.html | yes | The 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.css | no | 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). |
script.js | no | Template script, served sanitized at /templates/<name>/script.js and loaded (deferred) BEFORE the shared engine, so it can define window.StorefrontTheme. |
theme.json | no | Optional installation metadata (id, slug, name, version, previewImage) used to match the store's configured theme to this folder. |
image/ | no | Images served at /image/<path> for the ACTIVE template (sub-folders allowed). |
How the store builds the page
- render — index.html is rendered by TemplateEngine.render() with the placeholder data (see Data).
- strip-document — <!DOCTYPE>, <html>, <head>…</head> and <body> tags are removed: your markup becomes the body content of a page the application builds.
- 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().
- image-urls — <img src> values are normalised: image/x → /image/x, external URLs → /img-proxy?url=…
- 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.
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.
| Placeholder | Value |
|---|---|
{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} store | Selected store's address line (empty when no store is selected). |
{STORE_CITY} store | Selected store's city. |
{STORE_STATE} store | Selected store's state. |
{STORE_PHONE} store | Selected store's phone. |
{STORE_PHONE_LINK} store | Phone digits for tel: links. |
{STORE_EMAIL} store | Selected store's email. |
{STORE_HOURS} store | Opening 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:
<!-- 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
| Write | Meaning |
|---|---|
<!-- 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). |
<!-- 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".
| Page | Element | Link |
|---|---|---|
| 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"> |
<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
<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).
- Pages and navigation
- Header counters, account and search
- Store selection
- Home page blocks
- Products page
- Cart
- Checkout
- Account, login and registration
- Legal pages and footer
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.
| Element | Purpose | In store templates |
|---|---|---|
.app-section | Every route container. Only the active one should be visible (your CSS: .app-section{display:none} .app-section.active{display:block}). | 15 of 15 |
.main-nav | Navigation container whose .nav-link items are de-activated on route change. | 14 of 15 |
.nav-link | Navigation link; gets class "active" for the current route when it has data-section. | 15 of 15 |
.nav-profile-item | Shown only when a customer is signed in. | 15 of 15 |
#mainNav | Main navigation. Gets class "open" when #mobileMenuBtn is pressed. | 14 of 15 |
#mobileMenuBtn | Menu toggle button (aria-expanded is kept in sync; body gets class "sf-nav-open"). | 15 of 15 |
#mobileNav | Optional separate mobile navigation (takes precedence over #mainNav for the menu button). | 1 of 15 |
#section-cart | Cart (route "cart"). | 15 of 15 |
#section-checkout | Checkout (route "checkout"). | 15 of 15 |
#section-featured | Featured products (route "featured"). | 15 of 15 |
#section-home | Home page (route "home"). Also the fallback for unknown routes. | 15 of 15 |
#section-privacy-policy | Privacy policy (route "privacy-policy"). | 15 of 15 |
#section-product-detail | Single product (route "product-detail"). | 15 of 15 |
#section-products | Product list with filters (route "products"). | 15 of 15 |
#section-profile | Account pages (route "profile"; shows the login modal when signed out). | 15 of 15 |
#section-refund-policy | Refund policy (route "refund-policy"). | 15 of 15 |
#section-terms | Terms page (route "terms"). | 15 of 15 |
#section-wishlist | Saved items (route "wishlist"). | 15 of 15 |
#section-cart, include all of these too (every store template that has it does): #cartContainer#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#section-featured, include all of these too (every store template that has it does): #featuredGrid#section-product-detail, include all of these too (every store template that has it does): #productDetailContainer#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#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#section-wishlist, include all of these too (every store template that has it does): #wishlistContainerMarkup: #section-cart
<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
<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">×</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 & 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>Markup: #section-featured
<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
<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
<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
<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
<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.
| Element | Purpose | In store templates |
|---|---|---|
#cartCount | Number of items in the cart (class "sf-empty-count" when zero). | 15 of 15 |
#searchClose | Closes the search overlay. | 1 of 15 |
#searchContainer | Search wrapper toggled with class "open"/"active" by #searchToggleBtn. | 9 of 15 |
#searchInput | Search box. Typing shows suggestions; Enter searches the products page. | 15 of 15 |
#searchOverlay | Full-screen search overlay (used instead of #searchPanel when present). | 1 of 15 |
#searchPanel | Optional dropdown panel toggled together with #searchContainer. | 7 of 15 |
#searchSuggestions | Suggestion list container (class "active" when open). | 15 of 15 |
#searchToggle | Alternative id for the search toggle button. | 1 of 15 |
#searchToggleBtn | Opens/closes the search panel. | 7 of 15 |
#userMenu | Replaced with "Log in / Register" buttons or the signed-in customer's name, account and logout buttons. | 15 of 15 |
#wishlistCount | Number of saved items. | 15 of 15 |
Markup: #searchContainer
<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
<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.
| Element | Purpose | In 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]
<div class="k-gate-slot" data-sf-store-gate></div>Markup: [data-sf-store-pill]
<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.
| Element | Purpose | In store templates |
|---|---|---|
.announcement-bar | Alternative announcement bar marker. | 2 of 15 |
.footer-newsletter | Newsletter block in the footer. | 1 of 15 |
.hero-slide | One slide inside #heroSlider. | 15 of 15 |
.home-featured | Wrapper of #homeFeaturedGrid; hidden until a store is chosen and when empty. | 14 of 15 |
.home-products | Wrapper of #homeProductsGrid. | 14 of 15 |
.newsletter-section | Newsletter block (shown when content.newsletter is true). A form inside with an email input subscribes. | 8 of 15 |
.promo-banners | Promotion slots (.promo-banner children). Filled from content.promotions or the store's categories. | 6 of 15 |
.testimonial-section | Testimonials wrapper (hidden when there are none). | 6 of 15 |
.two-col-banners | Two promotion slots (.two-col-banner children). | 3 of 15 |
.usp-strip | Alternative 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 |
#heroDots | Dot buttons generated for each slide. | 15 of 15 |
#heroPaymentLine | Text replaced with the store's payment methods. | 3 of 15 |
#heroSlider | Slider. 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 |
#homeAnimalsGrid | Secondary category showcase (icon cards). | 1 of 15 |
#homeAnimalsSection | Wrapper of #homeAnimalsGrid. | 1 of 15 |
#homeBrandsGrid | Brand tiles (shown when the store has 2+ brands). | 13 of 15 |
#homeBrandsSection | Wrapper of #homeBrandsGrid. | 13 of 15 |
#homeCategoriesGrid | Category tiles. | 14 of 15 |
#homeCategoriesSection | Wrapper of #homeCategoriesGrid. | 14 of 15 |
#homeFeaturedGrid | Featured product cards. | 15 of 15 |
#homeProductsGrid | Newest product cards. | 15 of 15 |
#homeRecentlyViewed | Recently viewed products (from this browser, per store). Put a .products-grid inside. | 9 of 15 |
#megaBrandsList | Brand links inside a mega menu. | 1 of 15 |
#megaCategoriesList | Category links inside a mega menu. | 1 of 15 |
#testimonialDots | Testimonial dots. | 6 of 15 |
#heroSlider, include all of these too (every store template that has it does): #heroDotsMarkup: [data-sf-announcement]
<div class="announcement-bar sf-hidden" data-sf-announcement>
<div class="container">
<p class="announcement-text"></p>
</div>
</div>Markup: [data-sf-category-chips]
<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]
<div data-sf-stats class="sf-hidden"></div>Markup: [data-sf-ticker]
<div class="k-ticker k-ticker--top sf-hidden" data-sf-ticker></div>Markup: [data-sf-usps]
<div class="usp-strip" data-sf-usps aria-label="Why shop with us"></div>Markup: #heroSlider
<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 & 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
<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
<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
<div id="homeFeaturedGrid" class="products-grid" aria-live="polite"></div>Markup: #homeProductsGrid
<div id="homeProductsGrid" class="products-grid" aria-live="polite"></div>Markup: #homeRecentlyViewed
<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.
| Element | Purpose | In store templates |
|---|---|---|
.filter-sidebar | Alternative filter drawer marker. | 1 of 15 |
#applyFiltersBtn | Applies 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 |
#clearFiltersBtn | Clears filters. | 15 of 15 |
#featuredGrid | Featured products page grid. | 15 of 15 |
#featuredStoreRequired | Message area on the featured page when no store is selected. | 10 of 15 |
#filterToggleMobile | Opens the filter panel on small screens. | 9 of 15 |
#pagination | Page buttons. | 15 of 15 |
#priceRange | <input type="range"> maximum price. | 15 of 15 |
#priceRangeLabel | Shows the chosen maximum price. | 15 of 15 |
#productDetailContainer | Filled with the product page (gallery, price, variants, quantity, add to cart, related products). | 15 of 15 |
#productsFiltersSection | Filter panel (class "mobile-open" when opened on small screens). | 10 of 15 |
#productsGrid | Product cards for the current page. | 15 of 15 |
#productsStoreRequired | Message area shown when no store is selected. | 10 of 15 |
#resultsCount | Number of products shown. | 15 of 15 |
#resultsCounter | Wrapper 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 |
#totalCount | Total number of matching products. | 15 of 15 |
#wishlistContainer | Filled with saved items. | 15 of 15 |
Cart
The engine renders the whole cart (lines, coupon, totals) into #cartContainer.
| Element | Purpose | In store templates |
|---|---|---|
#cartContainer | Cart contents. | 15 of 15 |
#stickyCartCount | Item count in the sticky bar. | 1 of 15 |
#stickyCartTotal | Total in the sticky bar. | 1 of 15 |
#stickyOrderBar | Optional 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.
| Element | Purpose | In store templates |
|---|---|---|
.checkout-content | Wrapper of the step panels (the order summary is inserted next to it). | 15 of 15 |
.checkout-step-content | One step panel (class "active" when shown). | 15 of 15 |
.checkout-steps | Progress 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 |
#agreeTerms | Terms checkbox required before placing the order. | 15 of 15 |
#billingForm | Step 2 form with #sameAsShipping and the #differentBilling fields. | 15 of 15 |
#checkoutPersistenceBadge | "Your checkout progress has been restored" notice. | 10 of 15 |
#differentBilling | Part of #billingForm (checkout). | 15 of 15 |
#discountRow | Part of #reviewSubtotal (checkout). | 15 of 15 |
#paymentDetailsContainer | Payment instructions for the chosen method. | 15 of 15 |
#paymentMethods | Step 4: payment methods. | 15 of 15 |
#placeOrderBtn | Places the order. | 15 of 15 |
#reviewBilling | Part of #reviewItems (checkout). | 15 of 15 |
#reviewDiscount | Part of #reviewSubtotal (checkout). | 15 of 15 |
#reviewItems | Step 5: order lines (with #reviewShipping, #reviewBilling, #reviewPayment). | 15 of 15 |
#reviewPayment | Part of #reviewItems (checkout). | 15 of 15 |
#reviewShipping | Part of #reviewItems (checkout). | 15 of 15 |
#reviewShippingCost | Part of #reviewSubtotal (checkout). | 15 of 15 |
#reviewSubtotal | Totals: #reviewSubtotal #reviewDiscount #reviewShippingCost #reviewTax #reviewTotal (#discountRow, #summaryNote). | 15 of 15 |
#reviewTax | Part of #reviewSubtotal (checkout). | 15 of 15 |
#reviewTotal | Part of #reviewSubtotal (checkout). | 15 of 15 |
#sameAsShipping | Part of #billingForm (checkout). | 15 of 15 |
#shipAddress1 | Part of #shippingForm (checkout). | 15 of 15 |
#shipAddress2 | Part of #shippingForm (checkout). | 15 of 15 |
#shipCity | Part of #shippingForm (checkout). | 15 of 15 |
#shipCountry | Part of #shippingForm (checkout). | 15 of 15 |
#shipEmail | Part of #shippingForm (checkout). | 15 of 15 |
#shipFullName | Part of #shippingForm (checkout). | 15 of 15 |
#shipPhone | Part of #shippingForm (checkout). | 15 of 15 |
#shippingFeeHint | Part of #shippingLocationContainer (checkout). | 15 of 15 |
#shippingForm | Step 1 form: #shipFullName #shipEmail #shipPhone #shipAddress1 #shipAddress2 #shipCity #shipState #shipPostalCode #shipCountry. | 15 of 15 |
#shippingLocationContainer | Delivery area pickers #shippingLocationSelect and #shippingSublocationSelect, and #shippingFeeHint. | 15 of 15 |
#shippingLocationSelect | Part of #shippingLocationContainer (checkout). | 15 of 15 |
#shippingMethods | Step 3: delivery options. | 15 of 15 |
#shippingSublocationSelect | Part of #shippingLocationContainer (checkout). | 15 of 15 |
#shipPostalCode | Part of #shippingForm (checkout). | 15 of 15 |
#shipState | Part of #shippingForm (checkout). | 15 of 15 |
#summaryNote | Part 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.
| Element | Purpose | In store templates |
|---|---|---|
.modal | Any modal; clicking its backdrop closes it. | 15 of 15 |
.profile-tab | Profile tab buttons (data-tab="info|orders|addresses|activity|security"). | 15 of 15 |
.profile-tab-content | Tab 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 |
#addrCountry | Part of #addressModal (account, login and registration). | 15 of 15 |
#addressForm | Part of #addressModal (account, login and registration). | 15 of 15 |
#addressModal | Address editor (#addressForm with #addrId #addrFullName … #addrCountry). | 15 of 15 |
#addrFullName | Part of #addressModal (account, login and registration). | 15 of 15 |
#addrId | Part of #addressModal (account, login and registration). | 15 of 15 |
#changePasswordForm | Password form (#currentPassword #newPassword #confirmPassword). | 15 of 15 |
#confirmPassword | Part of #changePasswordForm (account, login and registration). | 15 of 15 |
#currentPassword | Part of #changePasswordForm (account, login and registration). | 15 of 15 |
#loginForm | Part of #loginModal (account, login and registration). | 15 of 15 |
#loginModal | Login modal containing #loginForm (#loginUsername, #loginPassword). | 15 of 15 |
#loginPassword | Part of #loginModal (account, login and registration). | 15 of 15 |
#loginUsername | Part of #loginModal (account, login and registration). | 15 of 15 |
#newPassword | Part of #changePasswordForm (account, login and registration). | 15 of 15 |
#profileActivity | Recent activity. | 15 of 15 |
#profileAddresses | Saved addresses. | 15 of 15 |
#profileCurrency | Part of #profileName (account, login and registration). | 15 of 15 |
#profileEmail | Part of #profileName (account, login and registration). | 15 of 15 |
#profileName | Profile fields: #profileName #profileUsername #profileEmail #profileCurrency. | 15 of 15 |
#profileOrders | Order history. | 15 of 15 |
#profileUsername | Part of #profileName (account, login and registration). | 15 of 15 |
#registerCaptchaContainer | Part of #registerModal (account, login and registration). | 15 of 15 |
#registerConfirmPassword | Part of #registerModal (account, login and registration). | 15 of 15 |
#registerEmail | Part of #registerModal (account, login and registration). | 15 of 15 |
#registerForm | Part of #registerModal (account, login and registration). | 15 of 15 |
#registerModal | Register modal containing #registerForm (#registerName #registerUsername #registerEmail #registerPhone #registerPassword #registerConfirmPassword, honeypot #registerWebsite, #registerCaptchaContainer). | 15 of 15 |
#registerName | Part of #registerModal (account, login and registration). | 15 of 15 |
#registerPassword | Part of #registerModal (account, login and registration). | 15 of 15 |
#registerPhone | Part of #registerModal (account, login and registration). | 15 of 15 |
#registerUsername | Part of #registerModal (account, login and registration). | 15 of 15 |
#registerWebsite | Part of #registerModal (account, login and registration). | 15 of 15 |
#addressModal, include all of these too (every store template that has it does): #addrId #addressForm#loginModal, include all of these too (every store template that has it does): #loginForm #loginPassword #loginUsername#registerModal, include all of these too (every store template that has it does): #registerCaptchaContainer #registerConfirmPassword #registerForm #registerPasswordMarkup: #addressModal
<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">×</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
<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">×</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
<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">×</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>Legal pages and footer
Text from template.json "legal", social links from "social", payment method badges from the store.
| Element | Purpose | In store templates |
|---|---|---|
[data-sf-payments] | Payment badges marker. | 0 of 15 |
[data-sf-social] | Wrapper hidden together with #footerSocialLinks. | 8 of 15 |
#footerPaymentIcons | Payment method badges. | 15 of 15 |
#footerSocialLinks | Social links (hidden when none are configured). | 15 of 15 |
#privacyContent | Privacy policy text. | 15 of 15 |
#refundContent | Refund policy text. | 15 of 15 |
#termsContent | Terms text. | 15 of 15 |
Markup: #footerPaymentIcons
<div class="payment-icons" id="footerPaymentIcons"></div>Markup: #footerSocialLinks
<div class="social-links" id="footerSocialLinks"></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-behaviordeclarations are removed too (the rule that removesbehavior: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.json | CSS variable |
|---|---|
branding.primaryColor | var(--sf-primary) |
branding.secondaryColor | var(--sf-secondary) |
branding.accentColor | var(--sf-accent) |
branding.textColor | var(--sf-ink) |
branding.surfaceColor | var(--sf-surface) |
branding.mutedSurfaceColor | var(--sf-muted-surface) |
branding.onPrimaryColor | var(--sf-on-primary) |
branding.fontFamily | var(--sf-font-body) |
branding.headingFont | var(--sf-font-heading) |
branding.displayFont | var(--sf-font-display) |
branding.radius | var(--sf-radius) |
.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.fonts | Font family | Weights |
|---|---|---|
albert-sans | Albert Sans | 100 900 |
cormorant-garamond | Cormorant Garamond | 300 700 |
exo | Exo | 100 900 |
forum | Forum | 400 |
fraunces | Fraunces | 100 900 |
inter | Inter | 100 900 |
jost | Jost | 100 900 |
manrope | Manrope | 200 800 |
nunito | Nunito | 200 1000 |
pacifico | Pacifico | 400 |
playfair-display | Playfair Display | 400 900 |
pt-sans | PT Sans | 400, 700 |
roboto | Roboto | 100 900 |
rubik | Rubik | 300 900 |
{
"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.
script.js
Optional. It runs before the storefront engine, so it can configure it through window.StorefrontTheme:
| Property | What it does |
|---|---|
labels | Object of words the engine uses (see labels). Overridden by template.json "labels". |
icons | Font Awesome classes for engine-rendered icons: cart, wishlist, emptyCart, browse, categoryDefault, brand. |
categoryIcons | Extra keyword → icon class pairs for category tiles (matched against category names). |
buttonColor | Confirm-button colour for SweetAlert2 dialogs (defaults to branding.primaryColor). |
onSection | function(route, params, App) called after every route change. |
instantFilters | Set to false so filters apply only when #applyFiltersBtn is pressed. |
categoryImages | Set to false to always use icons instead of category images. |
onInit | function(App) called before the engine boots. |
onReady | function(App) called once the store context, session and cart are loaded. |
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.
| Key | Type | Default | Status | Meaning |
|---|---|---|---|---|
| displayName | string | used | Name shown in the admin template list (GET /api/templates) and stored as the active theme name when an admin switches to this template. | |
| description | string | used | Description shown in the admin template list when set (falls back to website.description). | |
| version | string | used | Template version. Used for the admin list and the installed-version check when theme.json has no version. | |
| website | object | used | Store identity defaults supplied by the template. | |
| description | string | "" | used | Tagline used for the {DESCRIPTION} placeholder, the <meta name="description"> tag and the browser config when the store record has no description of its own. |
| name | string | "" | ignored | Not read by the application — the store name always comes from the store record (pos_setting.store.name). |
| logo | string | "" | ignored | Not read by the application. |
| favicon | string | "" | ignored | Not read by the application. |
| currency | string | "" | ignored | Not read by the application — the currency comes from the store record. |
| language | string | "en" | ignored | Not read by the application (the page is always lang="en"). |
| year | string | "" | ignored | Not read by the application — {YEAR} is the current year. |
| branding | object | used | Colours, 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. | |
| primaryColor | string | used | Main 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})$ | |
| secondaryColor | string | used | Secondary 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})$ | |
| accentColor | string | used | Accent 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})$ | |
| textColor | string | used | Body 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})$ | |
| surfaceColor | string | used | Card / 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})$ | |
| mutedSurfaceColor | string | used | Muted 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})$ | |
| onPrimaryColor | string | used | Text 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})$ | |
| fontFamily | string | used | Body 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}$ | |
| headingFont | string | used | Heading font stack. Sets --sf-font-heading. format ^[A-Za-z0-9 ,'"-]{1,160}$ | |
| displayFont | string | used | Display font stack. Sets --sf-font-display. format ^[A-Za-z0-9 ,'"-]{1,160}$ | |
| radius | string | used | Corner radius such as "8px" (1–2 digits + px). Sets --sf-radius. format ^\d{1,2}px$ | |
| home | object | used | Home page switches read by the storefront engine. | |
| showHero | boolean | true | used | Set to false to hide #heroSlider. |
| showFeatured | boolean | true | used | Set to false to skip loading featured products into #homeFeaturedGrid. |
| showLatestProducts | boolean | true | used | Set to false to skip loading #homeProductsGrid. |
| showCategories | boolean | true | used | Set to false to hide #homeCategoriesSection. |
| showBrands | boolean | true | used | Set to false to hide #homeBrandsSection. |
| productsPerSection | number | 8 | used | How many products the home grids request. |
| products | object | used | Products page filter switches. | |
| productsPerPage | number | 20 | not used by the shop | Not read by the storefront engine (it always requests 20 per page). |
| showFilters | boolean | true | not used by the shop | Not read by the storefront engine. |
| showBrandFilter | boolean | true | used | Set to false to hide the brand filter (#brandSelect). |
| showCategoryFilter | boolean | true | used | Set to false to hide the category filter (#categorySelect). |
| showSubcategoryFilter | boolean | true | used | Set to false to hide the subcategory filter (#subcategorySelect). |
| shipping | object | used | Delivery options the template allows. The server combines them with the store settings and delivery areas. | |
| enabled | boolean | true | used | Set to false to disable delivery choices entirely. |
| storePickupEnabled | boolean | true | used | Offer "Store Pickup" at checkout. |
| storePickupFee | number | 0 | used | Fee charged for store pickup, in the store currency. |
| standardDeliveryEnabled | boolean | true | used | Offer delivery to an address (also needs delivery areas in the store data). |
| payment | object | used | Payment switches applied on the server when listing payment methods. | |
| enabled | boolean | true | used | Set to false to disable online payment methods. |
| cashOnDeliveryEnabled | boolean | true | used | Set to false to hide Cash on Delivery. |
| security | object | used | Present 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). | |
| captcha | object | used | CAPTCHA settings. | |
| enabled | boolean | true | ignored | Not read — the browser config always receives enabled:false and the server decides when CAPTCHA is required. |
| login | boolean | true | ignored | Not read. |
| registration | boolean | true | ignored | Not read. |
| type | string | "server" | ignored | Not read. |
| minFormTimeMs | number | 1500 | not used by the shop | Copied to the browser config; not read by engine.js. |
| legal | object | used | Text of the legal pages rendered into #termsContent, #refundContent and #privacyContent. Plain text; blank lines start paragraphs; "{STORE_NAME}" is replaced with the store name. | |
| terms | string | "" | used | Terms & Conditions. |
| refundPolicy | string | "" | used | Refund policy. |
| privacyPolicy | string | "" | used | Privacy policy. |
| social | object | used | Social profile links shown in #footerSocialLinks. Only https:// URLs are rendered; empty values are skipped. | |
| string | "" | used | Facebook URL. | |
| string | "" | used | Instagram URL. | |
| string | "" | used | Twitter URL. | |
| x-twitter | string | "" | used | X URL. |
| tiktok | string | "" | used | TikTok URL. |
| string | "" | used | LinkedIn URL. | |
| youtube | string | "" | used | YouTube URL. |
| string | "" | used | Pinterest URL. | |
| string | "" | used | WhatsApp URL. | |
| footer | object | used | Copied to the browser config; engine.js does not read these switches (hide footer parts with your own HTML/CSS). | |
| showSocialLinks | boolean | true | not used by the shop | Not read by engine.js. |
| showPaymentIcons | boolean | true | not used by the shop | Not read by engine.js. |
| showLegalLinks | boolean | true | not used by the shop | Not read by engine.js. |
| features | object | used | Feature switches read by the storefront engine. | |
| wishlist | boolean | true | used | Set to false to remove wishlist buttons from product cards and the product page. |
| featuredProducts | boolean | true | used | Set to false to stop loading featured products. |
| shopByCategory | boolean | true | used | Set to false to hide the home category grid. |
| shopByBrand | boolean | true | used | Set to false to hide the home brand grid. |
| coupons | boolean | true | used | Set to false to hide the coupon box in the cart. |
| reviews | boolean | true | not used by the shop | Not read by engine.js. |
| guestCart | boolean | true | not used by the shop | Not read by engine.js. |
| content | object | used | Optional merchandising content. The server validates it (store/theme-assets.js publicContent) and blocks that have no content are hidden by the engine. | |
| announcement | string | "" | used | Text for [data-sf-announcement] / .announcement-bar (max 180 characters). max 180 characters |
| heroSlides | array | used | Replaces the slides inside #heroSlider (max 5). The first .hero-slide in your HTML is used as the slide template. max 5 items | |
| eyebrow | string | "" | used | Small text above the title (max 80). max 80 characters |
| title | string | "" | used | Slide title (required, max 120). Slides without a title are dropped. max 120 characters, required |
| text | string | "" | used | Paragraph (max 220). max 220 characters |
| cta | string | "" | used | Button text (max 40). max 40 characters |
| link | string | "#products" | used | Button link: a storefront route such as "#products" or a same-site path "/…". Anything else becomes "#products". |
| image | string | "" | used | Background image: /image/…, /assets/… or /uploads/… path to a png/jpg/webp/svg/gif. |
| promotions | array | used | Promotion 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 | |
| eyebrow | string | "" | used | Small text (max 60). max 60 characters |
| title | string | "" | used | Title (required, max 80). max 80 characters, required |
| text | string | "" | used | Text (max 160). max 160 characters |
| cta | string | "" | used | Link text (max 30). max 30 characters |
| link | string | "" | used | Storefront route or same-site path. |
| image | string | "" | used | /image/…, /assets/… or /uploads/… image path. |
| category | string | "" | used | Category name: the card links to that category. max 80 characters |
| usps | array | used | Service 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 | |
| icon | string | "check" | used | Font Awesome icon name without "fa-" (e.g. "truck-fast"). format ^[a-z0-9-]{2,40}$ |
| title | string | "" | used | Title (required, max 60). max 60 characters, required |
| text | string | "" | used | Text (max 120). max 120 characters |
| testimonials | array | used | Quotes for [data-sf-testimonials] / .testimonial-section (max 8). The section stays hidden when empty: the engine never invents reviews. max 8 items | |
| quote | string | "" | used | Quote (required, max 400). max 400 characters, required |
| name | string | "" | used | Name (required, max 60). max 60 characters, required |
| role | string | "" | used | Role / location (max 60). max 60 characters |
| newsletter | boolean | false | used | Show newsletter blocks (.newsletter-section, [data-sf-section="newsletter"], .footer-newsletter). Hidden unless true. |
| labels | object | used | Overrides for the words the engine uses (merged over script.js StorefrontTheme.labels). Keys are listed in the Runtime API section. | |
| assets | object | used | Shared assets loaded by the page head. | |
| kit | boolean | false | used | true loads /assets/storefront/kit.css (the layout kit used by the newer templates). |
| fonts | array | [] | used | Self-hosted fonts to load (keys of /assets/fonts/<key>.css that exist in the application). |
{
"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.
| Key | Meaning |
|---|---|
id | Platform template id (e.g. "TPL-…"). activeThemeId may match it. |
name | Display name. activeThemeName may match it. |
slug | Slug. activeThemeId may match it; the admin "switch" stores it as activeThemeId. |
version | Installed version (wins over template.json version). |
previewImage | Preview image URL shown in the admin template list. |
sourceUrl | Not read by the application. (ignored) |
installedAt | Not read by the application (written by the platform installer). (ignored) |
description | Not read by the application. (ignored) |
{
"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 matchestheme.json→slug. -
template.jsonexists and is valid JSON (paste it into any JSON checker). -
index.htmlhas no<head>content you rely on, and no<script>,<style>,<link>,<iframe>oron…=attributes — they are removed. - Every
<!-- IF -->has its<!-- ENDIF -->, everyFOREACHitsENDFOREACH, everyLOOPitsENDLOOP— 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-homewith classapp-section active, and everydata-navlink 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 CSSurl(). - No fonts, images, scripts or styles from other websites; fonts come from the store's list.
- Brand colours in
template.jsonare hex (#0b6e4for#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→versionis raised for every new version you send.
All 62 rules the store's checks use
| Level | Rule |
|---|---|
| Must fix | … does not exist in image/. |
| Must fix | url(…) resolves against /templates/<name>/…, which the application does not serve. Use an absolute /image/… path. |
| Must fix | Template engine: |
| Must fix | Template engine: |
| Must fix | JavaScript syntax error: |
| Must fix | template.json is not valid JSON: |
| Must fix | template.json must contain a JSON object. |
| Must fix | … is missing. |
| Must fix | Install 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 fix | data-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 fix | Both 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 fix | behavior: is removed by the application. |
| Should fix | -moz-binding: is removed by the application. |
| Should fix | expression() is removed by the application. |
| Should fix | url(…) 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 fix | The application changes parts of this stylesheet when serving it (sanitizeCss). |
| Should fix | The 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 fix | id="…" 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 fix | Cross-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 fix | Everything inside <head> is discarded by the application (title, meta, links). The application writes its own head. |
| Should fix | src="…" 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 fix | The 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 fix | There 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 fix | style 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 fix | srcdoc 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 know | External image … is loaded through the application's image proxy (/img-proxy). Prefer files in image/. |
| Good to know | script.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 know | theme.json version (…) and template.json version (…) differ; the application reports theme.json's. |
Delivering your template
- Zip the folder (not just the files inside): the zip must contain exactly one folder named like your template, with
template.jsondirectly in it.Zip contentssunny-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). - Send the zip to the store owner with the version number and what changed.
For the store owner: installing
- Copy the template folder to <app>/templates/<name>/ (name: letters, digits, "-" and "_").
- Load it: restart the application, or (signed in as admin) POST /api/templates/reload {"templateName":"<name>"}.
- 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 see | Why, 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 stays | Usually an unbalanced IF/ENDIF block or invalid template.json, or a folder name with spaces or other characters. |
| No products appear | With 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 nothing | Event attributes are removed. Use data-action or script.js. |
| My <script> or <style> in index.html is gone | They are removed. Put code in script.js and styles in styles.css. |
| Background image missing | Use url(/image/…) with the leading slash; external images are blocked. |
| My Google Font doesn't load | External fonts are blocked. Use a font from the store's list. |
| Smooth scrolling doesn't work | scroll-behavior is removed by the store; use script.js (element.scrollIntoView({behavior: 'smooth'})). |
| A page link opens the home page | Your template has no #section-… for that page. |
| Store phone/address are empty | They are empty until a store is chosen, and in shops without branches. Wrap them in <!-- IF STORE_PHONE -->. |
| Colours from template.json have no effect | Only 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
| Element | Purpose |
|---|---|
.app-section | Every route container. Only the active one should be visible (your CSS: .app-section{display:none} .app-section.active{display:block}). |
.main-nav | Navigation container whose .nav-link items are de-activated on route change. |
.nav-link | Navigation link; gets class "active" for the current route when it has data-section. |
.nav-profile-item | Shown only when a customer is signed in. |
#mainNav | Main navigation. Gets class "open" when #mobileMenuBtn is pressed. |
#mobileMenuBtn | Menu toggle button (aria-expanded is kept in sync; body gets class "sf-nav-open"). |
#mobileNav | Optional separate mobile navigation (takes precedence over #mainNav for the menu button). |
#section-cart | Cart (route "cart"). |
#section-checkout | Checkout (route "checkout"). |
#section-featured | Featured products (route "featured"). |
#section-home | Home page (route "home"). Also the fallback for unknown routes. |
#section-privacy-policy | Privacy policy (route "privacy-policy"). |
#section-product-detail | Single product (route "product-detail"). |
#section-products | Product list with filters (route "products"). |
#section-profile | Account pages (route "profile"; shows the login modal when signed out). |
#section-refund-policy | Refund policy (route "refund-policy"). |
#section-terms | Terms page (route "terms"). |
#section-wishlist | Saved items (route "wishlist"). |
Header counters, account and search
| Element | Purpose |
|---|---|
#cartCount | Number of items in the cart (class "sf-empty-count" when zero). |
#searchClose | Closes the search overlay. |
#searchContainer | Search wrapper toggled with class "open"/"active" by #searchToggleBtn. |
#searchInput | Search box. Typing shows suggestions; Enter searches the products page. |
#searchOverlay | Full-screen search overlay (used instead of #searchPanel when present). |
#searchPanel | Optional dropdown panel toggled together with #searchContainer. |
#searchSuggestions | Suggestion list container (class "active" when open). |
#searchToggle | Alternative id for the search toggle button. |
#searchToggleBtn | Opens/closes the search panel. |
#userMenu | Replaced with "Log in / Register" buttons or the signed-in customer's name, account and logout buttons. |
#wishlistCount | Number of saved items. |
Store selection
| Element | Purpose |
|---|---|
[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 store | Generated by the engine — do not add it yourself. |
#sfStoreModal made by the store | Generated by the engine — do not add it yourself. |
#sfStorePill made by the store | Generated by the engine — do not add it yourself. |
Home page blocks
| Element | Purpose |
|---|---|
.announcement-bar | Alternative announcement bar marker. |
.footer-newsletter | Newsletter block in the footer. |
.hero-slide | One slide inside #heroSlider. |
.home-featured | Wrapper of #homeFeaturedGrid; hidden until a store is chosen and when empty. |
.home-products | Wrapper of #homeProductsGrid. |
.newsletter-section | Newsletter block (shown when content.newsletter is true). A form inside with an email input subscribes. |
.promo-banners | Promotion slots (.promo-banner children). Filled from content.promotions or the store's categories. |
.testimonial-section | Testimonials wrapper (hidden when there are none). |
.two-col-banners | Two promotion slots (.two-col-banner children). |
.usp-strip | Alternative 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. |
#heroDots | Dot buttons generated for each slide. |
#heroPaymentLine | Text replaced with the store's payment methods. |
#heroSlider | Slider. Children .hero-slide (first one active), buttons [data-action="hero-prev"/"hero-next"], dots in #heroDots. content.heroSlides in template.json replaces the slides. |
#homeAnimalsGrid | Secondary category showcase (icon cards). |
#homeAnimalsSection | Wrapper of #homeAnimalsGrid. |
#homeBrandsGrid | Brand tiles (shown when the store has 2+ brands). |
#homeBrandsSection | Wrapper of #homeBrandsGrid. |
#homeCategoriesGrid | Category tiles. |
#homeCategoriesSection | Wrapper of #homeCategoriesGrid. |
#homeFeaturedGrid | Featured product cards. |
#homeProductsGrid | Newest product cards. |
#homeRecentlyViewed | Recently viewed products (from this browser, per store). Put a .products-grid inside. |
#megaBrandsList | Brand links inside a mega menu. |
#megaCategoriesList | Category links inside a mega menu. |
#testimonialDots | Testimonial dots. |
Products page
| Element | Purpose |
|---|---|
.filter-sidebar | Alternative filter drawer marker. |
#applyFiltersBtn | Applies filters (filters also apply instantly unless StorefrontTheme.instantFilters is false). |
#brandSelect | <select> of brands. |
#categorySelect | <select> of categories (first option value "all"). |
#clearFiltersBtn | Clears filters. |
#featuredGrid | Featured products page grid. |
#featuredStoreRequired | Message area on the featured page when no store is selected. |
#filterToggleMobile | Opens the filter panel on small screens. |
#pagination | Page buttons. |
#priceRange | <input type="range"> maximum price. |
#priceRangeLabel | Shows the chosen maximum price. |
#productDetailContainer | Filled with the product page (gallery, price, variants, quantity, add to cart, related products). |
#productsFiltersSection | Filter panel (class "mobile-open" when opened on small screens). |
#productsGrid | Product cards for the current page. |
#productsStoreRequired | Message area shown when no store is selected. |
#resultsCount | Number of products shown. |
#resultsCounter | Wrapper 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). |
#totalCount | Total number of matching products. |
#wishlistContainer | Filled with saved items. |
Cart
| Element | Purpose |
|---|---|
#cartContainer | Cart contents. |
#stickyCartCount | Item count in the sticky bar. |
#stickyCartTotal | Total in the sticky bar. |
#stickyOrderBar | Optional sticky bar with #stickyCartCount and #stickyCartTotal. |
Checkout
| Element | Purpose |
|---|---|
.checkout-content | Wrapper of the step panels (the order summary is inserted next to it). |
.checkout-step-content | One step panel (class "active" when shown). |
.checkout-steps | Progress 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). |
#agreeTerms | Terms checkbox required before placing the order. |
#billingForm | Step 2 form with #sameAsShipping and the #differentBilling fields. |
#checkoutPersistenceBadge | "Your checkout progress has been restored" notice. |
#differentBilling | Part of #billingForm (checkout). |
#discountRow | Part of #reviewSubtotal (checkout). |
#paymentDetailsContainer | Payment instructions for the chosen method. |
#paymentMethods | Step 4: payment methods. |
#placeOrderBtn | Places the order. |
#reviewBilling | Part of #reviewItems (checkout). |
#reviewDiscount | Part of #reviewSubtotal (checkout). |
#reviewItems | Step 5: order lines (with #reviewShipping, #reviewBilling, #reviewPayment). |
#reviewPayment | Part of #reviewItems (checkout). |
#reviewShipping | Part of #reviewItems (checkout). |
#reviewShippingCost | Part of #reviewSubtotal (checkout). |
#reviewSubtotal | Totals: #reviewSubtotal #reviewDiscount #reviewShippingCost #reviewTax #reviewTotal (#discountRow, #summaryNote). |
#reviewTax | Part of #reviewSubtotal (checkout). |
#reviewTotal | Part of #reviewSubtotal (checkout). |
#sameAsShipping | Part of #billingForm (checkout). |
#sfCheckoutBlocked made by the store | Generated by the engine. |
#sfCheckoutSummary made by the store | Generated by the engine. |
#sfOrderConfirmation made by the store | Generated by the engine. |
#shipAddress1 | Part of #shippingForm (checkout). |
#shipAddress2 | Part of #shippingForm (checkout). |
#shipCity | Part of #shippingForm (checkout). |
#shipCountry | Part of #shippingForm (checkout). |
#shipEmail | Part of #shippingForm (checkout). |
#shipFullName | Part of #shippingForm (checkout). |
#shipPhone | Part of #shippingForm (checkout). |
#shippingFeeHint | Part of #shippingLocationContainer (checkout). |
#shippingForm | Step 1 form: #shipFullName #shipEmail #shipPhone #shipAddress1 #shipAddress2 #shipCity #shipState #shipPostalCode #shipCountry. |
#shippingLocationContainer | Delivery area pickers #shippingLocationSelect and #shippingSublocationSelect, and #shippingFeeHint. |
#shippingLocationSelect | Part of #shippingLocationContainer (checkout). |
#shippingMethods | Step 3: delivery options. |
#shippingSublocationSelect | Part of #shippingLocationContainer (checkout). |
#shipPostalCode | Part of #shippingForm (checkout). |
#shipState | Part of #shippingForm (checkout). |
#summaryNote | Part of #reviewSubtotal (checkout). |
Account, login and registration
| Element | Purpose |
|---|---|
.modal | Any modal; clicking its backdrop closes it. |
.profile-tab | Profile tab buttons (data-tab="info|orders|addresses|activity|security"). |
.profile-tab-content | Tab 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. |
#addrCountry | Part of #addressModal (account, login and registration). |
#addressForm | Part of #addressModal (account, login and registration). |
#addressModal | Address editor (#addressForm with #addrId #addrFullName … #addrCountry). |
#addrFullName | Part of #addressModal (account, login and registration). |
#addrId | Part of #addressModal (account, login and registration). |
#changePasswordForm | Password form (#currentPassword #newPassword #confirmPassword). |
#confirmPassword | Part of #changePasswordForm (account, login and registration). |
#currentPassword | Part of #changePasswordForm (account, login and registration). |
#loginForm | Part of #loginModal (account, login and registration). |
#loginModal | Login modal containing #loginForm (#loginUsername, #loginPassword). |
#loginPassword | Part of #loginModal (account, login and registration). |
#loginUsername | Part of #loginModal (account, login and registration). |
#newPassword | Part of #changePasswordForm (account, login and registration). |
#profileActivity | Recent activity. |
#profileAddresses | Saved addresses. |
#profileCurrency | Part of #profileName (account, login and registration). |
#profileEmail | Part of #profileName (account, login and registration). |
#profileName | Profile fields: #profileName #profileUsername #profileEmail #profileCurrency. |
#profileOrders | Order history. |
#profileUsername | Part of #profileName (account, login and registration). |
#registerCaptchaContainer | Part of #registerModal (account, login and registration). |
#registerConfirmPassword | Part of #registerModal (account, login and registration). |
#registerEmail | Part of #registerModal (account, login and registration). |
#registerForm | Part of #registerModal (account, login and registration). |
#registerModal | Register modal containing #registerForm (#registerName #registerUsername #registerEmail #registerPhone #registerPassword #registerConfirmPassword, honeypot #registerWebsite, #registerCaptchaContainer). |
#registerName | Part of #registerModal (account, login and registration). |
#registerPassword | Part of #registerModal (account, login and registration). |
#registerPhone | Part of #registerModal (account, login and registration). |
#registerUsername | Part of #registerModal (account, login and registration). |
#registerWebsite | Part of #registerModal (account, login and registration). |
Legal pages and footer
| Element | Purpose |
|---|---|
[data-sf-payments] | Payment badges marker. |
[data-sf-social] | Wrapper hidden together with #footerSocialLinks. |
#footerPaymentIcons | Payment method badges. |
#footerSocialLinks | Social links (hidden when none are configured). |
#privacyContent | Privacy policy text. |
#refundContent | Refund policy text. |
#termsContent | Terms text. |
Generated by the engine
| Element | Purpose |
|---|---|
[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 store | Set on images rendered by the engine. |
[data-sf-link] made by the store | Set by the engine on hero buttons configured in content.heroSlides. |
[data-sf-state] made by the store | Set on sections by the engine: loading / ready / empty / needs-store (style hidden states with it). |
#couponInput made by the store | Coupon field inside the cart. |
#pdMainImageWrap made by the store | Product page gallery (inside #productDetailContainer). |
#pdQty made by the store | Product page quantity input (with #pdQtyDown / #pdQtyUp). |
#pdQtyDown made by the store | Product page quantity button. |
#pdQtyUp made by the store | Product page quantity button. |
#sfRecentWrap made by the store | Recently viewed block on the product page. |
#sfRelated made by the store | Related products block on the product page. |
#sfToastStack made by the store | Toast notifications. |