12.1. Convert JSON to HTML

JSON [1], which is an acronym for JavaScript Object Notation, is a text-based format for representing structured data. Websites utilize this format to send structured data to the front end and then process that data via JavaScript to convert it to HTML that is styled beautifully for humans to consume. For example, you might be familiar with Google’s structured data [2], which is data about a webpage added to the source code of the page in JSON format so that Google can easily process the page and show it in the search results. Another example would be JavaScript frameworks, such as NextJS, increasingly being used to create websites. These frameworks include the page’s data in JSON format and then convert it to HTML for users to consume the information of the page easily. Moreover, JSON is a format used by computer systems when interacting with each other. An example for such a system is an API [3]. Websites might also retrieve JSON data from an API by making a request after the page is loaded. So, in short, JSON is a format heavily used to create websites and transfer data. Therefore, the plugin has a feature that converts JSON to HTML. The plugin works by processing HTML. By converting JSON to HTML, the plugin becomes capable of working with JSON as well.

JSON to HTML conversion can be done via Convert JSON to HTML and Convert JSON to HTML automatically? settings, as well as via Convert to HTML and Convert to HTML automatically filter commands.

The plugin has two ways of converting JSON to HTML. The first one is completely automatic, while the second one gives you the control. The following sections describe these two ways.

12.1.1. Converting JSON to HTML automatically

When a JSON string is given, the plugin can convert it to HTML automatically. Let’s examine the following example.

Example:

JSON:

{
  "id": 3,
  "content": {
    "paragraph": "This is a paragraph",
    "tags": ["tag1", "tag2"],
    "url": "http://some.url/post/1"
  }
}

HTML:

<div class="wpcc-converted-json wpcc-generated-container">
  <div class="id" data-key="id">3</div>
  <div class="content" data-key="content">
    <div class="paragraph" data-key="paragraph">
        This is a paragraph
    </div>
    <div class="tags" data-key="tags">
      <div data-index="0">tag1</div>
      <div data-index="1">tag2</div>
    </div>
    <a class="url"
       data-key="url"
       href="http://some.url/post/1"
       target="_blank"
       rel="nofollow noopener noreferrer">
        http://some.url/post/1
    </a>
  </div>
</div>

In the example given above, JSON string is converted to the shown HTML code automatically by the plugin. The plugin encapsulates the generated JSON code with a div element that has wpcc-converted-json class. Each JSON field whose value is not a URL is converted to a div element. The fields with a URL value are converted to a elements. Each created element has a class name that is the same as the field’s name. The elements for the items that are not array items have a data-key attribute whose value is the name of their field. The elements for the items that are array items have a data-index attribute that specifies the array index of the item. The values of the items are defined as the inner HTML of the generated elements. For the nested fields, the plugin creates nested HTML elements, as it can be seen in the example above.

Once the JSON data is converted to HTML, you can use the generated elements as if the target page’s source code already contains them. You can write CSS selectors that select those values, just like you do for the elements existing in the source code of the target page.

12.1.2. Converting JSON to HTML via a template

Converting JSON to HTML automatically is useful when you need to retrieve values from JSON data. However, you might want to convert JSON data to HTML that has a specific structure. For example, let’s assume that the JSON data contains image URLs that you want to show as a gallery on the front end of your website. In that case, you probably have a custom stylesheet and/or JavaScript code loaded on your website’s front end that displays the images as gallery. So, you need to create the gallery HTML in a predefined structure that defines HTML elements with certain classes, container elements, and so on. In that case, you can achieve your goal by converting the JSON data to HTML via a template.

Let’s examine the following example.

Example 1:

JSON:

{
  "title": "My title",
  "images": [
    "https://some.domain/image1.jpg",
    "https://some.domain/image2.jpg",
    "https://some.domain/image3.jpg"
  ]
}

Template:

<div class="my-gallery">
    [wcc-item images.*]
        <img src="[wcc-item]">
    [/wcc-item]
</div>

Result:

<div class="wpcc-converted-json wpcc-generated-container">
    <div class="my-gallery">
        <img src="https://some.domain/image1.jpg">
        <img src="https://some.domain/image2.jpg">
        <img src="https://some.domain/image3.jpg">
    </div>
</div>

The example above converts the specified JSON data to the resultant HTML by using the shown template. In the template, you can write any HTML code. To retrieve values from the JSON data, [wcc-item] short code is used. This short code can be used in two ways. The first one is to directly write [wcc-item]. In this case, the short code will be replaced with the current value. The second one is to specify a JSON path, as it is done via [wcc-item images.*] in the example. This short code retrieves all the values of the images field of the JSON data, which are all image URLs. Because we want to use each image URL to create an img element, we close the short code via [/wcc-item]. Now, as the short code’s content, we can define any HTML element and use the current item via [wcc-item] short code, as it is done in the example above, to create an img element for each image URL.

Usages of the [wcc-item] short code in the template:

Field value retrieval:  

[wcc-item path.to.field]

Loop definition:  

[wcc-item path.to.array.*]
    <span>[wcc-item]</span>
    <span>[wcc-item path.to.field.in.item]</span>
[/wcc-item]

Nested loops:

[wcc-item path.to.array.*]
    [wcc-item path.to.field.in.item.*]
        <span>[wcc-item]</span>
    [/wcc-item]
[/wcc-item]

Let’s look at a few examples to clarify the usages.

Example 2 (Nested loops):

In a loop, [wcc-item] short code always points to the current value of its loop. For the nested loop case, the short code cannot be used to retrieve a value from an outer loop. So, as it is shown in this example, if the current value of the loop is an array or JSON object, you can use the short code with a JSON path to retrieve a value from that array or JSON object. This makes it possible to create nested loops.

JSON:

{
  "data": {
    "description": "List of items",
    "items": [
      {
        "name": "Item 1",
        "values": ["Value 11", "Value 12"]
      },
      {
        "name": "Item 2",
        "values": ["Value 21"]
      }
    ]
  }
}

Template:

<div id="converted-items">
    <p>[wcc-item data.description]</p>
    <div class="items">
        [wcc-item data.items.*]
            <div class="item">
                <h2>[wcc-item name]</h2>
                <ul class="values">
                    [wcc-item values.*]
                        <li>[wcc-item]</li>
                    [/wcc-item]
                </ul>
            </div>
        [/wcc-item]
    </div>
</div>

Result:

<div class="wpcc-converted-json wpcc-generated-container">
    <div id="converted-items">
        <p>List of items</p>
        <div class="items">
            <div class="item">
                <h2>Item 1</h2>
                <ul class="values">
                    <li>Value 11</li>
                    <li>Value 12</li>
                </ul>
            </div>
            <div class="item">
                <h2>Item 2</h2>
                <ul class="values">
                    <li>Value 21</li>
                </ul>
            </div>
        </div>
    </div>
</div>

Example 3 (Multiple wildcards in JSON path):

JSON:

{
  "data": {
    "description": "List of items",
    "items": [
      {
        "name": "Item 1",
        "values": ["Value 11", "Value 12"]
      },
      {
        "name": "Item 2",
        "values": ["Value 21"]
      }
    ]
  }
}

Template:

<ul id="values">
    [wcc-item data.items.*.values.*]
        <li>[wcc-item]</li>
    [/wcc-item]
</ul>

Result:

<div class="wpcc-converted-json wpcc-generated-container">
    <ul id="values">
        <li>Value 11</li>
        <li>Value 12</li>
        <li>Value 21</li>
    </ul>
</div>

Example 4 (Retrieving separate values from the same JSON object):

In this example, there are two notable things. The first one is that the HTML code in the content field is escaped when it is converted to HTML. The second one is that the array values are combined with space characters when they are retrieved directly, without defining a loop. You can see this behavior by observing how the tags field is converted to HTML.

JSON:

{
  "title": "My post",
  "content": "This is <b>the content</b> of the post.",
  "tags": ["Tag 1", "Tag 2"],
  "youtubeVideoId": "A96kT-jt9RQ"
}

Template:

<div id="my-post">
    <h1>[wcc-item title]</h1>
    <div class="content">
        [wcc-item content]
    </div>

    <iframe
        src="https://www.youtube.com/embed/[wcc-item youtubeVideoId]"
        allow="accelerometer; autoplay; encrypted-media;
            gyroscope; picture-in-picture"
        allowfullscreen>
    </iframe>

    <div class="tags">
        [wcc-item tags]
    </div>
</div>

Result:

<div class="wpcc-converted-json wpcc-generated-container">
    <div id="my-post">
        <h1>My post</h1>
        <div class="content">
            This is &lt;b&gt;the content&lt;/b&gt; of the post.
        </div>

        <iframe
            src="https://www.youtube.com/embed/A96kT-jt9RQ"
            allow="accelerometer; autoplay; encrypted-media;
                gyroscope; picture-in-picture"
            allowfullscreen>
        </iframe>

        <div class="tags">
            Tag 1 Tag 2
        </div>
    </div>
</div>

Footnotes

[1]	https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/JSON

[2]	https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data#how-structured-data-works-in-google-search

[3]	https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Introduction#what_are_apis