For a custom preview client, a corresponding preview URL service needs to be set up. It should respond to preview URL requests for a given content ID with a URL where to fetch the actual preview HTML from the custom preview client.

Adding coremedia.preview.js

The preview client needs to include coremedia.preview.js to enable communication with Studio. The file can be copied from the Blueprint workspace (e.g. headless-server/json-preview-client/src/main/resources/static/coremedia.preview.js).

Preview Driven Editing

To enable Preview Driven Editing (PDE), preview metadata tags need to be set (data-cm-metadata). This attribute can be set in the preview HTML, either via a static HTML tag or asynchronously. This means you can also fetch the available device types asynchronously and set metadata attributes later. An example for setting the metadata attributes is shown below:

const metadata = [
    {
        cm_responsiveDevices: {
            mobile_portrait: { width: 414, height: 736, order: 1, isDefault: "true" },
            mobile_landscape: { width: 736, height: 414, order: 2 },
            tablet_portrait: { width: 768, height: 1024, order: 3 },
            tablet_landscape: { width: 1024, height: 768, order: 4 },
        },
        cm_preferredWidth: 1200,
    },
];

const div = document.createElement("div");
div.setAttribute("data-cm-metadata", JSON.stringify(metadata));
document.body.appendChild(div);

Preview Refresh Mode

The preview client can support different refresh modes. By default, the Studio preview iframe is reloaded each time a content change takes place. For modern web frameworks, like React, Angular, Vue, etc., this is not the desired behavior, as a full page reload is not necessary and expensive. Instead, the preview client can support a "soft" refresh mode, where only the changed data is fetched and a refresh is made of the affected components. To enable this mode, the preview client needs to call the method studioAddRefreshListener on the JavaScript window object and is provided by the coremedia.preview.js file. The method takes a callback function as parameter, which is called by Studio whenever a content change takes place. The callback itself is called with a CustomEvent parameter which contains additional information about the preview settings (e.g. preview date and time) in the detail field. An example implementation in React could look like this:

import { useState, useEffect } from 'react'
import './App.css'

function App() {
  const [previewTs, setPreviewTS] = useState(Date.now())

  const handleRefresh = (event) => {
    setPreviewTS(Date.now());
  };

  useEffect(() => {
      // attach listener
    window.studioAddRefreshListener(handleRefresh);
    // cleanup
    return () => {
      window.studioRemoveRefreshListener(handleRefresh);
    };
  }, []);

  return (
    <>
      <h1>Preview Refresh Sample Page</h1>
      <div className="card">
        <h3>Last Preview Timestamp: {previewTs}</h3>
      </div>
    </>
  )
}

export default App

The given example updates the state of the React component by re-rendering a timestamp. In a real-world application, the changed data would be fetched from the headless server.