How and why we changed the way our references work

The way FontoXML applications deal with references has changed in the 7.0 release. Not only does this release introduce new add-ons to provide the various bits of UI for reference elements (such as popovers and insert / edit modals), FontoXML 7.0 also simplifies the way references are configured. In previous releases of FontoXML, it was necessary to implement and register a subclass of ReferenceType to provide details about your referencing elements, and then to use a mix of generic and reference-specific operations to manipulate them. In FontoXML 7.0, this "reference pipeline" has been removed in favor of simple transforms that each handle one step in the pipeline. This has the following advantages:

  • it removes the need to mix generic and specific operations - each operation can be specific for the type of reference it deals with and is composed of easily understandable steps

  • it removes the need to implement parts of ReferenceType that will not be used in your application - if you will only insert and remove references, it is not necessary to provide code to parse a reference into a form for editing

  • it removes specialized API to add a popover to references by using the same API as for other elements, while providing a standard component to retain the same look and feel as well as removing much of the complexity of dealing with references and their permanent IDs

  • it adds support for reusing reference type names for multiple references - previously, each reference type name would be linked to a single ReferenceType implementation. Now, the type name is only used when communicating with the CMS, and can be changed and reused as desired

  • it makes the use of permanent IDs optional for some reference types - by simply omitting the transforms to create and resolve permanent IDs, and by configuring related components and/or visualizations, FontoXML now supports both references encoded as permanent IDs and those that are not. For instance, as web references are usually absolute, you could now choose to insert the URL into the document directly instead of generating a permanent ID.

Permanent IDs should continue to be used for any reference for which the interpretation depends on the document they are located in, such as relative URLs. FontoXML will not modify your references if they are copy/pasted or otherwise moved between different documents. Permanent IDs make such references independent of their context, so their interpretation is no longer affected by these operations.

Additionally, note that the visualizations for certain types of references such as images do not yet support omitting permanent IDs in the 7.0 release. Support for non-permanent-ID versions of these may be added in future versions.

You will probably need to update or replace most parts of the reference configuration for your schemas, as both the UI and the reference APIs have changed. Please refer to the guide on configuring Work with references for step-by-step instructions on how to configure references using the new APIs, as well as specific considerations for many common types of references. In short:

  • For any insert or edit operations, select a new modal or reconfigure a custom one using FDS. Then, instead of transformReferenceStepDataForCommand, use a schema-specific transform to create a URL (e.g., createDitaUrlFromLoadedTarget) and createPermanentIdForReference to turn this URL into a permanent ID. Finally, insert the permanent ID into the DOM in a way appropriate for your reference.

  • Set up popovers as for any other element (see Create a popover). Consider using FxReferencePopover, or one of the ready-made popovers in the fontoxml-crosslink-references and fontoxml-web-references add-ons.

The new transforms provided in the 7.0 release to create DITA URLs (createDitaUrlFromLoadedTarget and createDitaUrlFromRemoteTarget) and permanent IDs automate the task of determining the referrer document that was previously required for most operations dealing with references and related UI. You can likely remove any custom transforms or usage of the ensureReferrerDocumentIdIsSet transform that was included in FontoXML 6.x.