Realtime Previews: How They Work

While not crucial to the editing experience, it can be beneficial to be able to see what effect the changes being made to a content item will have in the finished version of the project. This is why many traditional content management systems allow for a “preview” and some users prefer “what you see is what you get” (WYSIWYG) editors.

Previews are an area headless content management systems have struggled with in the past, since it’s not always clear what the content managed in the system will be used for in the end and headless CMS are by definition decoupled from the final frontend.

Mattrbld solves this problem by putting control into the developers’ hands, offering a standardised protocol which can be used to implement custom previews, which update in real-time as content is being worked on.

In this article, you’ll learn how live previews work in Mattrbld, while other articles in this section will dive deeper into limitations, common issues and the implementation details of such a preview.

Activating and Using Real-Time Previews

As mentioned in the article on configuration, previews can be enabled for the entire project by anyone with access to the project settings. Activating the switch in the “Content Previews” section of the General Settings tab will reveal an input field for a “Preview route URL”.

This input field should contain a valid URL to a page on a website that implements the preview protocol, which will then be used to display the content being worked on.

Once this setting is enabled and a valid URL was provided, all Collections will have previews enabled by default, which means that content editors will see a “Show Preview” button next to the “Save” button while editing content. This can then be used to show a preview of the content item being worked on, either right in the editor or in a separate tab / window.

Since version 0.4.0, it is possible to disable previews for specific Collections, by enabling the “Disable previews for content in this collection” option when editing a Collection in the Collections tab of the Project Settings.

Hovering over the preview while it is being displayed within the Mattrbld content editor will also provide editors with the ability to full-screen the preview or shrink it to a mobile size to preview how content might look on a phone.

The content within the preview will update immediately after it is changed in the content editor, making it real time.

How This is Possible

When the preview is shown, Mattrbld loads the specified preview URL in an iFrame and establishes a two-way communication link with it by exchanging a handshake and checking what features of the preview protocol the loaded page supports. This works securely through the postMessage feature provided by web browsers.

Since this system relies on bidirectional communication, it is important that the loaded website implements the preview protocol correctly. It is also the reason why a developer must explicitly implement a preview route for a project that wants to show live previews in Mattbrld.

Once the communication link has been established successfully and whenever the content changes while the link remains unbroken, Mattrbld sends the entire content item along with some metadata to the website shown in the preview. The website can then make use of this data as it sees fit, in most cases by simply showing it as it would appear on the published version of the site.

However, since the developer has 100% control over what to do with the data, it is also possible to use it for all sorts of other things, for example to generate a printable PDF of the business card of a team member, or pass the data along to a web-game engine to manipulate the parameters of the main character. The possibilities are endless.

In this article, you learned how to enable real time previews for your Mattrbld Collections, as well as gained an insight into how they work. In the next one, you’ll gain some insights into what limits and constraints this approach to real-time previews brings with it. If you’re not interested in those, you can also skip ahead to how to implement the preview protocol or check some common issues why it may not be working in your case.