Store Developer Guide
Customize a fcomurs store with HTML, CSS and JavaScript — right inside the editor. No server, no build, no deploy.
1.Where things are
Online store → Customize (the editor) │ ├─ ⋯ → Edit code · or right-click any section → Edit code / Customize code │ ├─ Header · Footer header.html/.css/.js │ ├─ Your sections + New <name>.html · .css · .js · .json │ ├─ Your blocks + New same four files, for a block │ ├─ Theme sections / blocks built-in code, read-only → Customize │ └─ top bar: Docs · Pause custom code · Publish code │ ├─ Custom code (top left) This page · Whole store · Tracking └─ Any section/block → Style → For developers copy #section-… / #block-…
| I want to… | Go to | Live when |
|---|---|---|
| Build my own section | Edit code, Your sections | Publish code |
| Build a block for any section | Edit code, Your blocks | Publish code |
| Change a built-in section/block | Right-click, Customize code | Publish code |
| Own header / footer | Edit code, Header / Footer | page Publish |
| Small CSS on one page | Custom code, This page | page Publish |
| Store-wide CSS / scripts | Custom code, Whole store | Save |
| Analytics, Pixel, TikTok… | Custom code, Tracking | Save |
Tip: drag the edges between panels to resize them (double-click resets).
2.Files at a glance
| File | Section | Block | Runs |
|---|---|---|---|
.html | Handlebars {{settings.x}} | Handlebars | server + editor preview |
.css | ✓ | ✓ | browser |
.js | gets section, fc | gets block, fc | store only (and Preview links) |
.json | settings blocks starter max_blocks | settings only | builds the settings panel |
3.First section in 5 steps
- Edit code, Your sections, + New, type a name, Enter
.json— list what the merchant can change.html— use them:{{settings.heading}}- Save draft (Ctrl+S), check the preview
- Publish code, add it: Add section, Code sections
4.settings.json
{
"settings": [
{ "key": "heading", "label": "Heading", "kind": "text", "default": "Why shop with us" },
{ "key": "featured", "label": "Product", "kind": "product" },
{ "key": "layout", "label": "Layout", "kind": "select", "options": ["grid", "list"], "default": "grid" }
],
"blocks": [
{ "type": "card", "label": "Card", "fields": [
{ "key": "title", "label": "Title", "kind": "text" },
{ "key": "image", "label": "Image", "kind": "image" }
] }
],
"starter": [{ "type": "card", "settings": { "title": "Easy returns" } }],
"max_blocks": 12
}kind | Template gets |
|---|---|
text textarea url color datetime | text |
richtext | HTML — print with {{{ }}} |
image | image address |
select | chosen value (needs options) |
number range | number (min max step unit) |
checkbox | true / false |
product | title url image price compareAtPrice inStock id slug |
collection | name url image slug products |
collections | a list of collections |
form | a form's id |
Field extras: default · help · placeholder. key: starts with a letter; letters, numbers, _.
5.Template cheat sheet
| Name | Section | Block |
|---|---|---|
settings.<key> | ✓ | ✓ |
blocks (each: id type settings) | ✓ | — |
section.id / block.id block.type | ✓ | ✓ |
store — name logo phone email address currencySymbol | ✓ | ✓ |
data — the built-in's own data (customized copies) | ✓ | — |
| Helper | Example |
|---|---|
eq ne gt lt | {{#if (eq type "card")}} |
and or not | {{#if (and settings.a (not settings.b))}} |
default | {{default settings.title "Untitled"}} |
money | {{money price}}, ৳1,990 |
embed | {{embed settings.url}}, YouTube/Vimeo player URL |
encode | {{encode settings.address}}, safe inside a URL |
lines | {{#each (lines settings.items)}}{{this}}{{/each}} |
<section class="cards"> <h2>{{settings.heading}}</h2> {{#each blocks}} {{#if (eq type "card")}}<div class="card">{{settings.title}}</div>{{/if}} {{/each}} {{#with settings.featured}}<a href="{{url}}">{{title}} — {{money price}}</a>{{/with}} </section>
{{x}} is escaped (safe). {{{x}}} prints HTML — only for richtext.
6.Script (.js)
fc. | Does |
|---|---|
submitForm({ form, name, email, phone, message, website }) | Contact / Email signup, error text or null |
submitBuiltForm(formId, answers, website) | a form built in Online store, Forms |
addToCart(productId, quantity) | adds to cart; header count updates |
// section = this copy's element (runs once per copy) section.querySelectorAll('.card').forEach((card) => { card.addEventListener('click', () => card.classList.toggle('open')); });
Doesn't run in the editor preview — test with Preview (beside Publish). Errors show in the console as Code section "<name>".
7.Blocks
| Code section | Code block | |
|---|---|---|
| On a page | code:<id> | cb:<id> |
.json | settings + blocks | settings only |
| Script gets | section | block |
| Added from | Add section, Code sections | Add block, Your code blocks |
Which sections take which blocks — accepts in each built-in's schema.json:
| Sections | Add block offers |
|---|---|
most ("@theme", the default) | every built-in block + your code blocks |
| Product grid · Featured collection · Collection list · Brand list | Heading, Text, Button, Divider, Space |
Blocks already on a page stay, even if no longer offered.
8.Customize built-in code
Built-in section ──Customize code──▶ "<name> (custom)" your store only settings + its own blocks ─────── kept ───────────▶ store data (products, slides…) ── as data.* ─────▶
| How | Where |
|---|---|
| Right-click a section / ⋯, Customize code | on the page |
| Edit code, Theme sections / Theme blocks, Customize | not placed on a page yet |
| Back: ⋯, Use original section / block | your copy stays in Edit code |
23 sections and 11 blocks can be customized.
| Section | data has |
|---|---|
| Product grid, Featured collection | data.products |
| Featured product | data.product (+ images, description) |
| Collection list / Brand list | data.collections / data.brands |
| Slideshow | data.slides, data.side |
| Contact details / Form | data.contact / data.form |
Slideshow: use a different banner on phones
Each slide has its own Picture and optional Picture for phones fields. Add or select a slide in the editor, upload the desktop banner under Picture, then upload a phone-specific crop under Picture for phones. Leave the phone picture empty to reuse the desktop banner. The storefront switches at 639px and below; the same slide's link and alt text are kept on both screen sizes.
When customizing the slideshow code, preserve the <picture> pattern:
<picture> {{#if mobileImage}}<source media="(max-width: 639px)" srcset="{{mobileImage}}">{{/if}} <img src="{{image}}" alt="{{title}}"> </picture>
data.slides supplies image, mobileImage, link, and title for every slide. This is per slide, so a slideshow can have a different phone banner for each desktop banner. The slideshow's separate Side picture setting is for the side-by-side layout, not the mobile banner.
9.Draft → Publish → History
write ──Save draft──▶ DRAFT ──Publish code──▶ LIVE │ preview as you type │ │ old version → History (last 20) │ └──Discard draft──▶ back to live └─ Preview link shows drafts (and runs scripts)
| Action | Who sees it |
|---|---|
| Typing | the editor preview |
| Save draft | you + anyone with a Preview link |
| Publish code (tick what to publish) | every shopper, on every page using it |
| History, Restore as draft / Restore & publish | — |
- Page Publish does not publish code.
- Two people on one file, *"changed while you were editing"*: Keep mine or Load theirs.
10.Mistakes can't break the store
| Mistake | What happens |
|---|---|
Bad settings.json | red message; can't save |
Broken template ({{#if}} not closed) | Save refused, file + line in red |
| Fails while drawing | preview: red box · store: the built-in original (a from-scratch section is left out) |
| JavaScript error | only that copy stops; console shows it |
Pause custom code (top bar): every customized section/block shows its original, no code scripts run. Nothing deleted.
11.When fcomurs updates a built-in
Your copy never changes by itself. A newer default, Update badge:
- Compare — what changed in the default · yours vs the new one
- Start from the new default — new files go to your draft (your extra settings kept)
- Preview, Publish code
12.Header & footer placeholders
| Header | Footer |
|---|---|
{{logo}} {{store_name}} | {{logo}} {{store_name}} {{about}} |
{{menu}} {{search}} | {{categories}} {{social}} |
{{cart_count}} (updates itself) | {{quick_links}} {{info_links}} {{support_links}} {{extra_links}} |
{{phone}} {{email}} | {{phone}} {{email}} {{address}} {{copyright}} {{year}} |
Turn it on: Use this code in Edit code, Header.
13.Colours & selectors
| CSS variable | For |
|---|---|
var(--primary) | prices, links, accents |
var(--btn-color) / var(--btn-fg) | buttons / their text |
var(--nav-bg) / var(--nav-fg) | header & footer / their text |
var(--background) | page |
| Target | Selector |
|---|---|
| one section / block | #section-<id> · #block-<id> (right-click, Copy CSS selector) |
| a kind | [data-section="product-grid"] · [data-block="button"] |
| all | .fc-section · .fc-heading · [data-code-section] · [data-code-block] |
14.Permissions
| Permission | Can |
|---|---|
| Custom code | write, Save draft, preview, Customize, History |
| Custom code — publish | Publish code, Restore & publish, delete, Pause |
Owner has both. Settings, Staff, Page access.
15.Full example — Trust badges
Badges with a click-to-open detail, plus one product.
{
"settings": [
{ "key": "heading", "label": "Heading", "kind": "text", "default": "Why shop with us" },
{ "key": "product", "label": "Product to show", "kind": "product", "help": "Optional" },
{ "key": "columns", "label": "Badges per row", "kind": "range", "min": 2, "max": 4, "default": 3 }
],
"blocks": [
{
"type": "badge",
"label": "Badge",
"fields": [
{ "key": "icon", "label": "Icon", "kind": "text", "default": "✓" },
{ "key": "title", "label": "Title", "kind": "text", "default": "Easy returns" },
{ "key": "detail", "label": "Detail (opens on click)", "kind": "textarea" }
]
}
],
"starter": [
{ "type": "badge", "settings": { "title": "Easy returns", "detail": "Change your mind within 7 days." } },
{ "type": "badge", "settings": { "icon": "⚡", "title": "Fast delivery", "detail": "Inside Dhaka in 1–2 days." } },
{ "type": "badge", "settings": { "icon": "↺", "title": "Easy returns", "detail": "Change your mind within 7 days." } }
],
"max_blocks": 8
}<section class="tb"> {{#if settings.heading}}<h2 class="tb-title">{{settings.heading}}</h2>{{/if}} <ul class="tb-list" style="--tb-cols: {{default settings.columns 3}}"> {{#each blocks}} {{#if (eq type "badge")}} <li class="tb-badge"> <button type="button" class="tb-head" aria-expanded="false"> <span class="tb-icon" aria-hidden="true">{{default settings.icon "✓"}}</span> {{settings.title}} </button> {{#if settings.detail}}<p class="tb-detail" hidden>{{settings.detail}}</p>{{/if}} </li> {{/if}} {{/each}} </ul> {{#with settings.product}} <a class="tb-product" href="{{url}}"> <img src="{{image}}" alt="{{title}}" loading="lazy"> <span>{{title}} — {{money price}}</span> </a> {{/with}} </section>
.tb { max-width: 1100px; margin: 0 auto; padding: 40px 20px; } .tb-title { margin: 0 0 20px; font-size: 26px; font-weight: 700; text-align: center; } .tb-list { display: grid; grid-template-columns: repeat(var(--tb-cols), minmax(0, 1fr)); gap: 12px; margin: 0; padding: 0; list-style: none; } @media (max-width: 640px) { .tb-list { grid-template-columns: 1fr; } } .tb-badge { border: 1px solid #e5e5e5; border-radius: 8px; } .tb-head { display: flex; width: 100%; align-items: center; gap: 10px; padding: 14px 16px; border: 0; background: none; font: inherit; font-weight: 600; text-align: left; cursor: pointer; } .tb-icon { color: var(--primary); } .tb-detail { margin: 0; padding: 0 16px 14px 42px; opacity: 0.75; } .tb-product { display: flex; align-items: center; gap: 12px; margin-top: 20px; color: inherit; text-decoration: none; } .tb-product img { width: 64px; height: 64px; object-fit: cover; border-radius: 8px; }
section.querySelectorAll('.tb-head').forEach((head) => { const detail = head.nextElementSibling; if (!detail) return; head.addEventListener('click', () => { const open = head.getAttribute('aria-expanded') === 'true'; head.setAttribute('aria-expanded', String(!open)); detail.hidden = open; }); });
| Then | |
|---|---|
| Save draft | red bar = a mistake, with the file |
| Place it | Add section, Code sections, Trust badges, pick a product |
| Test the script | Preview (beside Publish) |
| Go live | Publish code, tick it, Publish; then the page's Publish |
| Undo | History, Restore & publish · or Pause custom code |
As a block instead: Your blocks, + New, Badge; its .json has only settings (icon, title, detail); script uses block instead of section.
16.Limits & fixes
| Limit | |
|---|---|
| Each file | 100,000 characters (.json 20,000) |
| Code sections / blocks per store | 50 / 50 |
| History | last 20 publishes each |
| Problem | Fix |
|---|---|
| Saved, store unchanged | Save draft is only a draft, Publish code |
| No Publish button | you have write-only access — ask the owner |
| Script does nothing | not in the editor preview — use Preview; check console |
| CSS hits other sections | start selectors with #section-<id> or your own class |
{{settings.x}} empty | not in .json, or empty, {{default settings.x "…"}} |
| My block isn't in Add block | that section doesn't accept it — use Rich text / Custom section |
| Customized section looks like the original | code paused, or its template fails — see the preview's red box |
