Theme Architecture

Understanding the architecture and design principles of themes.

Overview

Finqu themes are built to be modular, flexible, and easy to customize. The architecture separates content, layout, and presentation, allowing developers to create unique storefronts while maintaining maintainability and scalability.

A theme consists of templates, sections, blocks, assets, and configuration files. These components work together to define the structure, appearance, and behavior of a storefront.

Theme Engine

The theme engine processes theme files and renders storefront pages dynamically. It interprets Liquid templates, processes section and block schemas, and merges user settings to generate the final HTML output. The engine supports localization, dynamic content, and extensibility through custom sections and blocks.

Template Structure

Templates define the overall layout and structure of pages. They use placeholders like content_for_index to render sections and can include specific sections or blocks using tags. Templates are stored in the templates directory and are responsible for the page’s main structure, such as headers, footers, and content areas.

Section Groups

Section groups are ordered, merchant-managed collections of sections shared across pages — for example a header or footer region that appears on every template. Unlike a template’s own sections (which live only on that template), sections in a group are stored once and rendered wherever the group is included via the {% sections %} tag. Group definitions live in the section-groups/ directory. See Sections and Templates & Layouts for details.

Sections

Sections are modular components that can be added, removed, or reordered within templates or section groups. They are stored in the sections directory and defined by a schema that describes their settings, blocks, and appearance. Sections are rendered using the content_for_index placeholder, the section tag, or as part of a section group.

Blocks

Blocks are reusable content elements that live inside sections. They are defined in the blocks directory and configured via a schema. Most blocks render content directly; layout blocks can contain child blocks in named containers (nesting is limited to a single level). Blocks are rendered within sections using the container tag or can be rendered statically with the block tag. See Blocks for placement rules.

Placement Model

Placement is controlled along three independent axes. All fields are opt-in and backward compatible — a schema with none of them behaves exactly as before.

Axis	Where declared	Question it answers
Template	`templates` on a section/block schema	On which page types may this be used?
Region	`section_groups` on a section + `allowed_sections` on a group	Which group/region may this section live in?
Block target	`private` on a block + `allowed_blocks` on a container/section	Which blocks may live in this container or section?

See Sections and Blocks for schema details and examples.

Asset Pipeline

Assets such as CSS, JavaScript, images, and fonts are stored in the assets directory. The asset pipeline processes and delivers these files efficiently to the storefront, supporting features like minification, versioning, and caching.

Settings and Configuration

Theme settings are defined in settings_schema.json and individual section/block schemas. These settings allow merchants to customize the look and feel of their store without editing code. Settings are exposed in the theme editor and merged with defaults during rendering.

Best Practices

Keep templates, sections, and blocks modular and reusable.
Use settings and schema definitions to maximize flexibility.
Organize assets and configuration files logically.
Test themes thoroughly to ensure compatibility and performance.

This architecture enables developers to build powerful, maintainable, and customizable themes for the Finqu platform.