# Storefront themes A **theme** is the whole customer-facing website of a shop: its pages, styles, scripts and pictures. Every shop on the platform picks one theme in the Platform console (Shops → Theme). The **admin app is not themed** — it is the same for every shop, branded only with the shop's name, logo and colours. A theme never touches a database. Everything it shows or sends goes through the shared client `window.FHStore` and the shared scripts in `/core/`, which talk to the shop's public API. The platform works out which shop a request is for from the web address, so the same theme code serves every shop. ``` themes/ classic/ the original Sri Kumaran storefront theme.json preview.webp index.html about.html products.html collections.html contact.html terms.html assets/css/… assets/js/… assets/images/… core/ shared by every theme and the admin app — never copy into a theme shop-config.js shop-theme.js fh-store.js track-consent.js tracker.js home-promotions.js home-promotions.css budget-modal.js budget.css images/ ``` ## 1. How files are found For a shop using theme ``, `server.cjs` looks for every URL in `themes//` first and then in the project root. So: - `index.html` → `themes//index.html` - `/assets/css/site-01.css` → `themes//assets/css/site-01.css` - `/core/fh-store.js` → `core/fh-store.js` (project root: shared) - `/parade/…`, `/assets/furniture_img/…`, `/uploads/…` → product photos and the shop's uploads (root / the shop's data folder). **Product image URLs come from the API; never hard-code them.** Write paths the same way as the classic theme: pages use `assets/...` and `/core/...`. A stylesheet's `url()` resolves against the stylesheet's own folder, so from `assets/css/x.css`, the theme's own `hero.webp` at the theme root is `url('../../hero.webp')`. ## 2. theme.json ```json { "id": "aurora", // = folder name: lowercase letters, digits, hyphens "name": "Aurora", "version": "1.0.0", "description": "One line for the console.", "preview": "preview.webp", // ~640×450 screenshot of the home page "pages": ["index.html", "about.html", "products.html", "collections.html", "contact.html", "terms.html"] } ``` `collections.html` is optional: leave it out of the folder and of `"pages"`, and `/collections.html` redirects to `/products.html`. The other five are required. The pop-ups only run on these page names, and both consent pop-ups load `/terms.html` to show the full terms. ## 3. Required scripts and their order Every page except `terms.html`: ```html …your stylesheets… … …your scripts (they may use FHStore from here on)… ``` `terms.html` needs only `/core/shop-config.js` (so the shop's name appears in it). Its main text is shown inside the pop-ups. ## 4. Hooks the core scripts read from your HTML | Attribute / id | Used by | What happens | |---|---|---| | `data-shop="contact.phone"` (any setting key) | shop-config.js | element text = the saved value | | `data-shop-tpl="© {year} {shop}"` | shop-config.js | text from a template: `{shop} {short} {tagline} {year} {phone} {email}` | | `data-shop-text` | shop-config.js | the default shop name inside the text is replaced by this shop's name | | `data-shop-href="contact.facebook"` / `data-shop-src="contact.map_embed"` | shop-config.js | link / iframe from a setting; hidden when blank (renamed shops) | | `` | shop-config.js | gets the uploaded logo, or the shop name as text | | `data-shop-img="about.owner_photo"` | shop-config.js | an `` filled from an image setting | | any stylesheet rule using `hero.webp` / `hero-mobile.webp` | shop-config.js | swapped for the shop's Hero image setting | | CSS colours | shop-theme.js | Appearance colours repaint every matching colour in your stylesheets | | `#budget-greeter`, `#menu`, `#burger` | budget-modal.js | the greeter mounts in `#budget-greeter`; waits while the menu is open | | body classes `fh-no-` | shop-config.js | set when the shop switches a feature off (e.g. `fh-no-checkout`) — hide your matching UI | The consent pop-up, the promotions pop-ups and the budget modal draw their own markup. You don't build them, and you mustn't hide them. ## 5. Cart, checkout and product details These belong to the theme. The simplest route is to keep the classic theme's `assets/js/shop.js` (cart drawer, checkout and product modal, all built in JavaScript) and give your pages its three hooks: | Hook | Where | Purpose | |---|---|---| | `id="cart-button"` | every page | opens the cart drawer (shop.js adds the count badge) | | `id="featured-products"` | index.html, products.html | the product grid; `data-show-all="true"` lists everything, otherwise six best sellers | | `id="products"` | the section around the grid | filters, search box and "View more" live in here | If you write your own cart, you must still: - Read products only with `FHStore.loadProducts()` / `FHStore.fetchProduct(id)`. - Place orders only with `FHStore.placeOrder(order)`. - Tell the tracker when product details open and close. Staff links and the Website tab depend on these events: ```js document.dispatchEvent(new CustomEvent('fh:product-opened', { detail: { name: product.name, price: product.price } })); document.dispatchEvent(new CustomEvent('fh:product-closed')); ``` ## 6. API contract (`window.FHStore`, from `/core/fh-store.js`) All calls return Promises. On failure they reject with an `Error` that has a `.status` (the HTTP status) and a readable `.message`. The client finds the API on its own (same address, `/api`), so never build API URLs yourself. ### Products `FHStore.loadProducts({ category?, search?, includeOutOfStock? })` → `GET /api/products` → `Product[]` (cached; `FHStore.getProducts()` reads the cache) `FHStore.fetchProduct(idOrSlug)` → `GET /api/products/:id` → `Product` `FHStore.loadCategories()` → `GET /api/products/categories` → `string[]` ```ts Product = { id: string; slug: string; name: string; category: string; subcategory: string; price: number; // rupees mrp: number; // original price, 0 = none (show strike-through when > price) image: string; // URL, may be a data: URL video: string; // URL or '' badge: string; // e.g. 'Bestseller', '' showPrice: boolean; // false → show "Ask for price" desc: string; specs: string; // specs separated by ' · ' stock: 'in' | 'low' | 'out'; stockCount: number; inStock: boolean; layout: '' | 'showcase' | 'text-product'; } ``` Out-of-stock products are left out unless `includeOutOfStock` is set. ### Orders `FHStore.placeOrder(order)` → `POST /api/orders` ```ts order = { name: string; phone: string; address: string; landmark?: string; city: string; pin: string /* 6 digits */; notes?: string; items: { id: string /* product id */; qty: number }[] } // resolves to Order = { id; ref /* '#1042' */; orderNumber; createdAt; name; phone; address; landmark; city; pin; notes; items: { id; name; image; price; qty; subtotal }[]; total: number; status: 'PENDING' | …; statusLabel: string; whatsappMessage: string; whatsappUrl: string /* wa.me link to the shop */; customerWhatsappUrl: string } ``` Prices and stock are checked again by the server. On a validation error it rejects with `status` 400 and a message to show the customer. ### Shop settings `FHStore.loadPublicSettings()` → `GET /api/settings/public` → `{ storeName, whatsapp /* digits */, currency, delivery, confirmationNote, raw }`, where `raw` is every public setting key (`shop.name`, `contact.phone`, `theme.primary`, …). Most themes never call it: `shop-config.js` already fills the page, and `FHShopConfig.get('contact.phone')` reads any value. ### Enquiries and promotions `FHStore.submitEnquiry({ name, phone, email?, city?, interest?, budget?, visitDate?, callTime?, message? })` → `POST /api/enquiries` → `{ id, receivedAt }` (the contact form; see classic `site.js`). You don't call the promotions methods (`loadPromotions`, `sendPromotionOtp`, `claimPromotion`, `fetchPromotionCatalogue`) yourself: `home-promotions.js` does. ### Endpoints underneath (for reference; themes don't call them directly) | Method | Path | Used for | |---|---|---| | GET | `/api/products`, `/api/products/:id`, `/api/products/categories` | catalogue | | POST | `/api/orders` | checkout | | GET | `/api/settings/public` | branding and wording | | POST | `/api/enquiries` | contact form | | GET/POST | `/api/promotions`, `/api/promotions/otp`, `/api/promotions/claim`, `/api/promotions/catalogue` | pop-ups | | POST | `/api/site-visit/ping`, `/exit`, `/api/track/*` | tracker.js | | GET | `/api/tenant` | which shop, and whether its demo has ended | ## 7. Rules 1. No `fetch('/api/…')` and no `XMLHttpRequest` in theme scripts. Use `FHStore`. 2. No `window.alert()` or `window.confirm()`. Show messages in the page. 3. No source file over 1,500 lines. 4. Never copy `/core/` files into the theme. Link them, so fixes reach every shop. 5. Don't rename the six pages. The pop-ups, the tracker and staff links (`/t/` → a page of your theme) depend on those names. 6. Make it work at 390 px wide, with no sideways scrolling. ## 8. Checklist: adding a theme 1. Copy `themes/classic/` to `themes//` and change what you like, or build from scratch following sections 2–6. 2. Set `theme.json` (`id` = the folder name) and add a `preview.webp`. 3. Run `npm run theme:check themes/` until it reports **0 errors**. 4. Restart nothing. In the Platform console, open a demo shop and choose the theme under **Theme**. The shop's website switches within about 15 seconds. 5. Open the shop's website at phone and desktop width and go through these: - the home pop-ups - a product's details - adding to the cart - checkout (the order appears in the admin app) - a staff link `/t/` with its consent question 6. A new folder appears under **Themes ? Refresh library**. It can be selected only after validation passes. Shops already on another theme are not affected. ## 9. Themes built from a framework (firstfurniture) `themes/firstfurniture/` is **generated** from the Next.js project in `firstfurniture/` — never edit it by hand. Change the React source, then run `npm run theme` inside `firstfurniture/`: it does a static export (`out/`), copies it here, adds the `/core/` scripts to every page (`firstfurniture/tools/export-theme.cjs`) and keeps `preview.webp`. The React code reads products, orders, enquiries and the shop's details only through `firstfurniture/lib/shop.ts` (FHStore / FHShopConfig). Links are plain ``, so every page is a full load and the core scripts run on each; the cart and wishlist live in sessionStorage (`fh_ff_cart`, `fh_ff_wishlist`). ## 10. Import and apply from the UI Open the **Platform console → Themes**. Choose a prepared theme folder, then select **Validate & import**. The folder must contain `theme.json` at its root, a raster preview image, the six required HTML pages and their assets. The limit is 500 MB / 5,000 files (uploaded in ~25 MB batches). Imports are available only to signed-in platform admins. A whole project folder (React/Vite/Next, with `node_modules` and `src`) also works: the console drops dependencies and source, uses the built site (`dist/`, `build/`, `out/`…), writes `theme.json` with `"imported": "static"`, copies `index.html` into any missing shop page (single-page apps), adds the `/core/` scripts, and the server adds the classic Terms page. For such themes a missing cart button / product grid is a note, not an error, and a clashing id gets `-2`, `-3`…. A project that was never built still has to run its build once (`npm run build`). Validation errors leave the library unchanged and list the files to fix. Warnings are shown for optional integrations. A successful import is installed as `themes//`. Existing IDs cannot be overwritten; use a new ID for a new version, so a shop can return to its previous theme. Choose a shop on a theme card and click **Apply theme**. Only that shop's theme setting changes. The success message links to its storefront; changes may take up to 15 seconds to appear. Other shops, products and orders stay unchanged. Folders copied directly into `themes/` appear when the library is refreshed. Invalid folders are listed with errors and cannot be newly assigned. The importer accepts browser-ready HTML/CSS/JavaScript and static assets. It does not install dependencies, run uploaded code on the server, or build raw Next.js / React source. For this project's Next.js example, run `npm run theme` in `firstfurniture/` and refresh the library. Other framework exports must follow the same page and shared API integration contract in this guide.