Configuration

Fonto Editor

The client-side UI configuration of Fonto Review is described in the README file of Fonto's reference configuration repository. This describes the following configuration options:

Alongside the UI configuration, there are a few other options, which are listed below.

Annotation target types

Fonto Review offers several annotation target types besides just text ranges starting from release 7.9. Target types describe where the annotation is located in the document. The available annotation target types are listed below.

Text Range

These are the most basic annotation target types that are available. These point to a text range in the document, with a start and end container ending in a textnode. Configuring text range target types is done via the registerTextRangeReviewAnnotationType registration API.

Target type in database: TEXT_RANGE_SELECTOR

Objects

Object targets can point to any single object in the document. Objects in this sense are for example images and formulas. Configuring object target types is done via the registerObjectReviewAnnotationType registration API.

Target type in database: OBJECT_SELECTOR

Publications

Publication targets point to the loaded document in general. They are not attached to any range in the document. Technically they point to the loaded root document. Configuring publication target types is done via the registerPublicationReviewAnnotationType registration API.

Target type in database: PUBLICATION_SELECTOR

Review state polling interval

The interval used by the background polling mechanism, which defaults to 7 seconds, can be changed. The default interval is based on achieving a decent user experience, avoiding users making changes which they will eventually lose. The interval can be changed using the remote-review-state-update-interval-ms configuration variable.

Server side filtering

Fonto Review requires a server-side filter component in the CMS it connects to. The review/state call sends a request with the current active filter form values. The CMS is expected to filter out annotations that do not match the filter.

Fonto's development CMS does not provide any of this filter logic by default (it will always return all annotations), since it is very specific to a data model. A filter for the development CMS can be specified the configureDevCms.js file in the dev-cms directory of Fonto Editor.

The following is an example configureDevCms.js file:

configureDevCms.js
'use strict';
 
const matchAnnotationToCurrentFilter = require('../<PATH TO YOUR FILTER FUNCTION>');
 
module.exports = (router, config) => {
    return {
        reviewAnnotationFilter: matchAnnotationToCurrentFilter
        // This key might be defined if the development CMS routes have been customized.
        // routes: myCustomRoutes
    };
};

Change proposals

This feature is also sometimes called change suggestions.

Fonto offers the ability to automatically merge change proposals into a document. This feature is only enabled if your data model uses a proposedChange property inside the annotation's metadata which is the default in the reference configuration.

Fonto will provide your annotation card with an onProposalMerge callback function that merges the text proposed by aforementioned property into the document. Fonto also provides the reviewAnnotation that gets passed into the card annotation card with a proposalState property that indicates what the current proposalState is (e.g. that it cannot be merged because the originating text changed or the proposal would yield a schema invalid situation). The proposalState property will only be set if the annotation is selected.

The default ReviewAnnotationAcceptProposalButton component can be used to have the same behaviour as the reference configuration implements.

Fonto Review backend

Schema experience

Starting from Fonto 7.10, Fonto Review has additional required configuration. This configuration is necessary to perform a compare between revisions of documents to map positions (annotations) from one revision to another.

This configuration consists of two environment variables:

Option Default Required Description
SchemaExperience__BlockTest (None) Yes

The value of this setting is an XPath that checks whether the given node is a block.

Must be XPath 1.0 compliant.

Example:

self::p or self::td or self::title or self::li

Example with namespaces:

*[(local-name()='p' or local-name()='td' or local-name()='title' or local-name()='li') and namespace-uri()='my:namespace:uri']
SchemaExperience__ObjectTest (None) Yes

The value of this setting is an XPath that checks whether the given node is an object.

Must be XPath 1.0 compliant.

Example:

self::img or self::formula

Example with namespaces:

*[(local-name()='img' or local-name()='formula') and namespace-uri()='my:namespace:uri']

DITA Example:

For our own DITA Example Editor, use the following 2 configuration settings:

BlockTest:

SchemaExperience__BlockTest="self::alt or self::cmd or self::codeblock or self::consequence or self::ddhd or self::dt or self::dthd or self::equation-block or self::glossAbbreviation or self::glossAcronym or self::glossdef or self::glossShortForm or self::glossSynonym or self::glossterm or self::howtoavoid or self::lcAge or self::lcAssessment or self::lcAttitude or self::lcBackground or self::lcDelivery or self::lcEdLevel or self::lcGapItemDelta or self::lcGeneralDescription or self::lcGoals or self::lcInteractionLabel2 or self::lcJtaItem or self::lcKnowledge or self::lcLearnStrat or self::lcMotivation or self::lcNeeds or self::lcObjective or self::lcObjectivesStem or self::lcOrgConstraints or self::lcPlanObjective or self::lcPlanResources or self::lcProcesses or self::lcSkills or self::lcSpecChars or self::lcTaskItem or self::lcTime or self::lcValues or self::lcWorkEnvDescription or self::lines or self::linktext or self::navtitle or self::p or self::pre or self::proptype or self::propvalue or self::pt or self::screen or self::searchtitle or self::shortdesc or self::sli or self::title or self::typeofhazard"

ObjectTest:

SchemaExperience__ObjectTest="self::img or self::hazardsymbol or self::mathml"


Annotation Export API

New in the Fonto 7.11 release is the Export functionality. The backend offers an additional endpoint that can be called to retrieve a CSV export of the annotations in the given documents. Starting with Fonto 7.11, this feature offers the ability to specify multiple exports and a format per export.

The Annotation Export API will only return annotations that are returned on the /review/state/ calls. This means that private annotations will not be exported by default.

The configuration needs to be done in a new exports.xml file in the root of your application. Further documentation of the configuration file can be found in the corresponding XSD file, which you can find here: http://schemas.fontoxml.com/review/1.0/exports.xsd

An example file is described below. It follows the datamodel as described in the Fonto Review Reference Configuration.

exports.xml
<exports>
    <csvExport id="123">
        <textColumn select="id" header="ID" />
        <textColumn select="originalText" header="Original text" />
        <textColumn select="metadata.commentType" header="Comment type" />
        <textColumn select="metadata.comment" header="Comment" />
        <textColumn select="metadata.proposedChange" header="Proposed change" />
        <textColumn select="resolvedMetadata.resolution" header="Resolution" />
        <textColumn select="resolvedMetadata.resolution.resolvedComment" header="Resolution message" />
    </csvExport>
</exports>


Host configuration options

In addition to the generic host configuration options, the Fonto Review backend provides the following configuration options:

Option Default Required Description
Cms:ApiBaseUrl
(None) Yes

The absolute base URL of the CMS endpoint including a trailing slash. This endpoint must be accessible by the backend.

These options can be configured using any of the supported configuration providers. Information about configuration conventions might prove useful. When running the Fonto Review backend using the Fonto Development Tools, configuring the options as environment variables in an .env file is supported.

Command line parameters

The Fonto Review backend supports the following command line parameters:

Parameter

Default

Required

Description

--as-windows-service

(None)

No

Run the backend as Windows Service. Only available for self-contained builds on Windows.

Logging

Logging options can be provided using any of the supported configuration providers. Please refer to the logging configuration page for available options. In addition, the Fonto Review backend supports an optional NLog configuration file. Information about how to configure NLog can be found in its official documentation.