Note: This documentation is for the preview version of the upcoming release of CMS 12/Commerce 14/Search & Navigation 14. Features included here might not be complete, and might be changed before becoming available in the public release. This documentation is provided for evaluation purposes only.
Optimizely offers some features to make client-side rendering easier. These features are framework agnostic, so they can be used with any JavaScript framework, such as Angular, React, or Vue.
Editing HTML attributes
CMS UI 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. Using data-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.
Editing HTML attributes for blocks
Editable blocks rendered in a content area should have this HTML attribute on each block element:
- data-epi-block-id="ContentLinkID"
This attribute marks a block element for editing.
Re-rendering
To know when to re-render, subscribe to the topic contentSaved. The controller must contain the attribute [RequireClientResources] unless it inherits from either PageController or ContentController, as these both include the attribute by default. The resources then need to be required in a razor view with other scripts for the site using @Html.RequiredClientResources("Footer").
Handling context modes
In order 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 mode
- isEditable
True in edit mode and false in preview mode
- ready
True if the property isEditable has been initialized. Otherwise, subscribe to epiReady to get those properties as soon as they are available
Navigation in on-page edit
In order 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 <a> tag and the href attribute needs to be an "edit mode" URL. Details can be found in this blog post on routing.
Content delivery API
Optimizely has released a content delivery API to make a headless implementation even easier. Check out the documentation.
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. For descriptions of the template site, see the blog post Introducing a new SPA template site: MusicFestival.
Related topics
Recommended blog series
- 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
Do you find this information helpful? Please log in to provide feedback.
Last updated: Jul 02, 2021
Area:
Optimizely CMS
