Variants and theme settings

So far every page renders with the same template. Two missing pieces:

• Variants. An editor working on a hero-led landing page and an editor maintaining a standard "About" page want different layouts. Variants let one content type — page — have multiple template options, with the editor picking which one applies per record.
• Theme settings. Things that should be the same across the whole site — site name, social links, footer copyright — don't belong on individual page records. They belong in theme settings, configured once by the editor and read everywhere.

You'll add both.

Step 1 — Create a homepage variant

Variants are template files named <content-type>.<variant-name>.liquid. A variant called homepage for the page content type lives at templates/page.homepage.liquid.

Create it:

{% if template_settings.heroTitle or template_settings.heroImage %}
  <section class="hero">
    {% if template_settings.heroImage %}
      <img class="hero__image" src="{{ template_settings.heroImage.url }}" alt="">
    {% endif %}
    {% if template_settings.heroTitle %}
      <h1 class="hero__title">{{ template_settings.heroTitle }}</h1>
    {% endif %}
  </section>
{% endif %}

<article class="page-content">
  {% if page.content_html %}
    <div class="page-content__body s-prose">
      {{ page.content_html | raw }}
    </div>
  {% endif %}

  {% stageblocks page %}
</article>

{% schema %}
{
  "settings": [
    {
      "type": "text",
      "name": "heroTitle",
      "label": "Hero title"
    },
    {
      "type": "upload",
      "name": "heroImage",
      "label": "Hero image",
      "relationTo": "media"
    }
  ],
  "blocks": ["text-section", "image-feature", "feature-grid"]
}
{% endschema %}

A few new ideas:

• The {% schema %} here declares two template-level settings. They appear as fields the editor can fill in on records using this variant. Their values are available in Liquid as template_settings.<name>.
• The blocks array carries forward — the variant supports the same three blocks the default page template does.

Step 2 — Pick the variant in the admin

Open a page record in your Basker admin and look for the template option in the sidebar. The dropdown lists every variant available for the page content type — including your new homepage one. Choose it and save.

The hero title and hero image fields will appear on the record once homepage is selected. Fill them in, save again, and switch to your dev-server browser. The page now renders the hero block above the body.

You can use this variant for your homepage or for any landing page that needs a hero — it's a regular template, not tied to the site's root URL.

Step 3 — Add theme-wide settings

Theme settings are declared in config/settings_schema.json. The file is a JSON array of setting groups; each group has a name and a list of fields. The editor configures values once in the admin's theme settings panel, and you read them in Liquid as settings.<group>.<field>.

Create config/settings_schema.json:

[
  {
    "name": "theme_settings",
    "theme_name": "My Theatre",
    "theme_version": "1.0.0"
  },
  {
    "name": "site",
    "label": "Site",
    "type": "group",
    "fields": [
      {
        "type": "text",
        "name": "name",
        "label": "Site name",
        "default": "My Theatre"
      },
      {
        "type": "text",
        "name": "tagline",
        "label": "Tagline"
      }
    ]
  },
  {
    "name": "social",
    "label": "Social links",
    "type": "array",
    "fields": [
      {
        "type": "text",
        "name": "label",
        "label": "Label"
      },
      {
        "type": "url",
        "name": "href",
        "label": "URL"
      }
    ]
  }
]

Three things to note:

• The first entry is special. A group named theme_settings carries metadata about the theme itself — the human-readable name and the version. It's not a settings group editors interact with.
• site is a group — fields nest underneath it and are read as settings.site.name, settings.site.tagline.
• social is an array — the editor adds as many entries as they like, each with label and href. You iterate it with {% for link in settings.social %}.

Step 4 — Use the settings in your components

Update components/global-header.liquid to read the site name from settings:

<header class="site-header">
  <a href="/" class="site-header__logo">{{ settings.site.name }}</a>
  <nav class="site-header__nav">
    <a href="/about">About</a>
    <a href="/events">What's on</a>
    <a href="/contact">Contact</a>
  </nav>
</header>

Update components/global-footer.liquid to render the social links:

<footer class="site-footer">
  <p>&copy; {{ 'now' | date: '%Y' }} {{ settings.site.name }}</p>

  {% if settings.social.size > 0 %}
    <ul class="site-footer__social">
      {% for link in settings.social %}
        <li>
          <a href="{{ link.href }}">{{ link.label }}</a>
        </li>
      {% endfor %}
    </ul>
  {% endif %}
</footer>

Step 5 — Configure the values

For the editor to fill the settings in, the theme has to be uploaded first — local development reads them from a fallback. You'll do the upload on the Validate and upload page; once uploaded, the theme settings panel in the admin shows the fields you defined here.

While developing locally, you can set sensible defaults in the schema (like "default": "My Theatre") so the dev server has something to render before any editor configuration exists.

What's next

Pull live event data — wire up a calendar block backed by the FrontStage API.

Going deeper

• Settings — full schema reference for theme and template settings.
• Field types — every field type available in any settings array.
• Templates overview — variant naming rules per content type.