Contributors:

JSON (parsing via Liquid)

This component parses JSON data for use in Liquid, either from a remote source, a local file, or string.

{% component type: "json", source_type: "<your-json-source-type>", source: "<your-json-source>" %}

Parameters and Options

type

json

This system parameter identifies the type of component for processing the data.

source_type

path
url
string

Defines the type of JSON source you will be working with.
path The JSON file will be found at a local, relative file path, eg: '/some/path/filename.json'
url The JSON data will be found at an external (or local) location via an absolute URL, eg: 'https://some.domain/some_api'
string The JSON data will be provided directly to the component source parameter as a string, eg: '{"some":"value"}'

source

<YOUR JSON FILE PATH OR STRING>

The local file path, data URL, or JSON string to parse (corresponding to your source_type value).

layout

<path/to/layout>

Path to file that will contain the Liquid layout content to be parsed.

If an empty string, nothing will be rendered.
If paramater is not included, the default virtual layout will be rendered (see below).

collectionVariable

<yourLiquidVariableName>

Assigns the data to a Liquid collection enabling further access to the data on the Page or Template using Liquid.

Your collectionVariable value must only contain English letters, numbers or underscores. Spaces or special characters are not supported.

Liquid Output

Let's assume your JSON source is a list of students in a class and is simply a string available on the page you're working on. To make it easier to work with we'll use a Liquid capture, with the variable name of jsonExample, to grab that JSON string:

{% capture jsonExample %}
{
    "class": {
        "id": 123456,
        "name": "Science 101",
        "students": [
            {
                "iq": 160,
                "name": "Einstein"
            },
            {
                "iq": 160,
                "name": "Hawking"
            },
            {
                "iq": 3,
                "name": "Wilson"
            }
        ]
    }
}
{% endcapture %}

You can then more easily use this captured variable in the component tag:

{% component type:"json", source_type: "string", source: "{{jsonExample}}" %}

Providing this JSON to the component results in it being parsed into the Liquid scope ready to be used in your Liquid logic. Therefore, the full output is a JSON object matching the source.

{
  "class": {
    "id": 123456,
    "name": "Science 101",
    "students": [
      {
        "iq": 160,
        "name": "Einstein"
      },
      {
        "iq": 160,
        "name": "Hawking"
      },
      {
        "iq": 3,
        "name": "Wilson"
      }
    ]
  }
}

Virtual Layout

Based on the above example, if not using any custom layout or collection, the default virtual layout is simply {{this}}, which will output the full JSON object:

{
  "class": {
    "id": 123456,
    "name": "Science 101",
    "students": [
      {
        "iq": 160,
        "name": "Einstein"
      },
      {
        "iq": 160,
        "name": "Hawking"
      },
      {
        "iq": 3,
        "name": "Wilson"
      }
    ]
  }
}

Accessing the Data

JSON Output

You can output the full JSON for your component data by referencing the root Liquid object {{this}} in your module’s layouts, or directly on your page, if using the collectionVariable parameter in your component tag.

For example:

{% component type: ... collectionVariable: "myData" %}

You can then render the JSON like so:

{{myData}}

For more details on using this approach, see Part 2 of the free ‘Learning Liquid Course’.

Rendering Property Values

You can provide a layout file that holds the Liquid logic and markup for rendering your parsed JSON data.

In this example, a .layout file has been created in a directory called "layouts", eg: /layouts/student-list.layout.
This file contains the following Liquid markup:

<p><strong>Student List for {{this.class.name}}:</strong></p>
<ul>
{% for i in this.class.students %}
    <li>{{i.name}} ({{i.iq}})</li>
{% endfor %}
</ul>

Now, this file path can be supplied to the component tag to be used as the data's template:

{% component type:"json", source_type: "string", source: "{{jsonExample}}", layout: "/layouts/student-list.layout" %}

Redering in the following:

Student List for Science 101:

Einstein (160)
Hawking (160)
Wilson (3)

This data is also accessible directly on the Page or Template via a Liquid Collection by adding collectionVariable to the Component and suppressing the layout.

{% component type:"json", source_type: "string", source: "{{jsonExample}}", layout: "", collectionVariable: "jsonCollection" %}

You could then render the list of students, similar to the above example using the variable, directly on the page instead of via a layout file:

<p><strong>Student List for {{jsonCollection.class.name}}:</strong></p>
<ul>
{% for i in jsonCollection.class.students %}
    <li>{{i.name}} ({{i.iq}})</li>
{% endfor %}
</ul>