On-page editing with client-side rendering
Optimizely offers some features to make client-side rendering easier. These features are framework agnostic so you can use them with any JavaScript framework, such as Angular, React, or Vue.
Edit HTML attributes
The Optimizely Content Management System (CMS) user interface provides the attribute data-epi-edit that can be added to editable DOM elements.
<span data-epi-edit="YourProperty">
{your JS framework decides how the value is actually rendered}
</span>Using data-epi-edit="YourProperty" is equivalent to adding three other HTML attributes as the following:
<span data-epi-property-name="YourProperty"
data-epi-property-render="none"
data-epi-property-edittype="floating">
{your JS framework decides how the value is actually rendered}
</span>- data-epi-property-name="YourProperty" – Marks an element for editing.
- data-epi-property-render="none" – Prevents the DOM from being modified directly when editing. Using data-epi-property-edittype="inline" overrides this and will modify the DOM ("inline" is the default for string properties).
- data-epi-property-edittype="floating" – Creates a dialog for editing and should be used for string types.
Re-render
To know when to re-render, subscribe to the topic contentSaved. If the application is a .NET project, then the controller must contain the attribute [RequireClientResources] unless it inherits from PageController or ContentController, because these both include the attribute by default. Require the resources in a razor view with other scripts for the site using @Html.RequiredClientResources("Footer").
If the application instead is a JavaScript-based application, then explicitly add the resources included by the [RequireClientResources] or develop an equivalent of them.
Note The resources included by @Html.RequiredClientResources are by default: /EPiServer/Cms/latest/ClientResources/communicationInjector.js /EPiServer/Cms/latest/ClientResources/deliveryPropertyRenderer.js
Handle context modes
To properly apply edit overlays and enable or disable client-side routing as needed, the client requires some indicator of the current context mode. For this purpose, Optimizely provides the following properties in the epi object :
- inEditMode – True in edit mode and preview mode.
- isEditable – True in edit mode and false in preview mode.
- ready – True if the property isEditable is initialized. Otherwise, subscribe to epiReady to get those properties when they are available.
Navigate on-page edit
There are two requirements to update the editing context (page tree, for this page folders, and so on) when navigating the site by clicking links in the preview iframe. The links must be actual hyperlinks with an <a> tag and the href attribute needs to be an "edit mode" URL.
Note Pages can be retrieved in three modes using different URLs:
- View mode – When the content is delivered to the site visitor. URL – /en/artist
- Edit mode – When the content is loaded in the CMS UI, and the content is editable in OPE. URL – /EPiServer/CMS/Content/en/artists,,6_7/?epieditmode=True
- Preview mode – When the content is loaded in the CMS UI, but rendered as it would in View mode. URL – /EPiServer/CMS/Content/en/artists,,6_7/?epieditmode=False
Configuration
The CMS needs to be configured to use External Templates and to OptimizeForDelivery. This will allow the Edit UI to load the decoupled delivery site into On Page Edit. It will also instruct the overlay's bounding boxes to include floating instead of inline editors. This is required to avoid cross-origin issues between the domain of the iframe and of the CMS itself.
services.ConfigureForExternalTemplates();
services.Configure<ExternalApplicationOptions>(options => options.OptimizeForDelivery = true);Hosts
The website needs to have two hosts configured, the Primary host which is the domain of the delivery site, and the Edithost which is the domain of the CMS.
Content delivery API
Optimizely has released a content delivery API to simplify a headless implementation. See Content Delivery API.
SPA template site
To demonstrate some useful concepts when creating a single-page application (SPA) with working on-page editing, see the GitHub repository containing Optimizely Content Delivery JavaScript SDKs and samples.