SA5 Data ( HSON ) ❺🧪

Add data to your custom code

We refer to this syntax as HSON, or HTML Structured Object Notation. It has specific design mechanics which allows us to unambiguously transform HTML-encoded content into script-friendly JSON.

The primary purpose of SA5 Data is to provide a reliable means to expose Webflow's collection lists as a JSON data source that can be used in your custom code.

Count and group data
Perform calculations
Generate running totals
and much more

Once the data is accessible to your scripts, you can do whatever you like with it.

How Do I Use It?

SA5 Data uses a specially-typed <script> code block to easily capture and describe your CMS and static data. The syntax is designed specifically to support Webflow's HTML-encoded field embeds as the source for your raw data.

SA5 Data blocks are placed in HTML Embeds, typically inside of any Collection List or Collection Page. They describe the JSON object you want to create.

Here's a very simple example of what SA5 Data looks like.

We are likely to migrate the type to sygnal/hson for generic data descriptions.

<script type="sygnal/sa5-data">
name: John Doe
slug: john-doe
brief: Software Engineer
</script>

This would be parsed as the JavaScript object;

{
  "name": "John Doe",
  "slug": "john-doe",
  "brief": "Software Engineer"
}

And that resulting data can be used in SA5 Data-Binding, or in your custom JavaScript code.

Typically, you would use Webflow's Field embeds to compose the SA5 Data object from Webflow's CMS Embed fields. An example might look like this;

The resulting JSON object is stored in SA5's Datastore so that you can easily access all of the data on your page, even hundreds of data items.

In the <script> element, you can see two custom attributes, wfu-data-dsn and wfu-data-item-id. These identify the collection and the item uniquely, so that you could later retrieve it easily.

For example if this collection contained an item with a slug of 102-hemingway, then you could access it directly through data-binding;

wfu-bind = $data.listings.102-hemingway.name

Features

To provide a full bridge between Webflow's CMS Data and structured JSON objects, the SA5 Data syntax has support for typed values ( string, number, boolean ), null values, nested objects, and multiline strings.

Typed Values

By default, values are interpreted as string values, and JavaScript objects are created accordingly. However you can identify any field as a numeric or boolean type when appropriate.

This is done by adding a symbol immediately after the : delimiter;

: or :$ indicate a string value
:# indicates a numeric value
:? indicates a boolean value

Here's an example structure;

<script type="sygnal/sa5-data">
name:$ John Doe
age:# 23
isActive:? true
description: <John is a software engineer
from Springfield. He loves coding and
is passionate about technology.>
</script>

Null Values

Blank values are expressed as nulls in your object, regardless of the type.

Here, age and isActive are nulls;

<script type="sygnal/sa5-data">
name:$ John Doe
age:# 
isActive:? 
description: <John is a software engineer
from Springfield. He loves coding and
is passionate about technology.>
</script>

Nested Objects

SA5 Data also supports nested objects.

To indicate a nested object,

Place your field key on a line by itself, with a double-colon :: suffix
Indent the fields within your nested object beneath it

Here address and postalCode are both nested objects.

<script type="sygnal/sa5-data">
name:$ John Doe
age:# 23
isActive:? true
address::
    street: 
    city: Springfield
    country: 
    postalCode::
        code:# 
        region: 
</script>

Generates the following JSON object;

{
  "name": "John Doe",
  "age": 23,
  "isActive": true,
  "address": {
    "street": null,
    "city": "Springfield",
    "country": null,
    "postalCode": {
      "code": null,
      "region": null
    }
  }
}

Multiline Content

There is an edge case problem here, which is that in Webflow a CMS text field can be set to multiline, and can contain line breaks. To resolve this unambiguously, wrap Webflow's embedded variable in angle brackets < >

Objects can be nested by specifying the object key on one line, and indenting the nested object beneath it;

<script type="sygnal/sa5-data">
name: The Catcher in the Rye
author: J.D. Salinger
description: <In "The Catcher in the Rye," the protagonist, Holden Caulfield, 
recounts his experiences in New York City after being expelled 
from an elite prep school.> 
</script>

Which is parsed as;

{
  "name": "The Catcher in the Rye",
  "author": "J.D. Salinger",
  "description": "In \"The Catcher in the Rye,\" the protagonist, Holden Caulfield,\nrecounts his experiences in New York City after being expelled\nfrom an elite prep school."
}

The use of angle brackets was chosen because Webflow HTML encodes all values it embeds, which means that angle brackets cannot exist in the embedded content itself.

Also use angle brackets if whitespace characters at the start or end of your field content are an essential part of your data.

Technical Guide

SA5 Data is a custom notation designed to represent structured data in a human-readable format. It is designed specifically to work with Webflow's Custom Code areas and HTML Embeds, and to work with Webflow's HTML-encoded CMS field embeds.

This syntax combines elements of traditional data representation formats like JSON, YAML and HCL, and simplifies them for ease of use. SA5 Data is particularly suitable for configuration, data representation, and other scenarios where clear, concise data structures are desired.

Design features;

Is very easy to work with in Webflow's HTML Embed editor
It reliably handles Webflow's innate HTML encoding in embedded CMS fields
It handes line breaks in multiline embed content
It is easily translated directly to JavaScript objects

Sygnal designed SA5 Data because other approaches like raw JSON embeds created too many risks for broken, unparseable data structures. SA5 Data safely transports HTML Encoded CMS data from Webflow's Collection lists into JavaScript objects with zero risk of data loss, damage, or broken scripts.

Basic Rules

Script Tag:

Every SA5 Data block starts with a <script type="sygnal/sa5-data"> tag and ends with a </script> tag.

Key-Value Pairs:

Represent data as key: value pairs.
Each pair should be on a new line.
Whitespace will be trimmed from both the key and the value
The first colon on the line is a delimiter, thus the key cannot contain a : but the value can

Values:

Do not enclose values in quotes. They are not needed and would be considered part of the string content.
All values must be HTML-encoded. This happens automatically with Webflow's embedded fields. If you have static string content;
- < must be encoded as <
- > must be encoded as >
- & must be encoded as &
If a value is delimited by < and > characters, the whitespace and line feeds within those angle brackets are considered part of the value.
```
multi-line-value: <This is a
multi-line value with preserved whitespace and line breaks.>
```
Value type defaults to strings, and will be created in the JavaScript object accordingly. However you can also define numeric and boolean types by appending a type identifier to the value separator;
- : or :$ indicates a string value
- :# indicates a numeric value
- :? indicates a boolean value
Empty values of any time resolve to null values.

Indentation & Nesting:

Nested structures are indicated by indentation.
Use consistent indentation (preferably spaces) to represent nested structures. The level of indentation indicates the depth of nesting.
For each nested level, increase the indentation consistently (e.g., by two or four spaces).

No Commas or Brackets:

Unlike JSON, SA5 Data doesn't use commas to separate key-value pairs or brackets to denote objects.

Technical Notes

In the resulting JavaScript object-

Value types are all string, unless identified as boolean or numeric
Empty values are always null
Webflow's HTML encoded fields are decoded
Line breaks are encoded as \n

Future

Support for process-assembled objects. In rare cases, some pieces of the object may be outside of the sa5-data block, particularly items that cannot be Field-embedded such as rich text content.

In this case, we might support a special attribute on those elements such as [wfu-data-item] along with field, db, dsn identifiers, and specify the field for an object-merge. e.g. article.text would indicate the nested article object, with a text field. Objects would be created as needed. I am probably in favor of an object-merge approach.

As multiline string delimiters, < > are concise and unambiguous, however we are also considering the use of """, ``` or \\\ delimiters to make them more visible.