On-page editing with Optimizely CMS on an externally hosted site

Did you know that you can enable on-page editing for a site that isn’t hosted on the same server as the CMS?

I’m not sure when this feature was introduced, as there isn’t much documentation available. It took me several hours to figure out all the necessary steps. Hopefully, this article will save you some time.

The solution involves three parts:

  • Some configuration needs to be done in the CMS.
  • Include a javascript on your external web app, and add edit-hint attributes around the property values.
  • Manage the re-rendering on the external web app when content is updated.

Changes needed in the CMS

Add the following code in your ConfigureServices within startup.cs:

services.Configure<ExternalApplicationOptions>(options => options.OptimizeForDelivery = true);

This code instructs the CMS to load the external web app in the edit-iframe, rather than rendering an MVC page template.

Configure host names

Refer to the Content Graph documentation to see how the host names could be set up.
However, I recommend not specifying the Type for the CMS host name. Most likely, you want one language to be the main language of your site, without requiring the language part in the URL. By setting the Culture of your primary site to “en”, mysite.com will display English content, and mysite.com/de will show German content.
When you fetch content from the CMS delivery API, you will achieve the same behavior if you configure the same Culture for the CMS host name. Hostnames configured as type “Edit” cannot have a Culture set, so you can leave the Type field empty.
So far, I haven’t encountered any issues with this setup. If it becomes a problem I need to make sure that the language part of the URL is always present when fetching content from the delivery API.

Communication script and edit-hint attributes

To determine if a page is requested in edit mode, check if “epieditmode=true” is present in the query string.
When in edit mode, include the “communicationinjector.js” script on your page. The script is hosted at: https://<your_cms_host>/episerver/cms/latest/clientresources/communicationinjector.js

Additionally, add the “edit-hint” attribute to an HTML element that surrounds the property value. You can achieve this by adding a <span> element with the “data-epi-edit” attribute. For more information about edit attributes, refer to this documentation.

Once added, you’ll notice the familiar edit overlays on elements with the “edit-hint” attribute.

Re-render when content is saved

Whenever any content is updated you need to update the current page to make the changes visible to the editor. The communicationinjector.js script enables an event that is triggered when content is saved. Refer to point 7 here for an example of how to subscribe to that event, and perform a re-render.

The exact method of re-rendering depends on your tech stack for the external web app, and the type of property being updated. I have added a custom edit attribute to determine if a property can be updated by just replacing content in the DOM, or if I want to fetch the updated content from the API and re-render the entire page.

And that’s it! With these steps, you’ll be able to have on-page editing for your externally hosted site without breaking a sweat. Just remember, if you encounter any unexpected glitches or hiccups along the way, don’t panic. Take a deep breath, grab a cup of coffee, and remember that even the most tech-savvy among us have moments when we feel like we’re wrestling with digital gremlins. So, stay persistent, keep a sense of humor handy, and happy editing! May your web app and CMS dance harmoniously like a perfect code tango!

Yeah… I asked ChatGPT to suggest a funny ending to this blog post 😊

Leave a Reply