Skip to content
biticaretdevelopers

Themes

Theme structure

The folders, templates, sections, blocks, settings, translations and assets of a biticaret theme, and how it is uploaded, checked, previewed and published.

A theme is a folder of Liquid, JSON, CSS and JavaScript files. The theme renders the storefront, while customer account pages and checkout are owned by the platform. This page explains how a theme is structured and how it is uploaded to a store.

The examples come from the skeleton theme (biticaret theme init).

Folders

layout/      theme.liquid wraps every page; password.liquid wraps the password page
templates/   one template per page type (JSON or Liquid)
sections/    sections and section groups (header-group.json, footer-group.json)
blocks/      theme blocks
snippets/    partials rendered with {% render %}
assets/      CSS, JavaScript, images, fonts
config/      settings_schema.json and settings_data.json
locales/     translations and *.schema.json files

A theme consists solely of these eight folders. Subfolders are allowed only under templates/customers and templates/metaobject.

Upload and check a theme

You upload a theme as a ZIP archive, which arrives as an unpublished theme. Its name comes from the theme_info entry in config/settings_schema.json, or from the ZIP filename if missing. biticaret theme check runs the same checks locally:

  • Limits: the ZIP can be at most 50 MB (200 MB unpacked), and a store can hold up to 20 themes. Files outside the eight theme folders, absolute paths, .. segments and symbolic links are rejected. A single top-level wrapper folder inside the ZIP is accepted.
  • Required files: a missing layout/theme.liquid or a missing index, product, collection, cart, page, search or 404 template is an error. Missing list-collections or password templates, config/settings_schema.json or the default locale file produces a warning.
  • JSON: every JSON file must parse cleanly.
  • Liquid: syntax errors are reported with file and line. Unknown tags or unknown filters are errors. Malformed Liquid that can still render produces a warning.
  • Other: an unparseable visible_if condition or a Sass file (assets/*.scss.liquid) is an error.

Errors block the upload; warnings do not. --strict treats warnings as errors.

You can preview an uploaded theme through its preview link before publishing. biticaret theme list --store <handle> lists a development store's themes and preview URLs (CLI).

Layout

layout/theme.liquid wraps every page. Two objects are required: content_for_header (inside <head>, injecting window.biticaret and compiled asset links) and content_for_layout (the template output).

liquid
<!doctype html>
<html lang="{{ request.locale.iso_code }}">
  <head>
    <title>{{ page_title }}{% unless page_title contains shop.name %} | {{ shop.name }}{% endunless %}</title>
    <link rel="canonical" href="{{ canonical_url }}">
    {{ content_for_header }}
    {{ 'base.css' | asset_url | stylesheet_tag }}
  </head>
  <body class="template-{{ template.name }}">
    {% sections 'header-group' %}
    <main id="main" class="page-width">
      {{ content_for_layout }}
    </main>
    {% sections 'footer-group' %}
  </body>
</html>

A Liquid template can select an alternative layout with {% layout 'name' %}.

Templates

Each page type has a corresponding template. The storefront renders these templates:

Template Page
index Home page
product Product
collection Collection
list-collections List of collections
cart Cart
page Content page
search Search
404 Page not found
password Storefront login page for a password-protected store
gift_card Gift card page
blog Blog (/blogs/<blog>) and tag-filtered blog (/blogs/<blog>/tagged/<tag>)
article Blog post (/blogs/<blog>/<post>)
metaobject/<type> Entry page for a metaobject type with web pages enabled (/pages/<type handle>/<entry handle>); returns 404 without a template

You can add alternate templates for the same type using names such as product.<suffix>.json. The template is resolved from the ?view=<suffix> query parameter first, then the resource's template_suffix, and otherwise the default template. If a suffix does not exist in the theme, the default template is used.

If there is no password template, the platform renders a built-in password form. Policy pages (/policies/<name>) are generated by the platform and rendered inside the theme's layout.

Customer account pages (sign in, account, order details, addresses, profile and personal data requests) are rendered by the platform inside the theme's layout. templates/customers/* files may exist in a theme, but they are not used. Layouts can tell these pages apart via request.page_type (customers/login, customers/account, customers/order, customers/addresses, customers/profile). Customers sign in using a one-time email code; /account/register and /account/recover redirect to the sign-in page. Blog comments are not supported: comment fields are always empty.

A JSON template lists the page's sections and their display order:

json
{
  "sections": {
    "featured-collection": {
      "type": "featured-collection",
      "settings": {}
    }
  },
  "order": [
    "featured-collection"
  ]
}

type is the filename under sections/, and settings holds that section's setting values.

A section's blocks are configured in blocks and block_order:

json
{
  "sections": {
    "featured-collection": {
      "type": "featured-collection",
      "settings": { "heading": "Featured" },
      "blocks": {
        "promo": {
          "type": "promo",
          "settings": { "text": "Free shipping" }
        },
        "note": {
          "type": "promo",
          "disabled": true,
          "settings": { "text": "Hidden note" }
        }
      },
      "block_order": ["promo", "note"]
    }
  },
  "order": ["featured-collection"]
}

blocks maps each block ID to its configuration. type refers either to a block type declared in the section schema's blocks list or to a theme block under blocks/, and settings holds the block's values. Blocks render in block_order (or object key order if block_order is omitted). A block with "disabled": true is skipped. A block with "static": true is excluded from the dynamic list and rendered explicitly by ID ({% content_for 'block', type: 'promo', id: 'note' %}, reading settings from the matching entry in blocks). A theme block can define its own nested blocks and block_order.

Sections

A section is a Liquid file under sections/: its markup followed by its settings schema inside {% schema %}:

liquid
<section class="featured-collection">
  <h2>{{ section.settings.heading | escape }}</h2>
  <ul class="grid">
    {%- for product in featured.products limit: section.settings.limit -%}
      <li>{% render 'product-card', product: product %}</li>
    {%- else -%}
      <li>{{ 'collections.general.empty' | t }}</li>
    {%- endfor -%}
  </ul>
</section>
{% schema %}
{
  "name": "t:sections.featured-collection.name",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "t:sections.featured-collection.settings.heading.label",
      "default": "Featured"
    },
    {
      "type": "collection",
      "id": "collection",
      "label": "t:sections.featured-collection.settings.collection.label"
    }
  ],
  "presets": [
    {
      "name": "t:sections.featured-collection.name"
    }
  ]
}
{% endschema %}

Each section is wrapped in <div id="biticaret-section-<id>" class="biticaret-section">. Setting tag in the schema changes the wrapper element (article, aside, div, footer, header or section), and class appends CSS classes. Inside the section, access its data via section.id, section.settings and section.blocks.

Section groups are lists of sections invoked from the layout ({% sections 'header-group' %}). They follow the same format as JSON templates and are wrapped with class biticaret-section-group-<group>:

json
{
  "type": "header",
  "name": "t:sections.header-group.name",
  "sections": {
    "header": {
      "type": "header",
      "settings": {}
    }
  },
  "order": [
    "header"
  ]
}

{% section 'name' %} renders a single static section directly.

Blocks

A section schema declares which block types it accepts in blocks, and the section loops over section.blocks to render them. Theme blocks under blocks/ are rendered with {% content_for 'blocks' %}, each wrapped in <div id="biticaret-block-<id>" class="biticaret-block …">.

Include {{ block.biticaret_attributes }} on each block's root element so the theme editor can identify and select it; outside the editor, this outputs nothing.

A section whose schema includes {"type": "@app"} in blocks accepts app blocks. App blocks are wrapped in <div id="biticaret-block-<id>" class="biticaret-app-block">. In JSON templates, their type has the form biticaret://apps/<app>/blocks/<name>/<uuid>. If the app is uninstalled, the block produces no output.

App embeds (app blocks injected page-wide) are stored under current.blocks in config/settings_data.json. Enabled embeds are injected before </head> or </body>. Store owners toggle them in the theme editor.

Settings

config/settings_schema.json defines global theme settings. Its first entry, theme_info, declares the theme's name and version:

json
[
  {
    "name": "theme_info",
    "theme_name": "Skeleton",
    "theme_version": "1.0.0",
    "theme_author": "biticaret"
  },
  {
    "name": "t:settings_schema.colors.name",
    "settings": [
      {
        "type": "color",
        "id": "color_background",
        "label": "t:settings_schema.colors.settings.background.label",
        "default": "#ffffff"
      }
    ]
  }
]

config/settings_data.json stores active values under current, which Liquid accesses as settings.<id>:

json
{
  "current": {
    "color_background": "#ffffff",
    "page_width": 1200
  }
}

Store owners edit these values in the admin settings form or in the theme editor; both update settings_data.json.

Setting types:

Type Value
text, textarea, html, richtext, inline_richtext Text
select, radio, text_alignment Selected option
checkbox Boolean (true or false)
number, range Number
color, color_background Color
color_scheme, color_scheme_group Color scheme and scheme definitions (1 to 50 schemes)
font_picker A font from biticaret's font catalogue or a system font
image_picker, video, video_url Image, uploaded video, or YouTube/Vimeo URL
url, link_list URL or menu
product, collection, page, product_list, collection_list Store resources
blog, article Blog or blog post (blog/post handle); exposed in Liquid as blog and article objects
metaobject, metaobject_list One metaobject entry or a list of entries; schema sets metaobject_type. Exposed in Liquid as metaobject entry objects
liquid Liquid snippet (up to 50,000 bytes)

Resource setting values are validated against the store's records on save; missing resources resolve to empty values.

A url setting accepts relative paths, #, http(s), mailto:, tel: and biticaret:// references. When a setting's visible_if condition evaluates to false, the editor hides the setting while preserving its saved value; the storefront still exposes every value.

Translations

locales/ holds one JSON file per language, with .default on the default language file (tr.default.json). Every buyer-facing string is resolved from these files using the t filter:

json
{
  "general": {
    "skip_to_content": "Skip to content"
  }
}
liquid
<a class="skip-link" href="#main">{{ 'general.skip_to_content' | t }}</a>

*.schema.json files store labels displayed in the theme settings form; schemas reference them with t: keys (e.g. "label": "t:settings_schema.colors.settings.background.label").

Assets

Link to files under assets/ with asset_url. The generated URL includes a content-derived ?v= query parameter so caches bust automatically when the file changes:

liquid
{{ 'base.css' | asset_url | stylesheet_tag }}

Do not hard-code CDN or store URLs: always use asset_url, file_url and routes. Sass is not supported. To use theme settings inside a stylesheet, name it assets/<name>.css.liquid: the platform renders it with your settings and you reference it as '<name>.css' | asset_url.

Contents of section {% stylesheet %} and {% javascript %} blocks are compiled into a single bundle for the theme and included by content_for_header.

Theme boundaries: cart and checkout

The theme renders the cart page (templates/cart) and add-to-cart UI, updating the cart via /cart/*.js endpoints (Endpoints a theme calls). The checkout (/checkouts/<cart token>) is owned by the platform: themes cannot render or customize checkout templates. Totals, shipping methods, payment methods and consent checkboxes are rendered by the platform's own interface. Apps customize checkout through extensions (checkout functions and UI extensions: App configuration files); themes play no part in checkout.

Preview and publish

In the admin, Online Mağaza > Temalar (Online store > Themes) shows the published theme and the theme library. Every uploaded or duplicated theme starts unpublished with its own Önizle (Preview) link, which appends ?preview_theme_id=<theme id> to the store URL. The storefront stores the ID in a signed cookie and redirects to the clean URL so the browser stays in preview mode; passing an empty ID clears the preview. Anyone with the link can preview the theme, though password-protected stores still require the storefront password.

When ready, clicking Yayınla (Publish) makes the theme live for visitors. Kopyala (Duplicate) creates an unpublished copy so you can iterate without affecting the published theme. A store can hold up to 20 themes. There is no theme store yet: themes are uploaded as ZIP files and remain scoped to the store they are uploaded to.

Endpoints a theme calls

  • Cart: /cart.js, /cart/add.js, /cart/change.js, /cart/update.js, /cart/clear.js (also with .json). Cart mutation requests can pass sections to receive updated HTML under sections, rendered in the context of sections_url (or the referring page).
  • Cart and localization form submissions are accepted only from the store's own pages: requests from external origins receive 403 and are ignored.
  • Product: /products/<product>.js returns the product with all its variants as JSON.
  • Section rendering: ?sections=<id,…> (up to five sections) and ?section_id=<id>.
  • Search suggestions: /search/suggest.json. Product recommendations: /recommendations/products.
  • Blog feed: /blogs/<blog>.atom.

Names and JavaScript

  • In HTML, CSS and JavaScript: biticaret-section-<id>, biticaret-section, biticaret-block-<id>, biticaret-app-block.
  • window.biticaret: shop, locale, currency, country, theme, routes.root and designMode.
  • window.biticaret.customerPrivacy exposes cookie consent APIs: analyticsProcessingAllowed(), marketingAllowed(), preferencesProcessingAllowed(), shouldShowBanner(), showPreferences(), setTrackingConsent({ analytics, marketing, preferences }, callback) and currentVisitorConsent(). Any hidden link or button with data-biticaret-privacy-preferences is shown automatically while the cookie banner is active and reopens preferences on click.
  • window.biticaret.analytics.publish(name, data) sends a custom event to installed web pixels (Web pixels).
  • The theme editor dispatches these DOM events on section and block elements: biticaret:section:load, biticaret:section:unload, biticaret:section:select, biticaret:section:deselect, biticaret:section:reorder, biticaret:block:select, biticaret:block:deselect. Inside the editor, request.design_mode is true.

Reference