Better Preview with Squidex

By default a headless CMS is very decoupled from the frontends. This makes it much harder for your content editors, because they lack in understanding where a content is used. The main problem is that the frontend is not controlled by the headless CMS. Therefore integrated editing features are hard to implement. But Squidex has some features to make the live easier for your content editors.

---

This blog post is an excerpt from the documentation: https://docs.squidex.io/02-documentation/developer-guides/preview

What is the problem?

In traditional content management systems you very often have a WYSIWYG (what you see is what you get) editor or other editing functionality where the editor can edit the content directly and understands how and where the content is used.

This is a challenge for a headless CMS, because of several reasons:

1. There might be more than one place where a content item is used. For example when you have multiple websites or multiple applications (e.g. mobile apps).
2. The frontend is not controlled or created by the headless CMS. Therefore it cannot provide direct WYSIWG functionality and inline editing in general is tricky.
3. Sometimes a content item has to go through multiple steps until it is published at a website. For example when you have a complex workflow with several review steps or when the publishing process takes very long due to technical challenges.

Squidex cannot solve all these problems for you. But with a little bit help from your frontend developers it can make the live easier for content editors.

Solutions

In general we have several solutions to the problem which work together. They are are best described as Use Cases.

1. Use Case 1: Show unpublished content items.
   As a content editor I want to preview the content item, even if it is not published or reviewed yet, to check if it looks correct and well formatted in the production environment.
2. Use Case 2: Link to the usage of a content item.
   ****As a content editor I want to see all locations where a content item is used, when I edit the content item in the Squidex Management UI.
3. Use Case 3: Link to the source of a content item
   As a content editor I want to see, which parts of the website come from Squidex and how I can edit them in the Squidex Management UI.

Use Case 1: Show unpublished content items

By default Squidex only provides published content items over the API, because the purpose is to only deliver finished content items that have followed a defined workflow.

But this means that a content editor cannot preview content items while he still edits them. Even if he would know where a content item would be used he cannot see it, because the application only gets published content items.

Therefore Squidex provides a special header.

Add the X-Unpublished = 1 header to all requests to retrieve unpublished content items.

Of course you do not want to show unpublished content items to your end users. Therefore it makes sense to use the header conditionally. The condition could depend on the user, environment or just a secret setting.

• When you have a development or staging version of your website, where you test new features, you can show unpublished content items only there.
• When you have a login system and you can distinguish end users from content editors, you could show unpublished content items for content editors only.
• When you neither have a login system nor a staging environment, you could just introduce a secret setting, for example a query string parameter, to enable unpublished content items.

For the Squidex website we have just added a "top secret" query parameter to the blog page. When this query parameter is set to true, it will create add this header to the requests.

Use Case 2: Link to the usage of a content item

For each content item you can define preview URLs. These are just normal links that point to the place where a content item is used. If you have multiple environments or frontends you can also define multiple preview URLs.

Define your Preview URLs

You can define preview URL per schema.

The following example shows 2 preview URLs:

1. The URL to the normal website.
2. The URL to an dedicated mobile website (just as an example).

As you can see, you can use a placeholder with the JavaScript interpolation syntax. Therefore you can add content fields to the link dynamically. If you use a query string to enable unpublished content items, you could also add it to the URL.

Use the preview button

If you open a saved content item, you will see the buttons with the preview URLs:

Use Case 3: Link to the source of a content item

The following screenshot describes this feature best. The screenshot is from the Squidex website. The idea is to annotate content items on your website so that we can provide links to the Squidex Management UI where you can edit them.

As mentioned above Squidex has no control over your website, therefore you have to make a few changes to implement this feature.

Add the Embed SDK script

This script is a little helper that provides the functionality. You have to add a script tag that points to https://cloud.squidex.io/scripts/embed-sdk.js. If you have installed Squidex on your own servers the URL is in general: https://YOUR_DOMAIN/scripts/embed-sdk.js.

Just add the script tag at the end of your body tag. This ensures that more important assets are loaded first and your website is as fast as possible.

The script is very small and has only 8.5kB at the moment, so it is not a problem to include it for all users. But if you want to optimize it further you can implement one of the mechanisms described under "Use Case 1".

The script works as followed:

1. When the user moves the mouse cursor over an element, the scripts tests whether this element or a parent element is annotated (more about this later).
2. The annotation also contains information about the URL of the Squidex installation. This URL is used to test whether the current user is authenticated in the Squidex Management and to maintain a list of known Squidex URLs.
3. If the user is authenticated and the element is annotated it the scripts renders the blue border with links to the Squidex Management UI as long as the cursor is not moved away from the element.
4. When the user moves the mouse cursor over an image the scripts checks whether the source of the image matches to one of the Squidex URLs and if the user is authenticated. If both conditions are met a blue border is rendered around the image as long as the cursor is not moved away from the image.

How to annotate elements?

When you query content items from the Squidex API you also get an edit token for each item.

Just annotate your elements with the edit token, for example you can show a list of blog posts like this. The actual template syntax might look different.

<div class="posts">
   @foreach (var post in Posts)
   {
      <div class="post" squidex-token={@post.EditToken}>
          <h3>{post.data.title.iv}</h3>
          
          <p>{post.data.content.iv}</p>
      </div>
   }
</div>

The edit token is just a base64-encoded JSON object. Property names are shortened to keep the edit token as small as possible. If necessary you can also create the token manually.

More about the edit token can be found in the documentation: https://docs.squidex.io/02-documentation/developer-guides/preview

This is just the beginning. The Embed SDK is based on Preact (a smaller version of React) and can be easily extended to provide more integrated editing functionality for your content editors. Unfortunately there is no easy way to provide such functionality for other platforms such as mobile apps, but this does not mean that you cannot implement something like this on your own.