Skip to main content

Templates

Templates group widgets into reusable regions that appear on every page (header, footer, global elements).

Template Files​

templates/
├── header.json    # Header area (announcement bar + navigation)
├── footer.json    # Footer area (footer widget)
└── global.json    # Global widgets (WhatsApp button, mobile nav)

Template Structure​

Each template file contains:

{
  "title": "Header",
  "allowAdd": true,
  "allowRemove": true,
  "allowReorder": true,
  "widgets": [
    {
      "name": "announcement-bar",
      "widget": "announcement-bar",
      "settings": { ... },
      "blocks": [ ... ]
    },
    {
      "name": "header",
      "widget": "header",
      "settings": { ... }
    }
  ]
}

Properties​

PropertyTypeDescription
titlestringDisplay name in the theme builder
allowAddbooleanAllow adding new widgets
allowRemovebooleanAllow removing widgets
allowReorderbooleanAllow reordering widgets
widgetsarrayList of widget instances

Common Templates​

header.json​

Groups widgets for the site header:

{
  "title": "Header",
  "allowAdd": true,
  "allowRemove": true,
  "allowReorder": true,
  "widgets": [
    {
      "name": "announcement-bar",
      "widget": "announcement-bar",
      "settings": {
        "backgroundColor": "#003033",
        "textColor": "#ffffff"
      },
      "blocks": [
        {
          "block": "announcement",
          "name": "Announcement 1",
          "settings": {
            "text": "Free shipping on orders over $50",
            "link": "/collections"
          }
        }
      ]
    },
    {
      "name": "header",
      "widget": "header",
      "settings": {
        "showSearch": true,
        "showCart": true,
        "showAccount": true,
        "showWishlist": true
      }
    }
  ]
}

footer.json​

Groups widgets for the site footer:

{
  "title": "Footer",
  "allowAdd": true,
  "allowRemove": true,
  "allowReorder": true,
  "widgets": [
    {
      "name": "footer",
      "widget": "footer",
      "settings": {
        "showNewsletter": true,
        "showPaymentMethods": true,
        "copyrightText": "© 2024 Store Name. All rights reserved."
      }
    }
  ]
}

global.json​

Groups widgets that appear globally (floating elements, mobile navigation):

{
  "title": "Global",
  "allowAdd": true,
  "allowRemove": true,
  "allowReorder": true,
  "widgets": [
    {
      "name": "whatsapp-button",
      "widget": "whatsapp-button",
      "settings": {
        "phoneNumber": "+1234567890",
        "defaultMessage": "Hello! I have a question."
      }
    },
    {
      "name": "mobile-nav",
      "widget": "mobile-nav",
      "settings": {}
    }
  ]
}

Template Rendering Order​

Define the order in settings/templates-settings.json:

{
  "templates_order": ["header", "global", "main", "footer"]
}

The main entry represents the page content ({% content %}).

Using Templates in Layout​

Include templates in your layout.njk:

<!DOCTYPE html>
<html lang="ar" dir="rtl">
  <head>
    {% seo %}
    {% qumra_head %}
    <link rel="stylesheet" href="{{ 'style.css' | assets }}">
  </head>
  <body>
    {% template "header" %}

    <main>
      {% content " " %}
    </main>

    {% template "footer" %}
    {% template "global" %}

    {% qumra_scripts %}
    <script src="{{ 'main.js' | assets }}"></script>
  </body>
</html>

Tips​

Best Practices
  • Group related widgets logically (all header widgets in header.json)
  • Use global.json for floating elements like WhatsApp buttons
  • Set allowAdd: false for templates that should have fixed widgets
  • Order templates in templates-settings.json to control rendering sequence