Custom JSON feeds are valuable in many situations, and while it is easy to create a JSON feed in Marketpath CMS there are a few challenges that you should be aware of in order to prevent frustration.
There are numerous ways to collect and prepare your data - exactly the same as for a normal page load. The exact method you use will depend on what you are trying to accomplish, but here are two suggestions that work well and are easy both to create and maintain. Note that you can easily combine the two for further power and flexibility:
In your JSON template, define custom fields for your content editors to fill out. This is the data that will be output in the JSON feed. Fieldsets are particularly useful for allowing editors to fill out repeating data structures (JSON arrays).
There are dozens of ways that you can pull dynamic content from Marketpath CMS in your template - each of which can be combined with the others. A few examples are:
One of the beautiful things about making JSON templates is that, if you build them with enough flexibility, you can re-use the same templates and/or pages multiple times for similar purposes by providing different input either through the custom fields on the page or through query string parameters passed in the request (or both).
Before beginning to output your data in the template (well, order doesn’t actually matter too much here, but it is generally more readable to put this at the top of your template), there are a few methods that you need to call so that your scripts can access and utilize your data:
{% allow_cors always %}, otherwise you will need to test that the origin matches the domain that you want to allow (eg: {% if request.headers.origin == 'https://specifically-allowed-domain.com' %}{% allow_cors %}{% endif %}).Outputting JSON to the template is exactly the same as outputting HTML or any other content types. There is one special challenge, however, due to the nature of the liquid syntax and how it conflicts with JSON syntax - both languages rely heavily on the “{“ and “}” characters:
Outputting a single JSON property to the template could not be simpler with the “json_encode” filter. When using this filter you do not need to concern yourself with whether or not the value is null or an empty string.
"custom_value":{{ entity.custom_value | json_encode }}Outputting a JSON object, on the other hand, can be a little more tricky due to the bracket limitation. The most simple workaround for this limitation is to output JSON brackets as a variable - particularly when it would otherwise result in multiple brackets next to each other in the liquid template. The "url_decode" filter makes defining the variable easy:
{"url":{{entity.full_url | json_encode}}}{"url":{{entity.full_url | json_encode}} }{"url":{{entity.full_url | json_encode}}{{ '%7D' | url_decode }}{% var openbracket = '%7B' | url_decode %}{% var closebracket = '%7D' | url_decode %}{{ openbracket }}"url":{{entity.full_url | json_encode}}{{ closebracket }}Here is an example of a very simple template which will output the next 10 blog posts with a post date in the future (note: if this is intended to be usable outside of your own website you will need to add {% allow_cors always %} to the template.
{% set_content_type 'application/json' -%}
{%- var openbracket = '%7B' | url_decode -%}
{%- var closebracket = '%7D' | url_decode -%}
{%- blog_posts posts = start_date:request.date limit:10 sort_by:'post_date' sort_direction:'asc' -%}
[{% for post in posts %}{{openbracket}}
'title':{{post.title.value | json_encode}}
,'post_date':'{{post.post_date | format: 'o' }}'
,'summary':{{post.summary_html.value | json_encode}}
,'blog':{{post.blog.title.value | json_encode}}{% if post.image.is_valid %}
,'image':{{post.image.path | json_encode}}{% endif %}
{{closebracket}}{% unless forloop.last %},{% endunless %}{% endfor %}]
For a fully-featured JSON template example, install the Flexible Blog Post JSON Feed package on your site. This package contains a single template which outputs a blog feed. The JSON structure is configurable at the page level and the blog posts returned are configurable via query parameters. Pagination-related information is returned using X-Pagination-* headers.
Here is an example of a template that outputs a JSON feed of calendar entries in a format that is friendly with the expected fullcalendar format:
{% set_content_type 'application/json' -%}
{%- allow_cors always -%}
{%- var start_date = request.query_params['start_date'] -%}
{%- var end_date = request.query_params['end_date'] -%}
{%- unless start_date is_valid -%}
{%- unless end_date is_valid -%}
{%- capture set start_date %}{{request.year}}-{{request.month}}-{{request.day}} 00:00:00{% endcapture -%}
{%- set start_date = start_date | date -%}
{%- set end_date = start_date | add_days:31 -%}
{%- else -%}
{%- set start_date = end_date | add_days:-31 -%}
{%- endunless -%}
{%- else -%}
{%- unless end_date is_valid -%}
{%- set end_date = start_date | add_days:31 -%}
{%- endunless -%}
{%- endunless -%}
{%- var openbracket = '%7B' | url_decode -%}
{%- var closebracket = '%7D' | url_decode -%}
{%- var calendar = request.query_params['calendar'] | url_decode -%}
{%- capture var filters %}{% if calendar is_valid %}calendar:calendar {% endif %}start_date:start_date end_date:end_date limit:200 sort_by:'StartDate' sort_direction:'asc'{% endcapture %}
{%- calendar_entries entries = *filters -%}
[{% for entry in entries %}{{ openbracket -}}
{% var format_string = 'f' %}{% if entry.all_day %}{% set format_string = 'D' %}{% endif -%}
"title":{{ entry.title.value | json_encode -}}
,"start":{{ entry.start_date | date: 'O' | json_encode -}}
,"end":{{ entry.end_date | date: 'O' | json_encode -}}
,"allDay":{% if entry.all_day %}true{% else %}false{% endif -%}
,"start_display":{{ entry.start_date | date: format_string | json_encode -}}
,"end_display":{{ entry.end_date | date: format_string | json_encode -}}
{% if entry.location.is_valid %},"location":{{ entry.location.value | json_encode }}{% endif -%}
{% if entry.description.is_valid %},"description":{{ entry.description.value | json_encode }}{% endif -%}
{% if entry.has_url %},"url":{{ entry.full_url | json_encode }}{% endif -%}
{% if entry.link.is_valid %},"link":{{ entry.link.value | json_encode }}{% endif -%}
{{closebracket}}{% unless forloop.last %},{% endunless %}{% endfor %}]
Note that you may want to remove the {% allow_cors always %} line depending on how you want this feed to be consumable. This is just an example and you can customize the feed as desired for your specific scenario.
This will load all datastore items for a specific datastore, and is the near equivalent to the (now obsolete) built-in datastore item API. When implementing, you should ideally filter for the specific datastore items that you want to include, as well as outputting only the specific data that is needed.
{%- if entity.datastore_filter.is_valid -%}
{%- assign datastore = entity.datastore_filter -%}
{%- else -%}
{%- datastore assign datastore = request.query_params["datastore"] | url_decode -%}
{%- endif -%}
{%- if datastore.is_valid -%}
{%- set_content_type 'application/json' -%}
{%- var openbracket = '%7B' | url_decode -%}
{%- var closebracket = '%7D' | url_decode -%}
{%- assign query = request.query_params["filters"] | url_decode -%}
{%- assign pageNum = request.query_params["page"] | to_int | default: 1 -%}
{%- assign limit = request.query_params["limit"] | to_int -%}
{%- unless limit is_valid %}{% assign limit = entity.default_limit | to_int | default: 20 %}{% endunless -%}
{%- assign start = request.query_params["start"] | to_int -%}
{%- assign sort_by = request.query_params["sort_by"] | default:"name" -%}
{%- assign numeric_sort = request.query_params["numeric_sort"] | to_boolean | default: false -%}
{%- assign sort_direction = request.query_params["sort_direction"] | default:"asc" -%}
{%- datastore_items products = datastore:datastore limit:limit query:query sort_by:sort_by sort_direction:sort_direction numeric_sort:numeric_sort page:pageNum start:start -%}
{{openbracket}}
"limit":{{limit}},
"start":{{products.start}},
"end":{{products.start | plus:products.size}},
"page":{{products.page}},
"total_count":{{products.total_count}},
"total_pages":{{products.total_pages}},
"items":[{% for product in products %}{{openbracket}}
"guid":"{{product.guid}}",
"name":{{product.name.value | json_encode}},
"title":{{product.title.value | json_encode}},
{% if product.has_url -%}
"has_url":true,
"url":{{product.full_url | json_encode}}
{%- else -%}
"has_url":false
{%- endif %},
"data":{{openbracket}}{% var fields = product.data | where:'is_valid', true | where_exp:'field', 'field.field_id is_valid' %}{% for field in fields %}
{{field.field_id | json_encode}}:{{field.value | json_encode}}{% unless forloop.last %},{% endunless %}
{% endfor %}{{closebracket}}
{{closebracket}}{% unless forloop.last %},{% endunless %}{% endfor %}]
{{closebracket}}
{%- else -%}
{%- set_response_code 404 "Datastore not specified" -%}
{%- endif -%}
Note that if no filters are passed in the query parameters it will load all datastore items in all datastores on the entire site. This may be OK for example code, but you will need to limit the results to items in one or more specific datastores, and optionally filtered by additional criteria.