Limits and Constraints

While the possibilities offered by the real-time previews of Mattrbld are basically endless, there are some limits and constraints you should be aware of when using them. In this article, you will get to know them, as well as find some pointers on how to work around them to improve your and your content editors’ experience.

Only the Current Content Item is Actually Current

The version of your project that is loaded in the preview window is not the version you are editing in the CMS—it’s the one that is currently running under the URL you provided when configuring real-time previews. The content of the content item you are currently editing is simply injected into that version of the project, creating an illusion that you are working on a newer version of your project. In fact, the preview URL doesn’t even have to be on the same domain as your project—it could be a simple shell or general purpose preview site.

For example, if you are editing a blog post, only the content of that blog post, i.e. the words and images you can see and change in the Mattrbld content editor will be current. Everything else, like the menu, footer, etc. will be as it is currently live on your actual blog. Even if you changed your logo, or rearranged your footer navigation menu since you last synced your content.

Dynamic Content will be Missing or Outdated

As an extension of this, any content that is dynamically linked, for example through a Content Reference field, will not be reflecting the content that is currently in Mattrbld, but the one that is currently on the live version of the project. Depending on your build process, it may not even be shown at all.

The same goes for other dynamic parts of your content, such as “related posts” and other items that are ordinarily added by your build process. Of course, you’re free to use client-side JavaScript to “fake” these things, but it may only be worth going through that effort if the information is crucial for the content editor.

Additionally, while this limitation is not an issue in most cases, as you’ll not be editing the menu and a post at the same time, it may throw off users that aren’t aware of it. So it could be worthwhile to add a little pop-up or toast to your preview page telling them that they are not in fact editing the live version of the project.

It could also be beneficial to insert dummy content, or “skeleton content” as commonly seen in website-loaders, where there would ordinarily be some form of dynamic content that cannot be shown in the preview, so editors will have an accurate depiction of how the content they are working on will flow on the final page.

On top of that, the flexibility of the preview system allows you to create specific previews for specific content items, since the metadata passed along in the preview payload contains information on the current Collection as well as Schema. To learn more about what data is at your disposal, refer to the article on how to implement the preview protocol.

Links Can Break the Preview

The preview is loaded in an <iframe /> or a child-window of Mattrbld, which is connected to the main Mattrbld window or tab. If a link is clicked on the previewed website and the iFrame / window navigates away from it, that connection is broken. This means that Mattrbld can no longer communicate with the preview, even if you navigate back to it inside the iFrame / window.

To mitigate that, you can use a global event listener that detects clicks on links that open in the same window and prevent its execution:

function disableLinks(e) {
  let link;

  if (e.target.tagName.toLowerCase() === 'a') {
    link = e.target;
  } else {
    link = e.target.closest('a');
  }

  if (!link) return;

  if (
    link.getAttribute('target') !== '_blank'
    && (!link.getAttribute('href')
    || !link.getAttribute('href').startsWith('#'))
  ) {
    e.preventDefault();
  }
}

window.addEventListener('click', disableLinks, { capture: true });

Content Won’t be Processed

There are cases, where your build-process may process the raw content, for example to optimise images, or by transforming data from one format into another. Mattrbld doesn’t know about these processes and would often not be able to execute them anyway.

That’s why content will be passed as is to the preview and should be considered raw. Here are some common cases when you’ll notice this.

Markdown is Transmitted as Plain Text

Many static site generators use Markdown files for their content, and Mattrbld supports outputting Markdown. However, since Markdown is a plain-text format, it will be sent to the preview as plain text, just like it would be stored in Mattrbld.

If you tried to display it in your preview as it was received, you’d end up showing raw Markdown, not HTML like you’d expect.

To deal with this constraint, you have to convert the raw Markdown to HTML yourself before you render it on the page. This can be accomplished by using one of the many Markdown libraries for the browser, such as marked or markdown-it.

Images Will be Transmitted as Binary Data

Images (and other media files) will be transmitted as binary data in a special imageData Map alongside the other preview data. You can use URL.createObjectURL() to create an actual URL you can use in the src=* attributes of your elements instead of the string path that is in the data.

The Map maps string paths to binary blobs, so you can use it to look up what ObjectURL to use in which element while you’re transforming your content:

const images = new Map();

// data is the data passed by the Mattrbld preview
function handlePreviewData(data) {
  if (data.imageMap && data.imageMap.size > 0) {
    data.imageMap.forEach((image, path) => {
      if (images.has(path)) return;
      images.set(
        path,
        URL.createObjectURL(image)
      );
    });
  }

  // the actual content is in data.data
  content = replaceContent(data.data);
}

// A recursive function to replace content
// with usable data, could also be used to convert
// Markdown and other things
function replaceContent(obj) {
  if (!obj || typeof obj !== 'object') return obj;

  if (Array.isArray(obj)) {
    return obj.map((item) => {
      return replaceContent(item));
    }
  }

  return Object.entries(obj)
    .reduce((content, [key, value]) => {
      if (
        typeof value === 'string'
        && key === 'src'
        && images.has(value)
      ) content[key] = images.get(value);
      else content[key] = replaceContent(value);
      return content;
    }, {});
}

This code takes incoming preview data, checks if there are any images (or other media files) attached to it, loops over them and stores them in a local map as ObjectURLs, which can be used as src attributes.

Then it goes through the content passed by the Mattrbld preview and replaces every src-key that contains a string path with the ObjectURL from the local map.

In this article, you were made aware of some constraints and limitations regarding real-time previews in Mattrbld and learned about ways to deal with them. With this, you’re ready to implement the preview protocol into your own projects, so you can enable previews for your content editors.