On-page editing with client-side rendering
Describes how to make client-side rendering easier with on-page editing.
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
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 3 other HTML attributes as below:
<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"
– This attribute marks an element for editing.data-epi-property-render="none"
– This attribute prevents the DOM from being modified directly when editing. Usingdata-epi-property-edittype="inline"
overrides this and will modify the DOM (note, "inline" is the default for string properties).data-epi-property-edittype="floating"
– This attribute 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 either PageController
or ContentController
, because these both include the attribute by default. The resources need to be required 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 [email protected]_ 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/disable client-side routing as needed, the client requires some sort of indicator of the current context mode. For this purpose, Optimizely provides the following properties in the epi object :
inEditMode
– True in both edit mode and preview modeisEditable
– True in edit mode and false in preview modeready
– True if the propertyisEditable
has been initialized. Otherwise, subscribe toÂepiReady
to get those properties as soon as they are available
Navigate on-page edit
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 there are two requirements. The links needs to be actual hyperlinks with an 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/artistEdit mode – When the content is loaded in the CMS UI, and the content is editable in OPE.s/"
URL – /EPiServer/CMS/Content/en/artists,,6_7/?epieditmode=TruePreview 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
Content delivery API
Optimizely has released a content delivery API to make a headless implementation even easier. See Content Ddelivery API.
SPA template site
To demonstrate some useful concepts when creating a Single Page Application with working on-page editing, see the MusicFestical SPA template site on Github.
Recommended blog series
- JS SDK public preview
- Introducing a new SPA template site: MusicFestival
- Routing in a SPA with a working On-Page Editing experience (CMS UI 11.11.0)
- Tips and tricks for a great On-Page Editing experience in SPAs and other client side rendered sites
- Represent the concept of "pages" and "blocks" with matching client side components in a SPA
Blog posts
Updated 5 months ago