Skip to main content

Layouts

Layouts serve as the structural foundation of a Soppiya theme. They act as the master wrappers through which all page templates are rendered. By hosting repeated elements—such as metadata, global navigation, and footers—in a single file, Layouts ensure design consistency across the storefront while keeping the codebase maintainable.

Folder Location​

Layout files are stored in the /layout directory at the root of your theme structure.

└── theme
    └── layout
        ├── theme.liquid      # Primary storefront layout
        └── password.liquid   # Restricted access layout

Core Layout Files​

theme.liquid​

This is the default layout file for your store. Unless specified otherwise in a template, every page (Home, Product, Collection, etc.) is rendered through this file. It typically contains the HTML <head> and the global site wrappers.

password.liquid​

A specialized layout used exclusively when the store is under Password Protection (Maintenance Mode). It allows you to display a branded "Coming Soon" or "Maintenance" page while hiding the actual storefront from the public.

Required Platform Objects​

For the Soppiya rendering engine to function, two critical Liquid objects must be present in every layout file.

ObjectLocationDescription
{{ content_for_header }}Inside <head>Dynamically injects platform-critical scripts, SEO metadata, app integrations, and security tokens.
{{ content_for_layout }}Inside <body>The primary content slot. It dynamically outputs the content of the specific Template being viewed.

[!CAUTION]
Mandatory Objects: If either content_for_header or content_for_layout is missing, the theme will fail to save or render properly, as the platform cannot inject required system logic.

Component Rendering Tags​

Soppiya uses specialized tags to bring modularity into the layout files.

The render Tag​

Used to include reusable pieces of code from the /snippets folder.

  • Syntax: {% render 'filename' %}
  • Data Passing: You can pass dynamic data to a snippet using parameters:
    {% render 'product-card', data: product_info %}
  • Note: Do not include the .liquid extension in the filename.

The sections Tag​

A powerful plural tag used to render Section Groups (JSON files from the /sections folder).

  • Syntax: {% sections 'header-group' %}
  • Usage: Typically used in the layout to allow merchants to manage multiple sections (like an announcement bar and a logo bar) within a single area.

Technical Implementation Example​

The following boilerplate illustrates a standard theme.liquid implementation, including asset loading and conditional logic.

<!doctype html>
<html class="no-js" lang="{{ request.locale.iso_code }}">
<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    
    <!-- Injects Soppiya System Scripts -->
    {{ content_for_header }}

    <title>{{ page_title | default: "Soppiya Store" }}</title>

    <!-- Global Assets -->
    <link rel="stylesheet" href="{{ 'global.css' | asset_url }}" />
    <script src="{{ 'soppiya.js' | asset_url }}" defer></script>

    <!-- Custom Typography -->
    <style>
        @font-face {
            font-family: 'ProductSans';
            src: url('{{ 'product-sans-regular.ttf' | asset_url }}') format('ttf');
        }
    </style>
</head>

<body class="{% if template == 'cart' %} bg__color {% endif %}">

    {%- comment -%} Render Header Group (Excluded on Checkout) {%- endcomment -%}
    {% if template != 'checkout' %}
        {% sections 'header-group' %}
    {% endif %}

    <main role="main">
        <!-- Template Content Injection Point -->
        {{ content_for_layout }}
    </main>

    {% sections 'footer-group' %}

</body>
</html>

Developer Best Practices​

note

Performance Optimization: Always use the asset_url filter when calling CSS or JS files. This ensures your files are served from Soppiya's global CDN with automatic versioning for cache busting.

tip

Contextual Styling: Adding a conditional class to the <body> tag based on the template object (e.g., template == 'cart') allows you to apply specific CSS overrides that only trigger on certain pages.

important

Language Localization: Utilize {{ request.locale.iso_code }} in the HTML lang attribute to ensure search engines and browsers identify the correct language of your storefront dynamically.