Use cases

This chapter describes several use cases which illustrates the ways the CMS connector can work.

The use cases might refer to certain buttons, elements, and attributes. In most cases these are just examples and can be different in every implementation based on user experience and XML schema. Some use cases also use optional steps, these might or might not be present depending on the specific configuration of FontoXML.

Opening FontoXML in an iframe

The most common way to open FontoXML is in an iframe within the CMS.

  1. The CMS opens an iframe with the src attribute set to the URL of the FontoXML editor including the scope query parameter.

  2. FontoXML parses the scope parameter and loads the document(s).

Communicating from the FontoXML iframe to its parent window

This use case describes direct interactions from the user that require direct feedback from the CMS. Examples interactions are: ‘Close FontoXML and return to the CMS’, ‘Save and close and return to the CMS’, ‘Toggle full screen’.

  1. If the user clicks one of these buttons, FontoXML uses the HTML5 standard postMessage API to send the command to its parent window or frame. See postMessage API documentation for details.

  2. The messageString is a serialized JSON representation of the message object.

  3. The message object will always contain the following properties:

    1. type: The message type, for example ‘fontoxml-close’ or ‘fontoxml-toggle-fullscreen’.

    2. scope: The scope object that was passed when FontoXML was opened, as specified in the CMS Connector contract.

    3. metadata: An object that may contain command specific properties.

  4. The JavaScript on the CMS’s page that created the iframe should listen to these messages using .addEventListener('message', callback) or .attachEvent('onmessage', callback) – depending on the browser – and act accordingly. The CMS is responsible for closing the iframe, resizing the iframe, releasing locks and/or cleaning up automatic saves if necessary.

This use case assumes the CMS opened FontoXML in an iframe.

The fontoxml-close command might not be sent if the browser closes in an unsupported or unexpected way.

Communicating from the parent window to the FontoXML iframe

This use case describes how the parent window which initiated the FontoXML iframe can send messages, for example execute operation, to FontoXML. Please note that FontoXML must be configured to accept the specific message.

  1. The parent window needs to execute a specific operation in FontoXML, for example initiate a graceful save and close.

  2. The parent window sends a message to the FontoXML iframe using the postMessage API.

  3. The messageString is a serialized JSON representation of the message object.

  4. The message object contains the following properties:

    1. type: Required, the message type, for example fontoxml-execute-operation.

    2. operationName: Optional, in case of type=fontoxml-execute-operation specifies the operation to execute, for example ‘save-and-close’.

    3. correlationId: Optional, an ID you can pass along which you will get back in the response message so you can match responses with your requests.

    4. data: Optional, additional data to pass along with the message, for example operation data.

  5. FontoXML will receive the message and act accordingly, for example execute the specified operation.

  6. When done FontoXML will send a message back using the postMessage API.

  7. The messageString is a serialized JSON representation of the message object.

  8. The message object contains the following properties:

    1. type: Required, the message type FontoXML is replying to, for example fontoxml-execute-operation.

    2. correlationId: Optional, the correlationId as specified in the request.

    3. success: Optional, whether or not the operation execution was successful.

The operation to execute needs to be added to FontoXML’s operation whitelist.

Load & save a single document

Only applicable if a single document is edited at the same time.

  1. The CMS opens an iframe passing the documentId which to load in the scope parameter to the FontoXML editor application.

  2. FontoXML uses the GET /document api to load the document from the CMS.

  3. The user modifies the document and clicks the save button.

  4. FontoXML uses the PUT /document api to save the document back to the CMS.

Loading & saving multiple documents

Only applicable if multiple documents are modified in FontoXML at the same time.

  1. The CMS opens an iframe passing the documentIdswhich to load in the scope parameter to the FontoXML editor application.

  2. For each documentId FontoXML uses the GET /document api to load document until all the documents are loaded into FontoXML.

  3. The user modifies several documents and clicks the save button.

  4. For each modified document FontoXML uses the PUT /document to save the document.

Loading & saving multiple documents in a map

Only applicable if multiple documents are modified in FontoXML at the same time. In this example use case DITA is used to illustrate the concepts, but the concepts are applicable to any multi document structure.

  1. The CMS opens an iframe passing the documentId of the map which to load in the scope parameter to the FontoXML editor application.

  2. FontoXML uses the GET /document api to load the map document from the CMS.

  3. FontoXML iterates over the map to find referenced documents.

  4. Optionally (if the reference pipeline is enabled):

    1. All document references are resolved using the POST /reference/get api to get the actual target documentIds.

  5. For each referred document FontoXML uses the GET /document api to load the document until all the documents are loaded into FontoXML.

  6. Optionally:

    1. If the loaded document is another map, FontoXML repeats this flow from step 3.

  7. The user modifies several documents and clicks the save button.

  8. For each modified document FontoXML uses the PUT /document to save the document.

Opening the editor without a document

The editor might be configured to be able to start without any loaded document and the user will create a new document.

  1. The CMS opens an iframe passing scope with documentIds being empty.

  2. FontoXML opens the ‘New document’ modal.

  3. Optionally (If the editor is configured to allow creating a document in a specific folder):

    1. FontoXML displays the results of a request to the POST /browse api without specifying a folderId but with type set to document.

    2. The user selects the desired folder.

  4. The user specifies the needed input, for example a title.

  5. FontoXML generates the XML skeleton of the new topic.

  6. FontoXML executes a request to the POST /document api, with optionally a folderId, content and/or metadata.

  7. The CMS creates the document and can optionally update the XML content and/or metadata and generates a documentId, which are returned in the response object.

  8. The user can now work in the new document.

Automatically saving a document

FontoXML will automatically trigger a save for the user 2 seconds after the last change they made.

  1. The CMS opens an iframe passing the documentId which to load in the scope parameter and scope.autosaveset to true to the FontoXML editor application.

  2. FontoXML uses the GET /document api to load the document from the CMS.

  3. The user modifies the document and waits for 2 seconds.

  4. FontoXML uses the PUT /document api to save the document back to the CMS, the autosave parameter is set to true.

Note that all documents are saved when the user executes an explicit save. This includes all documents which are were automatically saved since the last change.

Autosave can be disabled if necessary, see the scope object definition for information.

Acquire document lock

This use case describes how the editor interacts with the locking mechanism. If the CMS does not support locking then both lock.isLockAvailable and lock.isLockAcquired must be set to true or false depending on whether or not the document is writable by the user. FontoXML allows users to edit documents for which the lock as not yet been acquired, the lock will be acquired before saving the document.

  1. FontoXML uses the GET /document api to load a document.

  2. The CMS returns the document with lock.isLockAcquired set to false and lock.isLockAvailable set to true.

  3. The user modifies the file for which no lock has been acquired yet, but for which the lock is available.

  4. In the background FontoXML uses the PUT /document/lock api to request a lock with the documentId set to the id of the current document, documentETag to the ETag of the current document from when the document was loaded and lock.isLockAcquired set to true.

  5. Depending on the response of the server the following things can happen:

    1. The CMS returns 204 indicating the document is now locked for the user and was not modified since it was retrieved via the GET /document api based on the ETag.

    2. The CMS returns 403 indicating the document could not be locked. FontoXML reverts the change to the document and informs the user about the failed lock acquisition.

    3. The CMS returns 404 indicating the document is no longer available, FontoXML will alert the user.

    4. The CMS returns 412 indicating the document was modified after the GET /document request but before the PUT /document/lock was made. FontoXML will first retrieve the document using the GET /document api then one of the following scenarios can occur:

      1. The document is no longer available, FontoXML will alert the user.

      2. The modified document is still available and was reloaded, FontoXML will try to execute the PUT /document/lock request again (Step 4).

    5. The CMS returns 412 indicating the document is already locked by someone else, so the lock cannot be acquired. FontoXML reverts the changes to the document and informs the user about the failed lock acquisition.

Previously a return code of 423 was used to indicate the document is already locked by someone else, this has changed to 412.

Releasing the lock on the document

This use case describes how FontoXML interacts with a locking mechanism provided by the CMS. This use case assumes that a document is loaded and a lock has been acquired for that document (lock.isLockAcquired is true).

  1. The user chooses to release the lock, for example by clicking on the ‘Release lock’ button.

  2. When there are unsaved changes in a document:

    1. FontoXML saves the document using the PUT /document api.

  3. FontoXML makes a request to the PUT /document/lock api to release the lock with the documentId set to the id of the current document and documentETag to the ETag of the current document from when the document was loaded and lock.isLockAcquired set to false.

Adding an existing topic to a map

This use case assumes a DITA map is loaded and lock is acquired in the current FontoXML editing session.

  1. The user clicks the ‘Include existing topic’ button.

  2. FontoXML opens the browse modal displaying the results of a request to the POST /browse api without specifying a folderId but with type set to document.

  3. The user selects a topic to include in the map.

  4. FontoXML retrieves the content of the newly added topic using the GET /document api passing the documentId it got from the POST /browse api (BrowseResultItem.id) with context.referrerDocumentId set to the map document identifier in which the topic was added.

  5. Optionally (if the reference pipeline is enabled):

    1. A new reference is created using the POST /reference/create api, the returned permanentId is used in the map document to reference the document. The permanentId could be an existing permanentId if a reference already existed for the document.

  6. FontoXML modifies the map document and saves it using the PUT /document api.

Adding a new topic to a map

This use case assumes a DITA map is loaded and is writable in the current FontoXML editing session.

  1. The user clicks the ‘Add new topic’ button.

  2. FontoXML opens the new topic modal.

  3. Optionally (If the editor is configured to allow creating a document in a specific folder):

    1. FontoXML displays the results of a request to the POST /browse api without specifying a folderId but with type set to document.

    2. The user selects the desired folder.

  4. FontoXML displays the results of a request to the POST /browse without specifying a folderId but with type set to document-template.

  5. The user selects the desired template.

  6. FontoXML will preprocess the template, for example it will generate unique IDs for elements for which this is configured.

    Note that FontoXML will also (re)create ID’s, if they are configured for elements in the template.

  7. FontoXML executes a request to the POST /document api with context.referrerDocumentId set to the map document identifier in which the topic will be added and content set to the processed content for the new document.

  8. The CMS creates the document and can optionally update the XML content and/or metadata and generates a documentId.

  9. Optionally (if the reference pipeline is enabled):

    1. A new reference is created using the POST /reference/create api, the returned permanentId is used in the map document to reference the document.

  10. FontoXML inserts the reference element in the map document and saves it using the PUT /document api.

Moving a topic to another map

This use case assumes two DITA maps (Map A & Map B) are loaded and are writable in the current FontoXML editing session.

  1. The user moves a topic from map A to map B.

  2. FontoXML modifies the map A document and saves it using the PUT /document api.

  3. FontoXML modifies the map B document and saves it using the PUT /document api.

Removing a topic from the map

This use case assumes a DITA map is loaded and is writable in the current FontoXML editing session.

  1. The user removes a topic from a map.

  2. FontoXML modifies the map document and saves it using the PUT /document api.

Insert a reference to another document

This use case assumes a document is loaded and is writable in the current FontoXML editing session.

  1. The user clicks the ‘Insert reference’ button.

  2. FontoXML opens the browse modal displaying the results of a request to the POST /browse api without specifying a folderId but with type set to ‘document’.

  3. Optionally:

    1. The user clicks on a folder.

    2. FontoXML loads the contents of the folder using the POST /browse api using the folder’s BrowseResultItem.id as folderId and typeset to document.

    3. Continue from step 3.

  4. Optionally:

    1. The user clicks on a document.

    2. FontoXML loads the contents of the document using the GET /document api using the document’s BrowseResultItem.id as documentId.

    3. FontoXML parses the document to retrieve deep link element id’s and labels, and displays them.

  5. The user clicks the ‘Insert’ button.

  6. Optionally (if the reference pipeline is enabled):

    1. A new reference is created using the POST /reference/create api, the returned permanentId is used in the document to reference the document. The permanentId could be an existing permanentId if a reference already existed for the referenced document.

  7. FontoXML inserts the reference element into the document using the BrowseResultItem.id (or permanentId) as href (or similar) attribute value.

Insert an existing graphical asset into the document

This case assumes a document is loaded and is writable in the current FontoXML editing session.

  1. The user clicks the ‘Insert image’ button.

  2. FontoXML opens the browse modal displaying the results of a request to the POST /browse api without specifying a folderId but with type set to image.

  3. Optionally:

    1. The browse modal loads thumbnails for all items from the GET /asset/preview api using BrowseResultItem.id as id and variant set to thumbnail.

  4. Optionally:

    1. The user clicks on a folder.

    2. FontoXML loads the contents of the folder using the POST /browse api using the folder’s BrowseResultItem.id as folderId and type set to image.

    3. Continue from step 3.

  5. The user selects an image to insert in the document.

  6. Optionally (if the reference pipeline is enabled):

    1. A new reference is created using the POST /reference/create api, the returned permanentId is used in the document to reference the graphical asset. The permanentId could be an existing permanentId if a reference already existed for the referenced graphical asset.

  7. FontoXML inserts the image element into the document using BrowseResultItem.id (or permanentId) as src (or similar) attribute value.

  8. FontoXML renders the inserted image using the GET /asset/preview api using BrowseResultItem.id (or permanentId) as id and variant set to web. In case of other media FontoXML might use the original version of the asset (maybe to stream a video or audio file) using the GET /asset api using BrowseResultItem.id (or permanentId) as id.

Upload and insert a graphical asset into the document

This case assumes a document is loaded and is writable in the current FontoXML editing session.

  1. The user clicks the ‘Insert image’ button.

  2. FontoXML opens the browse modal and displaying the results of a request to the POST /browse api without specifying a folderId but with type set to image.

  3. Optionally:

    1. The browse modal loads thumbnails for all items from the GET /asset/preview api using BrowseResultItem.id as id and variant set to thumbnail.

  4. The user selects a file to upload and presses upload.

  5. FontoXML uploads the file to the POST /asset api with folderId set to the current folder’s BrowseResultItem.id, if any.

  6. Optionally (if the reference pipeline is enabled):

    1. A new reference is created using the POST /reference/create api, the returned permanentId is used in the document to reference the graphical asset.

  7. FontoXML inserts the image element into the document using the returned AssetUploadResult.id (or permanentId) as src (or similar) attribute value.

  8. FontoXML renders the inserted image using the GET /asset/preview api using AssetUploadResult.id (or permanentId) as id and variant set to web.

Load a document which contains a graphical asset

This case assumes a document gets loaded which contains at least one graphical asset.

  1. FontoXML loads the document using the GET /document api and renders it.

  2. Optionally (if the reference pipeline is enabled):

    1. All graphical assets references are resolved using the POST /reference/get api to get the actual target assetIds.

  3. When rendering an image element, FontoXML uses the GET /asset/preview api using the element’s src (or similar) attribute value (or permanentId) as id and variant set to web.

The CMS requires the edit session to be kept alive

The CMS might require the edit session to be kept alive for as long as the editor is open. This might be necessary to protect against session timeout or stale sessions, but might also be used by the CMS to release document locks.

  1. The CMS opens an iframe passing the documentId which to load in the scope parameter and scope.heartbeat set to a positive integer, for example 300, to the FontoXML editor application.

  2. While the user works in the document(s), FontoXML sends a request to the GET /heartbeat api with the current editSessionToken every 300 seconds.

  3. FontoXML will repeat step 2 for as long as the editor is open.