Getting started

To make FontoXML work with documents in your CMS, a couple of steps need to be executed. The editor must be hosted by the CMS and a number of endpoints should be implemented.

Get a build of FontoXML which is configured for your content. There are two ways of acquiring a build of FontoXML:

  • Get it from one of the FontoXML partners

  • Build it yourself using our SDK

The following 7 steps should be taken to integrate FontoXML into the CMS.

Step 1 Host the FontoXML editor in the CMS

FontoXML is a single page application consisting of a main HTML file, JavaScript file, stylesheet file and some assets.

FontoXML MUST be hosted on the same domain as where the endpoints are implemented, due to authentication and cross-origin policy.

For example host FontoXML on on a subpath of the CMS: https://cms/fontoxml.

Step 2 Add a user action to the CMS to open documents with FontoXML

This action should open FontoXML by supplying some parameters telling FontoXML what to open, for who, and which CMS to talk to. This is done by supplying a scope object in the query parameter.

You MUST at least specify one document ID, the cmsBaseUrl, and SHOULD specify an user. It is advised that you also set the editSessionToken and enable the heartbeat. You can find the documentation for the scope object in the CMS connectors API.

FontoXML URL example

Other

https://cms/fontoxml?scope={"documentIds":["74257961-EDE3-4180-AF17-0A435EE8FB7B"], "cmsBaseUrl":"https://cms/api/fontoxml", "user":{"id": 1, "displayName":"Mr. Author"}, "editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE"}

Step 3 Implement the document loading and saving endpoints

In case you need cannot implement custom endpoints/API’s, you could consider using our FontoXML iFrame CMS connector. Another alternative is FontoXML Demo Connectors, which provides out-of-the-box, demo-grade connectivity for integrating an instance with Cloud storage (such as Google Drive or Microsoft OneDrive), and CMS's XML databases (Using CMIS or WebDAV).

The endpoints should be hosted under the cmsBaseUrl.

  1. For loading documents, implement the GET /document endpoint.

  2. For saving documents, implement the PUT /document endpoint.

  3. For requesting and releasing locks, implement the PUT /document/lock endpoint.

You should now be able to do the following in FontoXML:

  • Load a simple single topic document without assets (e.g. images)

Step 4 Implement additional endpoints for various basic functionality

  1. For resolving references implement the POST /reference/get endpoint.

  2. For loading assets like images implement the GET /asset/preview endpoint.

You should now be able to do the following in FontoXML:

  • Load documents which include or reference other documents

  • See included assets like images

Step 5 Implement the remaining mandatory endpoints

  1. For creating new documents implement the POST /document endpoint.

  2. For browsing documents to reference or include, assets and listing available templates implement the POST /browse endpoint.

  3. For uploading assets implement the POST /asset endpoint.

  4. For adding references to documents and assets implement the POST /reference/create endpoint.

You should now be able to do the following in FontoXML:

  • Create new documents, for example in DITA maps

  • Browse for assets like images, upload new assets and insert assets

  • Insert new or existing documents to, for example, a DITA topic

Step 6 Implement recommended and optional endpoints

This is only needed if you have the associated option enabled in FontoXML.

  1. For sending a heartbeat signal implement the GET /heartbeat endpoint.

  2. For changing reference metadata, for example the isSuspicious flag, implement the PATCH /reference/metadata/update endpoint.

  3. For downloading original assets, for example full resolution image, implement the GET /asset endpoint.

  4. FontoXML should now be fully functional if there are no implementation specific endpoints.

Step 7 Implement implementation specific endpoints

  1. Implement implementation specific endpoints when needed.

  2. In case you need iframe communication between the editor and the CMS’s page which opened FontoXML, for example for save-and-close functionality, implement the communication protocol based on postMessage. See the specific chapter about this for more information.