<
Omnichannel Manager, 3.0
Omnichannel Manager, 3.0
Documentation

User documentation - OCM 3.0

The Omnichannel Manager (OCM) is an integral part of the multi-platform management of content in FirstSpirit. Together with the FirstSpirit ContentCreator, the OCM enables preview editing of external applications allowing editors to make changes and see them in real time.

For headless projects, e.g. PWAs (Progressive Web Apps) or dynamic websites, the website is an external application whose preview version is embedded in FirstSpirit but not generated within FirstSpirit. The content is stored in an external database, e.g. FirstSpirit CaaS (Content as a Service), from which the applications retrieve it.

The OCM offers you the following advantages:

  • Editing content from external applications using familiar editing functions of the ContentCreator
  • Displaying and editing of content from multiple different sources (e.g. FirstSpirit CaaS)
  • Dynamic partial reloading of areas where content has been changed instead of full page reloads for better performance

Technical implementation

To enable preview editing in ContentCreator for a headless project, a bidirectional communication channel between FirstSpirit and the external application is necessary. The Third Party Preview (TPP) function contained in the ContentCreator sends and receives requests from the SNAP-API integrated in the external application. These two endpoints form the OCM.

As an editor, you want to edit content within the external application embedded in the ContentCreator:

  • The SNAP-API provides the editing functions of the ContentCreator in the embedded external application.
  • You edit an element of the displayed external application within the ContentCreator.
  • As soon as you save the changes in the ContentCreator, they are transported to the external database.
  • At the same time, the ContentCreator sends a request to the SNAP-API in the external application.
  • The SNAP-API receives the request and updates the content of the external application.
  • The external application displays the updated content and you can see it directly in ContentCreator.

Configuration in FirstSpirit

Preview URL configuration

To ensure the use of ContentCreator functionalities in headless projects, you must configure a preview URL on the FirstSpirit side:

  • Enter the URL of the web application to be used for the preview in FirstSpirit in the External Preview URL text field.
    FirstSpirit ServerManager > Project properties > ContentCreator settings

  • Click Ok to save your changes.
    → The preview application can be used in the ContentCreator. Editors can edit, expand or delete the content displayed in the preview area.

When entering the URL, note that...
  • the URL specified must also include the protocol of the external web application.
  • if the text field is left empty, the internal preview of the ContentCreator is used.
You can find more information in the FirstSpirit documentation for administrators and in the documentation on restrictions of the editing interface.

External preview application

Consider the following requirements for an external preview application to ensure successful use in the ContentCreator:

  • The application must be allowed to run in an iFrame (see MDN/X-Frame-Options).
  • If the ContentCreator protocol and the protocol of the external application are not identical (http:‌//…, https:‌//…), you will receive a warning in the Java console which can be ignored.

Prevent the warning message by running the external app and the ContentCreator under the same protocol. Alternatively, you can also use absolute links that begin with // instead of http[s]:// .

Preview application configuration

You can configure the preview applications. The PreviewRenderingPlugin selected in the configuration is used to generate preview content. For hybrid projects, you can configure one or more preview applications for various areas in the project.

  • Add the project component "CXT ContentCreator: Preview Configuration ProjectApp"
    ServerManager > Project > Properties > [Project selection] > Project components
  • Click Configure.
  • Select the appropriate PreviewRenderingPlugin from the drop-down menu, e.g. "CaaS Connect Preview Rendering Plugin" for connections to CaaS.

If you do not configure the PreviewRenderingPlugin, the standard output channel is used for the preview.

  • Optional: Click Create to define a preview application for a sub-area. Enter the display name (Name) and URL of the preview application (URL). Select the desired sub-area (Folder).

External preview application

If you have configured the preview application on the FirstSpirit side, content can be displayed in the ContentCreator. To enable the preview application to address ContentCreator functionalities, you have to make adjustments to its code and include an API.

The API enables editors to identify editable HTML elements on mouseover and edit them using editing icons. Further functions are provided via the ContentCreator menus.

Frontend Library

To establish a connection between the external preview application and the ContentCreator, include the following script:

<script src="https://FIRSTSPIRIT-HOSTNAME/fs5webedit/live/live.js"></script>
The URL of the script refers to the fs5webedit application in which the preview application is used.

Example:
"https://customer.e-spirit.hosting/fs5webedit/live/live.js"

Assignment to FirstSpirit elements

For an assignment to FirstSpirit elements, the HTML elements of the preview application are marked with the "data-preview-id" attribute:

<div data-preview-id="8326527a-60ff-49a0-bc66-91671d660249.de_DE">...</div>
A distinction between higher-level elements, e.g. a page or a paragraph, and nested content, e.g. individual input components or FS_CATALOG structures, is necessary.

Nested components

You can edit individual input components or nested structures, such as FS_CATALOG or FS_INDEX.

Since version 3.0, you can define the information about the origin of a nested component in a single [data-preview-id]:

  • {sectionPreviewId}/{editorName}
  • {sectionPreviewId}/{editorName}/{catalogCardIndex}
  • {sectionPreviewId}/{editorName}/{catalogCardIndex}/{catalogCardEditorName}

Nested component example:

8326527a-60ff-49a0-bc66-91671d660249.de_DE/st_catalog/0

In addition to the index, you can also use the UUID of the FS_CATALOG:

8326527a-60ff-49a0-bc66-91671d660249.de_DE/st_catalog/e7c669ee-26b4-4267-8bbe-fa84c689ffc0

JavaScript API

Refer to the API documentation for a detailed description of the integration and code examples.

Current preview element

A fronted API makes it possible to determine the displayed preview element for which toolbar functions are available. To change the current preview element and inform the ContentCreator of the currently visible page reference, use the following function:

TPP_SNAP.setPreviewElement(pageRefPreviewId);

Desired preview element

If the editor wants to open a specific preview element from the ContentCreator (e.g. when using the search function), the event TPP_SNAP.onRequestPreviewElement is sent. The external preview application uses this event to open the corresponding view and react to the user interaction. 

TPP_SNAP.onRequestPreviewElement(async (previewId) => {
  // The following previewIdToPath function is just a placeholder! The mapping from previewId to route has
  // to be defined project-dependent!
  let path = previewIdToPath(previewId);

  // The routing mechanism depends on the frontend as well, thus the "route" function also has to
  // be understood as a placeholder!
  if (path) return route(path);
  // ... error handling (e.g. 404) ...
}

Migration from 2.x

Version 2.x Version 3.0
FirstSpirit Third Party PreviewThe use of the TPP-module and the corresponding web-component "FirstSpirit ThirdPartyPreview WebApp" is required.The TPP functionality is included in the ContentCreator.
You can delete the web-component "FirstSpirit ThirdPartyPreview WebApp".
Frontend LibraryThe Frontend Library is provided seperately and integrated in the preview applications. You have to ensure that the version is compatible with FirstSpirit.The TPP-SNAP API is provided in the ContentCreator. The preview application retrieves the Frontend Library directly from the contextual ContentCreator application. You do not have to consider version compatibility.
Overriding standard functionsOverride standard functions using the TPP-SNAP method "overrideDefaultButton".Use TaioloredUI to hide, extend or exchange standard functions.
CaaS ModeUse "CaaS Mode" to delay TPP-SNAP events.No dependency on CaaS exists.
CaaS ConnectOCM is directly dependent on CaaS Connect. Depending on your configuration, you can use this dependency to generate updated preview content.No dependency on CaaS exists.To generate preview fragments, configure a PreviewRenderingPlugin.
Find more information in the OCM 2.x documentation.

Restrictions

Please note the following functional restrictions when using external preview applications:

  • Historical versions are not available for external applications that use FirstSpirit CaaS. Therefore, it is not possible to view a historical version in the preview. This applies, for example, to the use of the Multi Perspective Preview or the project history in the ContentCreator.

Table of Contents