Invocation of Fonto Editor

This describes how an instance of Fonto Editor can be opened by the CMS in the correct state, using a document chosen in the CMS, an URL where the CMS endpoints are available, an unique token for the edit session, and some other settings and data.

/fontoxml

This is NOT an API endpoint to implement, rather a definition of the scope object needed for opening Fonto Editor. Although the instance of the editor SHOULD be hosted by the CMS or on the same domain as the CMS.

This is a description of how to invoke Fonto Editor, and instruct it to load (a) document(s). Please keep in mind that the URL length may be limited in certain browsers, so a safe limit of 2000 characters for the entire URL including query parameters should be used.

Parameters

scope (Required)

The scope object which configures the editor to load a document from the CMS. This is a JSON serialized object passed as a query string.

Parameter type	query

scope
parameter	required	type	description
documentIds	required	array[string]	The document id's of the documents 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 Fonto. See below for details.
autosave	optional	boolean	Allow/disallow auto-save functionality. Defaults to true if undefined.
heartbeat	optional	number	If set to a positive integer, enable the Heartbeat API to send every x seconds.
requestTimeoutInSeconds	optional	number	The amount of time in seconds a request may take before it is timed out. By default, this is 60 seconds.
user	optional	User	User information.
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.

Examples

JavaScript

const url = new URL('https://trial.fontoxml.com/');
url.searchParams.set('scope', JSON.stringify({ documentIds: ["structured-content.xml"], cmsBaseUrl: "/connectors/cms/standard", editSessionToken: "tab-id-token" }));
// Result: https://trial.fontoxml.com/?scope=%7B%22documentIds%22%3A%5B%22structured-content.xml%22%5D%2C%22cmsBaseUrl%22%3A%22%2Fconnectors%2Fcms%2Fstandard%22%2C%22editSessionToken%22%3A%22tab-id-token%22%7D
return url.toString();

An example of how you can construct a correctly encoded invocation URL in JavaScript.

using System;
using System.Collections.Generic;
using System.Text.Json;
using Microsoft.AspNetCore.WebUtilities;

// Build and serialize the scope
var scope = new Scope (
    documentIds: new[] {"structured-content.xml"},
    editSessionToken: "tab-id-token",
    cmsBaseUrl: "/connectors/cms/standard"
);
var serializedScope = JsonSerializer.Serialize(scope);

// Construct the url with scope query string
var editorUrlWithQueryString = QueryHelpers.AddQueryString(
    "https://trial.fontoxml.com/",
    "scope",
    serializedScope
);

// Prints https://trial.fontoxml.com/?scope=%7B%22documentIds%22%3A%5B%22structured-content.xml%22%5D,%22editSessionToken%22%3A%22tab-id-token%22,%22cmsBaseUrl%22%3A%22%2Fconnectors%2Fcms%2Fstandard%22%7D
Console.WriteLine(editorUrlWithQueryString);

record Scope(string[] documentIds, string editSessionToken, string cmsBaseUrl);

An example of how you can construct a correctly encoded invocation URL in C#.

Additional information

Document identifier

The documentIds strings uniquely identify XML documents in the CMS. Fonto Editor 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.

Fonto Editor does not support CORS (Cross-Origin Resource Sharing).

Edit session token

The CMS must use the editSessionToken for an edit session to uniquely identify any instance of Fonto Editor loaded in the user’s browser. By including it in the scope, Fonto Editor 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 Fonto across multiple tabs.

For example: When using locking the editSessionToken can be used to identify two different sessions for the same user allowing a lock to be applied in one of the sessions but not the other.

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 Fonto Editor with. This information is then used by Fonto Editor in the fontoxml-track-changes and fontoxml-annotations features. The value should be an object with the following properties:

User
parameter	required	type	description
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 two 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 Fonto Editor 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.

Use embedded mode

This setting is intended for instances of Fonto Editor 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 Editor'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):

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.

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-toand set-content-view-text-size-to operations anyway.
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.
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 Fonto. The exact content of the metadata object needs to be agreed upon on a per request basis by the CMS vendor and Fonto.