Editor integration using metadata

This topic describes the metadata-based integration of Next.js Pages Router applications with the SitecoreAI Page builder. The Page builder uses the metadata provided by the layout service for placeholders, renderings, and fields to identify them and enable visual editing directly in the browser. This relies on the Sitecore Headless Services HTTP rendering engine, Next.js API routes, and the Next.js Preview Mode.

The following diagram illustrates the architecture of integrating a Content SDK Next.js Pages Router app with the Page builder:

The architecture of integrating a Content SDK Next.js Pages Router app with the SitecoreAI Page builder using metadata
Note

The diagram highlights APIs included with Content SDK for Next.js in teal. Elements with other colors are part of the Next.js Content SDK sample application.

If you want to test components without affecting published sites or other users on the same environment, you can connect your local host directly to Pages.

Important

Certain header configurations restrict the loading of iframes that can prevent metadata integration from working. For example:

  • Setting the X-Frame-Options header to "SAMEORIGIN".

  • Setting the Content-Security-Policy header to "frame-ancestors 'self'".

To avoid this issue, ensure your response headers allow the Pages domain to load the response inside an iframe, either by adjusting these settings or adding exceptions as needed.

API routes

The Next.js Content SDK sample application includes three Next.js API routes that facilitate the integration with Sitecore content and layout editors, as follows:

  • The Render API route defined in the file <src>/pages/api/editing/render.ts handles GET requests using logic encapsulated in the middleware EditingRenderMiddleware provided by Content SDK for Next.js. Use this route as the value for the Content SDK app configuration option serverSideRenderingEngineEndpointUrl.

  • The Config API route defined in the file <src>/pages/api/editing/config.ts handles GET requests using logic encapsulated in the middleware EditingConfigMiddleware provided by Content SDK for Next.js.

  • The Page route, which is the main Next.js optional catch-all route defined in <src>/pages/[[...path]].tsx, renders all Sitecore page routes.

Sitecore editing secret

The Sitecore editing secret is a token for securing the Sitecore editor endpoints exposed by the Content SDK Next.js apps through the Render API Route.

The middleware EditingRenderMiddleware automatically validates the token. If validation fails, it returns a response with the HTTP status code 401.

Next.js preview mode

Preview mode is a built-in feature of Next.js meant for CMS use cases where you write draft content (such as the SitecoreAI Page builder), and you want to render pages with this content at request time, bypassing any static generation.

Integrating Next.js Content SDK apps with Sitecore editors relies on this feature.

The EditingRenderMiddleware middleware enables Next.js preview mode, which creates specific cookies on the Render API route responses and passes them along to the subsequent page route request.

The page data is requested within the catch-all route and depends on whether the current route is in preview mode. In such cases, the appropriate SitecoreClient method should be used, depending on the application mode: getPreview or getDesignLibraryData.

Understanding data editing in Content SDK Next.js

A GET request made by the SitecoreAI Page builder to the render API route contains the required query string parameters to render a given page route.

The SitecoreClient uses those query string parameters to fetch editing data. The editing data contains the layout data necessary for rendering the page.

The following represents an example GET request to the editing render endpoint when using metadata-based integration:

RequestResponse
/api/editing/render?secret={EDITING_SECRET}&sc_site=nextjs-app&sc_itemid=54C8E9B5-0B2C-5363-8FA6-D32A3A302F51&sc_lang=en&route=/&mode=edit&sc_version=latest&sc_variant={VARIANT_ID}&sc_layoutKind=shared

sc_layoutKind is an enum with a default value of final, but it can be set to shared instead if needed.

The sc_version, sc_variant, and sc_layoutKind parameters are all optional.

APIs

You can find the relevant APIs for Sitecore editor integration in the @sitecore-content-sdk/nextjs NPM package in the editing submodule.

To use any of these, import them into your code file. For example:

RequestResponse
import { EditingRenderMiddleware } from '@sitecore-content-sdk/nextjs/editing';

EditingRenderMiddleware

EditingRenderMiddleware is a middleware handler for the editing Render API route. It does the following:

  • Validates the Sitecore editing secret.

  • Extracts the required query string parameters from the request URL.

  • Enables Next.js preview mode, passing the parameters to the preview data.

  • Sends an internal request to the editing host’s catch-all route to fetch the page.

  • Returns the rendered page markup as the response.

EditingConfigMiddleware

EditingConfigMiddleware is a middleware handler for the editing Config API route. It does the following:

  • Validates the Sitecore editing secret.

  • Provides a required configuration (application metadata) to determine feature compatibility and configuration.

Do you have some feedback for us?

If you have suggestions for improving this article,