CMS Connect (JSON) Expressions
Reusing your content is a great way to save time and effort. By defining JSON expressions for a CMS Connect (JSON) component, you can map existing content into your site pages.
When you place a component on your site page, you specify its properties using JSON expressions. For example, if you’re mapping in a blog article, you can define expressions to retrieve the blog’s ID, title, author, and content from your CMS.
Let’s look at an example using this JSON structure as the content source. The example JSON response body is from a Drupal CMS.
To set up a CMS connection, create a content item (for example, a blog) or a content list (a blog series). When you add the component to your page, you enter JSON expressions to define its properties.
For example, to retrieve the title, the expression
@data/attributes/title retrieves DIY Dryer Vent Cleaning from the example JSON resource. The @ symbol indicates that the text represents a JSON expression that points to the title element.
For CMS JSON connections, the expression syntax follows the JSON Pointer specification in RFC 6901. For the example content source, the parent node
@data is the top-level pointer to the source content. To access a nested element, specify the path. For example, the expression
@data/attributes/body/value points to the blog content.
When accessing values in an array, the starting index value is 0. Here’s an example of JSON source containing a simple array.
Using this source, the expression on the left yields the output on the right.
You can build more complex expressions using the
concat functions. Use the
where function to filter array elements. The function compares two values using an operator:
'ne' (not equals),
'lt' (less than),
'gt' (greater than),
'le' (less than or equals), or
'ge' (greater than or equals).
In the first example, the
where expression filters the array to find where the value of key is equal to 2. The second example uses two
where functions, and both conditions must be met to find the array element of interest.
lookup function is useful when searching a JSON document. It takes at least 3 parameters.
- Starting node
- Key to examine inside the starting node
- String or numeric value to match the key against
For example, you can search the JSON source for instances where an author ID or a key matches a certain value.
concat function concatenates the strings and parameters that you give it. The expression
@concat('DIY Focus', ': ', 'about your ' , /array/1/dictionary/d) outputs "DIY Focus: about your Dryer". If your CMS stores the author name in an array with first and last name elements, to output the author’s full name, use an expression such as @concat(author/first_name,' ',author/last_name).
Keep these points in mind when you compose JSON expressions.
- Enclose strings in single quotes. For example, @'hello' is how you include the string
helloin an expression. To include an @ character in a string, enclose it in single quotes. For example,
falseto indicate a Boolean value. The value
trueis a Boolean, but
'true'is a string.
- Specify a sibling or parent element relative to the current context using a period (.) for a sibling and two periods (..) for a parent. For example, to search by title, specify
@data/attributes/title/../idto retrieve the corresponding ID for a title.
- Use the backslash character (\) as an escape character. For example,
@/author/namelooks for name under an author element, but
@/author\/namelooks for author/name as a key.
Mistakes happen sometimes. Here’s a couple of possible error messages when your JSON expressions aren’t right.
Entering an invalid JSON path in the property editor of Experience Builder. For example, if you enter a JSON expression for author as
@author/name, you see an error message like this one.
Entering an expression that returns more than one value when only one value is expected. For example, if you enter a JSON expression for author as
@author/name, you see this error message.
Providing an invalid URL path when you create a CMS connection for a content list or connection details. Depending on the issue, you see HTTP errors, such as HTTP 0 or HTTP 404 errors, or an error like this one. Verify the configuration settings for your CMS connection.