Export Child Entry Metadata with Entries from Content Management Systems

This blog post suggests that, when exporting the JSON representation of an entry (record) from a content management system, that JSON should include metadata about the children of the entry based on its URL path. For example, when exporting the JSON representation of the home page at the URL /, that JSON should include metadata about any pages directly beneath the home page, such as /products and /company. This post also contains specific suggestions for exporting JSON for entries that do and do not have URLs to file system paths.

The URL structure of all websites that consist of more than a home page reflects a hierarchy from the home page down. Developers can use that hierarchy to drive navigation elements on the site, such as top-navigation, left navigation, hamburger navigation, and even breadcrumbs and footers.

I am working on a simple architecture for websites that uses only static files. Each page consists of an index.html file generated from a page entry in the CMS. The /index.html file in the document root directory for the website contains the home page visible at the URL path /. The index.html file in the /company subdirectory of the document root directory (/company/index.html file contains the page visible at the URL path /company.

So that JavaScript referenced by the HTML can access a JSON representation of each entry, such as to generate navigation dynamically, the solution generates an index.json file for each index.html file, where that index.json file contains a normalized (non-vendor-specific) representation of the entry with the URL associated with that file path. The JSON for the entry with the URL /company is available at the URL /company/index.json to JavaScript or anything else from the CDN that hosts the site.

With this approach, visitor clients may not need to retrieve data from the CMS, but can instead retrieve all data from JSON files. The client may not need to know anything about the CMS, resolve its DNS entries, make HTTP round trips to call its APIs, or require its SDKs, security tokens, data formats, and other configuration details. If the solution requires CMS data that was created or updated after generation of the static site, then consider using a search index updated with published data rather than accessing the CMS directly.

To facilitate client-side rendering of data-driven navigation, the JSON representation of an entry that has a URL should include metadata about entries that have URLs that appear as children of that URL as well as its parent by URL. For example, the index.json file for the page entry associated with the URL /company should include metadata about any entries that begin with /company and contain only two slash characters, such as /company/about and /company/careers.

The metadata should include anything useful to client-side rendering logic, such as the URLs of the related entries and short titles to render in navigational elements that link to them. Additional metadata requirements may depend on the CMS. While JavaScript code can retrieve the JSON from the index.json files, but if developers would prefer to retrieve entry data from the CMS directly, for Contentstack specifically, then the metadata should include the content types and IDs of the related entries (and possibly API key, environment, and delivery token).

To export files, generate a list of all URLs on the site and process it in reverse order. Populate a data structure that stores the required metadata, such as a hashtable that maps URL paths to JSON representations of the metadata for each page entry. Before writing the JSON file, insert a “children” JSON or equivalent element with a list of the JSON metadata for the child entries by URL and a “parent” or equivalent element with the JSON metadata for the parent.

It may be necessary to export JSON for entries that do not have URLs separately from those that have URLs. Store JSON for entries that do not have URLs in a subdirectory structure, such as by content type (/json/typeA/123456.json), creation date (/json/year/month/day/123456.json), ID (/json/1/2/3/123456.json), or otherwise. It may be useful to generate JSON files in this directory structure for all entries in the repository including those that do have URLs, duplicating the JSON files in the directory structure that represents the website. It may be useful to generate an index.json that lists the json files that exist in this directory structure.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: