Templating Basics

Squarespace sites store their content using a JSON data dictionary, which you can see by adding ?format=json-pretty to the end of any site URL. This page will show some examples of how we use JSON-T to display JSON data on template pages.

NOTE: The examples on this page require an understanding of JSON key/value pairs. If you aren't familiar with what JSON Data is, please see the introduction to JSON page.

Rendering JSON Data

In order to show data on a page, you first need to scope into the appropriate section of JSON Data. Then you can display data by using curly brackets around any JSON key inside that section. In this basic example, we'll show a Page Title:

// JSON Data

{
  "collection" : {
    "title" : "Page Title",
    "description" : "This is the page description."
  }
}

<!-- Template code (JSON-T) -->
{.section collection}
  <h1>{title}</h1>
  <p>{description}</p>
{.end}

<!-- Rendered values in HTML -->
<h1>Page Title</h1>
<p>This is the page description.</p>

Handling an Array

When scoping into a section with multiple items, commonly known as an array, JSON-T uses the syntax {.repeated section key}{.end} instead of {.section key}{.end}. Every piece of code within the opening and closing scope tags will be repeated for each item in the array.

// JSON Data

{
  "items" : [
    {
      "title" : "First Item",
      "description" : "This is the first item description."
    },
    {
      "title" : "Second Item",
      "description" : "This is the second item description."
    },
    {
      "title" : "Third Item",
      "description" : "This is the third item description."
    }
  ]
}

<!-- Template code (JSON-T) -->
{.repeated section items}
  <article>
    <h1>{title}</h1>
    <p>{description}</p>
  </article>
{.end}

<!-- Rendered values in HTML -->
<article>
  <h1>First Item</h1>
  <p>This is the first item description.</p>
</article>
<article>
  <h1>Second item</h1>
  <p>This is the second item description.</p>
</article>
<article>
  <h1>Third Item</h1>
  <p>This is the third item description.</p>
</article>

Render Data from Multiple Sections

In your template you'll more than likely have a need to scope into multiple sections on any given page. You can do this by ending one scope tag and entering another.

// JSON Data

{
  "website" : {
    "siteTitle" : "My Website",
    "baseUrl" : "http://developers.squarespace.com"
  },
  "collection" : {
    "title" : "Page Title",
    "description" : "This is the page description."
  }
}

<!-- Template code (JSON-T) -->

{.section website}
  <header>
    <h1><a href="{baseUrl}">{siteTitle}</a></h1>
  </header>
{.end}
{.section collection}
  <section>
    <h1>{title}</h1>
    <p>{description}</p>
  </section>
{.end}

<!-- Rendered values in HTML -->

<header>
  <h1><a href="http://developers.squarespace.com">My Website</a></h1>
</header>
<section>
  <h1>Page Title</h1>
  <p>This is the page description.</p>
</section>

Section with no Data

If a section or repeated section has an empty value, nothing inside the scope tags will be outputted.

// JSON Data

{
  "collection" : { }
}

<!-- Template code (JSON-T) -->

{.section collection}
  <section>
    <h1>{title}</h1>
    <p>{description}</p>
  </section>
{.end}

<!-- Rendered values in HTML -->

Using an Or Statement

If a section or repeated section has no value, an or statement outputs alternative markup to express that empty value.

// JSON Data

{
  "items" : [ ]
}

<!-- Template code (JSON-T) -->

{.repeated section items}
  <article>
    <h1>{title}</h1>
    <p>{description}</p>
  </article>
{.or}
  <p>There are no items here.</p>
{.end}

<!-- Rendered values in HTML -->

<p>There are no items here.</p>

Using Dot Notation

You can add any JSON value to your template by writing the key and its parent object in dot notation. This method of scoping only defines the scope for this one single value, so no end tag is required in JSON-T.

// JSON Data

{
  "collection" : {
    "title" : "Page Title",
    "description" : "This is the page description."
  }
}

<!-- Template code (JSON-T) -->

<h1>{collection.title}</h1>
<p>{collection.description}</p>

<!-- Rendered values in HTML -->

<h1>Page Title</h1>
<p>This is the page description.</p>

Referencing the Scope

Using scope reference, written as {@}, allows you to reference the key you're scoped into. This is like (this) in JavaScript.

// JSON Data

{
  "collection" : {
    "title" : "Page Title",
    "description" : "This is the page description."
  }
}

<!-- Template code (JSON-T) -->

{.section collection}
  {.section title}<h1>{@}</h1>{.end}
  {.section description}<p>{@}</p>{.end}
{.end}

<!-- Rendered values in HTML -->

<h1>Page Title</h1>
<p>This is the page description.</p>

Using an If Statement

If statements check to see if a section exists without scoping into that section.

// JSON Data

{
  "items" : [
    {
      "title" : "First Item",
      "description" : "This is the first item description."
    },
    {
      "title" : "Second Item",
      "description" : "This is the second item description.",
      "featured" : true
    },
    {
      "title" : "Third Item",
      "description" : "This is the third item description."
    }
  ]
}

<!-- Template code (JSON-T) -->

{.repeated section items}
  {.if featured}
    <article class="featured-post">
      <h1>{title}</h1>
      <p>{description}</p>
    </article>
  {.or}
    <article>
      <h1>{title}</h1>
      <p>{description}</p>
    </article>
  {.end}
{.end}

<!-- Rendered values in HTML -->

<article>
  <h1>First Item</h1>
  <p>This is the first item description.</p>
</article>
<article class="featured-post">
  <h1>Second item</h1>
  <p>This is the second item description.</p>
</article>
<article>
  <h1>Third Item</h1>
  <p>This is the third item description.</p>
</article>