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();
C#
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);
Additional information
Document identifier
The document
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.
C MS Base UR L
The cms
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.
Edit session token
The CMS must use the edit
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 edit
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 P
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 G
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 use
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 thewide-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 theset-document-content-width-to
andset-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 Fx
Editor Masthead 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 fonto
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 use
is true, this will happen automatically if you do not set theme-name
to anything.
Current limitations:- the is
and is
properties of tab items given to Fx
Request data
Context
Most requests will have a context (context
) attached to them in which a session token (edit
) and optionally identifiers for the folder (folder
), document (document
) and/or referrer document (referrer
) 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.