Netlify Docs
Ask Netlify

Contact

Visual editing /Visual Editor /

Personalization

Make personalized content editable in Visual Editor.

Visual Editor can integrate with the current generation of headless CMS-native personalization engines. A significant challenge for editors using these engines is navigating through the CMS content tree to actually edit multiple variants and targeting rules, without actually getting immediate feedback on their work (more about that challenge here).

In other words, the common hardships with a headless CMS are made worse by the extra layers added for personalization. Integrating a personalization tool into Visual Editor is meant to ease this pain.

Here’s what such integrations typically provide:

  • Quick discovery: any personalized page sections are visually marked as such in Visual Editor.
  • Previewing variants: the user can switch between the default variant (the one selected by the engine) and any other variant.
  • Editing and adding variants is done within Visual Editor, without leaving the page.

For an example, see our Ninetailed integration (video, code).

# Requirements

For personalization to be editable with Visual Editor, the content should be stored in a supported content source. Variants should be stored either in fields within a document, or (more commonly) as separate referenced documents.

# Edit personalized content

Making personalized content editable with Visual Editor is a three-step process:

  1. Mare sure you fetch all variants from the content source. If you’re using a GraphQL API to access your CMS, make sure that all variants and their IDs are included in the query.
  2. Wrap any relevant components with a higher-order component rendering a variant selection control for the user.
  3. Ensure all variants are annotated.

# Wrap components

The mechanism for this depends on the web framework (Next.js example). For any component that is personalizable, create a wrapper component (only in non-production environments!).

The responsibilities of this wrapper are:

  1. If the wrapped component instance is actively personalized, render a badge over the component for quick discovery by content editors.
  2. For personalized instances, render a drop-down control over the component with the option to show either the default variant (the one selected by the personalization engine) or explicitly select any of the existing variants.
  3. When a user selects a specific variant, the wrapper should: (a) render that variant as its child, rather than the default one, and (b) persist the user selection on the client-side, so that it's not lost when navigating between pages.

# Target environment

This behavior should only exist in your application when it is running in development mode. This is commonly achieved using the NODE_ENV environment variable. There is also a STACKBIT_PREVIEW environment that is set in the visual editor.

# Annotate variants

The last step is to ensure that any variant rendered is properly annotated, whether it’s the default variant returned by the personalization engine or a user-selected variant.

As a reminder:

  • If storing variants as individual documents in the content source, use data-sb-object-id on an element that wraps the personalized content.
  • If variants are stored as individual fields, use data-sb-field-path instead.

# Handle gated content

Visual Editor can also handle content that is behind a gate or paywall, or content that requires user authentication.

The process follows a similar pattern to personalization. As long as there is a way to access content in a supported content source, it can be edited.

There are two approaches commonly taken to let editors access to gated content:

# Impersonate a user

In many cases, developers choose to provide the ability to impersonate a specific user or a request. In this mode, the content editor sees exactly what that end-user should see, and edit it. How this is implemented varies significantly based on the needs of the project.

# Bypass the gate

An alternative approach is to make all gated content available when the site is running in development mode. This tends to speed up the editing process, but comes with risk:

  • You must remember (and should test) that gated content is not available in production.
  • Page visuals may differ slightly if not edited in the same context in which the content is presented in production.