Best practices for CMS integration

This chapter describes the best practices for integrating FontoXML with the CMS. It describes how the CMS endpoints should work.

Locking

Document locking is the process of placing a constraint (‘lock’) on a document in the CMS. This constraint prevents any author that is not the author that requested the lock to make adjustments to the document. The availability of this constraint is determined by whether or not it has already been placed by another author and if this constraint can be placed on this document at all. If the constraint can be placed is determined by a range of different factors, such as author rights, which are managed by the CMS.

Optimistic locking

Optimistic locking is, as its name implies, an optimistic approach on how to handle the locking process. When using optimistic locking the assumption is made that the author should be able to place a lock on the document at any point in time. This means that when using the FontoXML editor an author is always presented with a visual representation of an editable document. The moment the author starts editing the editor will request a lock from the CMS. The author will only be blocked from editing if the lock could not be acquired. The exception to this are documents for which the author, either by rights or another factor determined on CMS level, can never get a lock.

Streamlined editing process

A document is editable until the author is told otherwise. This causes the locking process to be hidden from the author. Not having to manually request a lock on a document minimizes the amount of actions required from a author to start editing documents, and avoids the author having to take this aspect of document management into account. If a lock can’t be requested at all this is conveyed to the author by having the document loaded and visualized as a document that cannot be edited. This is a clear visual difference compared to the starting state of editable documents.

Collaborative editing when using collections of documents such as DITA’s map structure

Not having to manually request a lock on a document which is part of a collection means collaborative editing on these documents will come naturally to authors. Concurrent authors can open the same collection and start editing documents within this collection without having to be aware of each other. The author will only be made aware of this constraint when trying to change a document another author is already editing.

Additional CMS constraints regarding locking based on business logic

Using, adding and editing of business logic in the form of CMS constraints no longer needs the same level of transparency towards your authors. This is due to the fact that as far as an author is concerned everything is always editable until the editor shows you otherwise. This enables your authors to focus on the task at hand instead of being disrupted by what could be interpreted as strange or unexplained behavior.

The reason property

The ‘reason’ property can be used to provide additional information to display to the author on why a lock could not be acquired and is not available. This will then be shown next to the visual indication that a document is locked.

Guidelines

To ensure a consistent tone of voice throughout the FontoXML editor, consider the following guidelines:

  • The FontoXML editor talks like a person, so no robot talk.

  • The FontoXML editor avoids jargon and XML terms unless no clearer word is available, for example ‘metadata’. If unfamiliar terms are used, we make sure they are explained.

  • The FontoXML editor is straight to the point, in the shortest, clearest possible way.

  • The FontoXML editor uses an active voice (“can not load document”), not a passive one (“document could not be loaded”).

  • The FontoXML editor will never blame the user or any other system for what went wrong; it simply offers the author options on how to proceed.

Using the heartbeat or state to monitor for active session

When using document locking it is possible for an author to never release a lock placed by him/her. This can happen due to multiple reasons, including but not limited to:

  • Loss of internet connection.

  • Closing the browser (tab).

  • Crashing of the browser (tab).

The CMS should leverage the heartbeat or state feature provided by the FontoXML editor to ensure documents do not remain in this locked state until the author manually releases the lock .

GET /heartbeat

When enabled, the FontoXML editor issues a periodic call to GET /heartbeat. This call is made at a configurable interval to notify the CMS that the author still has an instance of the editor open, indicated by the editSessionToken passed in the model of the call.

Once the editor stops issuing the heartbeat call for a longer duration the CMS should assume the editing session is stopped and it should unlock the document if still locked.

POST /document/state

Periodically retrieves the most recent lock state and revisionId for a set of documents from the CMS. Can be used to notify the CMS that the author still has an instance of the editor open, indicated by the editSessionToken passed in the model of the call.

Once the editor stops issuing the state call for a longer duration the CMS should assume the editing session is stopped and it should unlock the document if still locked.

Example

This is only an example of an approach. You are free to use either call in whatever way you see fit.

When an author opens a document in FontoXML a 30 minute lock is placed on the document. Every time the CMS receives the heartbeat/state call this lock is refreshed. When the call is no longer received the lock expires within 30 minutes and another author is free to open and edit the document.

Templates

In many cases you or your organization might want to provide authors with document templates. These templates help to get them started quickly and improve completeness of documentation for common situations. In order to give users a meaningful experience there are guidelines and best practices to consider when creating these templates.

The following section describes guidelines and aspects to consider in order to make document templates as effective as possible. It also explains “text placeholders”, an XML processing instruction that has special behavior in the FontoXML editor, in the last chapter.

The following guidelines are specific for creating and describing the XML templates that are made available through the CMS.

First and foremost, document templates are regular XML documents that therefore should be valid according to their schema. A document template is recognized as such by the CMS because it’s been placed in a different folder or has special attributes (this is not part of the XML and may differ per CMS). A document template typically contains editorial instructions.

Information that describes the template

The template browser dialog uses CMS-supplied information to describe templates. Each template should be easily recognizable. With this in mind, pay attention to the following fields for each template:

Label

The label is a template’s primary identifier for a user, not unlike a filename in Windows Explorer. Use a short phrase to name the template. If there is a commonly used name within the organization, it could be a good idea to use this.

  • Must be a short, unambiguous phrase

  • Must fit the users’ frame of reference

  • The same label must not be used for different templates

Description

The description is shown once a user selects a template that he may want to use and should therefore provide additional details. Describe when to use the template and when not to.

  • Consists of one or more full sentences, using Fonto’s tone of voice and glossary.

  • Do not provide details on how to use the template after insertion. This information can be provided as editorial instructions in the template content.

Image

An added goal of the image is to make the templates more recognizable. There are two options, which should not be mixed:

  • Using an icon or other schematic representation. Icons may be specifically designed to highlight characteristic features of the template, and may use concepts the user is already familiar with. Icon images should be carefully designed to be easily distinguishable yet also consistent with each other.

  • Using a screenshot of (part of) the resulting document. If the organization has a clear primary publishing platform that users are familiar with, a screenshot of the “finished product” will help the user to recognize it. Ensure the screenshots are easily distinguishable in the limited space available for the template browser’s thumbnails.

The actual templates

The template should provide a boilerplate for the semantic structure desired for its use case.

  • Focus on providing only the basic necessary structure; do not include (placeholders for) every possible structural element.

  • Provide guidance on desired use of these structural elements using editorial instructions, as detailed below. The wording of these instructions should adhere to the tone-of-voice guidelines.

Please contact your FontoXML consultant if you have any questions on how to apply the guidelines.

Editorial instructions

Editorial instructions are most suitable to provide an instructional phrase for a specific element. In FontoXML these can be created by including ‘fontoxml-text-placeholder’ processing instructions in the template XML. These are visualized as a placeholder text that can easily be replaced with actual content by simply clicking on them. In XML, the syntax is as in the following example:

XML

<figure>
	<title><?fontoxml-text-placeholder text="Add a short, descriptive title for the image"?></title>
	[...]
</figure>

Quotes in the “text” pseudo-attribute may be escaped using a backslash (\"). The forbidden “?>” character sequence can be escaped by replacing it by “?\>”.

This processing instruction is visualized as shown in the following screenshot:

Placeholders are automatically removed when a user makes a change within the same element.

Alternatively placeholders can be automatically placed in elements in case they are (left) empty. This type of placeholder requires configuration within FontoXML. You may use this to your advantage by inserting elements without content in your template and letting FontoXML create the placeholder for you.

In some cases you may want to provide placeholders within an element with other content, for example when the placeholder substitutes only a part of a paragraph. In this case, use the “autoremove” attribute on the placeholder, like so:

XML

<p>The first version of <?fontoxml-text-placeholder text="product name..." autoremove="false"?> is now available.</p>

This will make sure the placeholder is only removed if it was selected beforehand.