CMS Concepts

This chapter describes the concepts and terminology used throughout the documentation on the CMS integration.

Scope parameters

The scope is an object passed to FontoXML by the CMS upon opening the application. This contains all the contextual information for FontoXML to know what to open and how to behave. The scope contains parameters telling Fonto what to open, for who, and which CMS to talk to:

Scope
documentIds required array[string] Array of document IDs to load from the CMS.
cmsBaseUrl required string The base URL where the CMS endpoints are exposed.
editSessionToken required string Uniquely identifies the instance of FontoXML. See CMS Concepts for details.
user optional object Describes the user.
autosave optional boolean Whether to save changes periodically, defaults to true.
heartbeat optional number

Heartbeat interval in seconds. Heartbeats are disabled by default.

requestTimeoutInSeconds optional number

The amount of time in seconds a request may take before it is timed out. By default, this is 60 seconds.

useEmbeddedMode optional boolean Sets the 'use-embedded-mode' configuration setting to true, and 'theme-name' to 'neutral' if neither of them haven't explicitly been set to anything yet.

The technical description for these and other optional parameters is found in the CMS connectors API documentation, which is also the leading API definition.

Document identifier

The documentIds strings uniquely identify XML documents in the CMS. FontoXML does not process these strings and just passes them back to the CMS within relevant requests.

CMS Base URL

The cmsBaseUrl scope property defines the base URL where all CMS API endpoints are exposed. For example https://cms/api/fontoxml. Note that this scope parameter should only be used to indicate the path at which the CMS endpoints are exposed.

FontoXML does not support CORS (Cross-Origin Resource Sharing). Either host the FontoXML static files and the endpoints/API’s on the same domain -or- implement a proxy.

Edit session token

The CMS must use the editSessionToken for an edit session to uniquely identify any instance of FontoXML loaded in the user’s browser. By including it in the scope, FontoXML will be able to pass it back to the CMS when making API calls. This allows the author to be reliably identified and work in FontoXML across multiple tabs.

The edit session token must not be used for authentication. See the Security section in Implementation concerns for more information.

User

The user scope property describes the CMS account the author opened FontoXML with. This information is then used by FontoXML in the fontoxml-track-changes and fontoxml-annotations features. The value should be an object with the following properties:

User
id required string Unique identifier for the user. This is used, for instance, to distinguish changes made by this user from those made by others.
displayName required string Name of the user, for display purposes.
roleId optional string Unique identifier of the role of the user.

Autosave

The autosave scope property determines whether or not to automatically save changed documents.

When autosaves are enabled the application will send a request to PUT /document three seconds after the last edit. The request data for this API call includes a property (autosave) to indicate this is an automatic save. With this property the CMS can decide to differentiate between automatic and manual saves.

Heartbeat

The heartbeat scope property instructs the FontoXML application to send a request to the GET /heartbeat at a defined interval. The value of heartbeat is the interval time in seconds. This feature is useful for keeping the author’s CMS session and locks alive while the editor is opened.

saves.

Use embedded mode

This setting is intended for editors that are embedded on a pre-existing (CMS powered) web page, such that they cannot use the full size of the web page.
This embedded mode will optimize Fonto's UI for this scenario.

Setting useEmbeddedMode to true in the scope currently has the following effects (by automatically setting the 'use-embedded-mode' configuration variable to true):

1) the content view is stretched to take up all available width, instead of being a fixed width; sidebars are opened on top of the content view, resulting in a horizontal scrollbar for the content view.

Note: this also means that using operations that change the document width, do nothing when embedded mode is true, this affects the "set-document-content-width-to" set of operations and the "wide-canvas-content-view-to" operations.

The zoom operations do still work, they only change the text size when embedded mode is true.
The "zoom-content-view-to" are preferred over the "set-document-content-width-to" (and "set-content-view-text-size-to") operations anyway.

2) the statusbar is automatically hidden from view, after the editor is focused/hovered for the first time. The statusbar is automatically revealed when hovering for a little bit near the bottom of the screen. It can be pinned by toggling the thumb-tack icon on the bottom left. Pinned means; it is no longer automatically hidden when hovering outside the statusbar.

3) the masthead is displayed as a single line with a single select to select a "tab", instead of the normal "two lines with tab buttons on the first line".
Note: the masthead is only changed if you are using FxEditorMasthead within the masthead component you have registered. If so, you don't have to change this masthead component in any way.

Also, make sure you have not set the 'theme-name' configuration variable to 'fontoBlue' explicitly if you set this scope variable to true. That configuration variable will take precedence over this scope variable.
The intention is for theme-name to be 'neutral' when set useEmbeddedMode is true, this will happen automatically if you do not set 'theme-name' to anything.

Current limitations:
- the isHighlightedTab and isHighlightedTabQuery properties of tab items given to FxEditorMasthead are ignored.
- make sure you don't add to many quick access and/or right aligned buttons to your masthead, especially with (long) labels. These will limit the available space for buttons in each of your tab toolbars.

Request data

Context

Most requests will have a context (context) attached to them in which a session token (editSessionToken) and optionally identifiers for the folder (folderId), document (documentId) and/or referrer document (referrerDocumentId) are passed to the CMS.

For example: When a user is browsing for a document to link to, the document identifier of the document in which the link will be created is passed to the CMS so it can scope the browse action.

Metadata

Several requests and responses have a metadata object attached to them. This object must be used to transport implementation-specific information between the CMS and FontoXML. The exact content of the metadata object needs to be agreed upon on a per request basis by the CMS vendor and FontoXML.

FontoXML does not support CORS (Cross-Origin Resource Sharing). Either host the FontoXML static files and the endpoints/API’s on the same domain -or- implement a proxy.