Configure reference pipeline

This guide describes how references, such as images and hyperlinks, can be configured in both behavior and visualization.

References and permanent IDs

Many schemas contain the ability to create references to other things, be it items contained elsewhere in the document, other documents or content therein, or external resources such as web pages or images. FontoXML provides functionality to enable your users to create and interact with such elements in a straightforward way.

References generally take the form of a specialized element, such as the HTML a element, with an attribute, say href, that specifies the target of the reference. This target is usually encoded as an URL, although other formats are possible. In some cases, the target is specified in a way that is relative to its context, such as the location of the document containing the reference. This creates problems when moving (or copying) content containing such references to other documents, or sometimes even within the same document. To avoid such problems, we recommend storing all references in a form that is independent of context. To help with this, FontoXML provides the concept of a permanent reference ID (permanent ID for short). The reference CMS endpoints allow the editor to ask the CMS to create a permanent ID for any reference that is to be inserted into the document, as well as to resolve such an ID back to the original information used to create it. Inserting a reference element with a permanent ID as its target, rather than the original relative URL, allows the reference to be moved freely between documents without requiring complicated logic to rewrite it whenever its location changes.

FontoXML versions prior to 7.0 required the CMS to provide a correct value for the type of a reference when resolving a permanent ID. This value was then used to determine the operations to use to edit and remove the reference. This was usually the same type used when creating the reference. The operations provided in FontoXML 7.0 assume that this information can be derived from the DOM alone. If you want to use the CMS-provided value, you can create your own popover to first retrieve the reference and then present appropriate operations to the user, or use a custom transform after retrieveReferenceFromPermanentId to change behavior based on the reference.type returned.

Reference metadata and validity

When creating a permanent ID for a reference in the CMS, FontoXML supports providing additional metadata for the reference. This metadata can be supplemented by the CMS and is returned whenever the reference is retrieved. One possibility this offers is to mark the validity of references. Setting the special metadata property isSuspicious to true for any reference will cause elements of supported families representing that reference to be marked with a red underline.

Configuring references

Configure element appearance and behavior

FontoXML includes a number of families for visualizing reference elements in your documents:

  • Use configureAsInlineLink for hyperlink-like elements that are part of the text of your document. This family provides the familiar blue underlined style commonly used for links on the web. It also enables reference validity visualization if the referencePermanentIdAttributeName argument is provided.
  • Use configureAsImage for block-level images, configureAsInlineImage for inline images, and configureAsImageInFrame / configureAsInlineImageInFrame for framed versions of these, respectively. The framed versions can be useful if the element representing the image reference may have additional elements as content. These families render such content inside the frame, after the image itself. Note that these families only support images represented as permanent IDs at this time.
  • For DITA related links, use the configureAsRelatedLink family.
  • For DITA conrefs, use the configureAsConref family.

When using configureAsInlineLink with references that do not use permanent IDs, set the referencePermanentIdAttributeName argument to undefined to avoid the reference validity check trying to retrieve metadata for these references from the CMS.

Configure a popover

Popovers for references can be configured the same way as for any other element. Refer to Create a popover for details. To simplify dealing with permanent IDs and to provide a consistent look and feel for your reference popovers, consider using the FxReferencePopover to base your popover on. The open-source fontoxml-crosslink-references and fontoxml-web-references add-ons provide example popover implementations that use this approach.

Define operations

Like any element, references are inserted, modified and deleted using operations. You will need to define these operations by composing them out of several steps, as discussed in the sections below.

Choose or design a modal

FontoXML provides a number of add-ons that implement familiar browser interfaces for nodes and/or documents as well as a standard URL entry modal. See the "additional considerations" sections below for links to appropriate add-ons for common reference types. Many of these add-ons are provided as open source software, and may be easily modified to suit your needs. Alternatively, you can use FDS components directly to create your own modal. In either case, you probably need a variation of the modal for inserting a reference as well as one for editing an existing one. This is usually achieved by using a single modal, with two operations that each provide alternative text as step data, to adapt the modal's components to each scenario.

If you use one or more of the modal add-ons in your operations, don't forget to include a dependency on the add-on package in the config/fonto-manifest.json for your application.

Inserting the reference

An operation that inserts a reference generally consists of the following steps:

  1. Open an appropriate modal to allow the user to select or otherwise provide the target of the reference.
  2. Transform the target from the representation returned by the modal into a URL.
  3. If permanent IDs are used, create a permanent ID for the URL.
  4. Insert an element or structure representing the reference, with an attribute containing the permanent ID (or URL if permanent IDs are not used).

As an example, consider the insertion of a DITA topicref (some details omitted):

{
    "contextual-topicref-to-existing-document-insert": {
        "label": "Insert existing topic",
        "description": "Insert an existing topic below the current one.",
        "icon": "file-text-o",
        "steps": [
            // 1. Open the document browse modal (provided by the fontoxml-cms-browser add-on)
            {
                "type": "operation/open-document-browser-modal"
            },
            // 2. This returns the documentId of the document we want the topicref to point to.
            {
                "type": "transform/createDitaUrlFromLoadedTarget",
                "data": {
                    "targetDocumentId": "{{documentId}}",
                    "targetNodeId": null
                }
            },
            // 3. DITA maps require permanent IDs (as DITA URLs may otherwise be relative)
            {
                "type": "transform/createPermanentIdForReference",
                "data": {
                    "target": "{{url}}",
                    "referenceType": "document",
                    "metadata": {}
                }
            },
            // 4. Insert the topicref element in the target DITA map
            {
                "type": "operation/append-topicref",
                "data": {
                    "contextNodeId": "{{contextNodeId}}",
                    "documentId": "{{targetDocumentId}}",
                    "targetHref": "{{permanentId}}"
                }
            }
        ]
    }
}

Please refer to the following pages for more details on the steps used in the example:

Modifying the reference

Editing a reference to point to a different target is very similar to inserting one, with two differences. First, the operation at the end is replaced with one to update the DOM structures for the existing reference rather than inserting new ones. Second, the operation usually pre-populates the modal with the details of the existing reference, which requires reversing the transformations performed to create it:

  1. If permanent IDs are used, retrieve the permanent ID from the CMS to obtain the original URL.
  2. Parse the URL in order to obtain a representation of the target that is compatible with the modal.
  3. Open an appropriate modal using the operation for its edit variation.
  4. Transform the resulting updated target from the representation returned by the modal into a URL.
  5. If permanent IDs are used, create a permanent ID for the URL.
  6. Update the attribute containing the target to the new permanent ID or URL.

References in your documents could be broken due to various reasons, including permanent IDs getting deleted from the CMS, or documents being edited manually outside of FontoXML. To prevent the entire edit operation from failing, make sure that steps 1 and 2 allow the operation to continue in case of errors.

As an example, consider the dita-permanent-id-web-reference-edit operation provided by the fontoxml-dita add-on:

{
    "dita-permanent-id-web-reference-edit": {
        "label": "Edit",
        "steps": [
            // 1. Retrieve the details of the reference with the permanent ID stored in the DOM
            // Note the use of an inline XPath expression to obtain the value of the href attribute
            {
                "type": "transform/retrieveReferenceFromPermanentId",
                "data": {
                    "permanentId": "x__$data('contextNode')/@href",
                    "continueOnError": true
                }
            },
            // 2. For web references, the URL is the representation we want to edit, so directly
            // 3. open the modal
            {
                "type": "operation/open-web-reference-modal-for-edit",
                "data": {
                    "url": "{{reference.target}}"
                }
            },
            // 4. The modal already returns a URL, so no transformation is needed except to
            // 5. Create a permanent ID for the new URL
            {
                "type": "transform/createPermanentIdForReference",
                "data": {
                    "contextNodeId": "{{contextNodeId}}",
                    "target": "{{url}}",
                    "referenceType": "web",
                    "metadata": {}
                }
            },
            // 6. Update the href attribute of the xref element with the new permanent ID
            {
                "type": "operation/set-attributes",
                "data": {
                    "contextNodeId": "{{contextNodeId}}",
                    "attributes": {
                        "href": "{{permanentId}}"
                    }
                }
            }
        ]
    }
}

Please refer to the following pages for more details on the steps used in the example:

Removing the reference

By default, the button for removing a reference uses the reference-delete operation. This operation first attempts to "unwrap" the reference element by replacing it with its children. If that does not result in a schema-valid document, the element is removed together with its descendants. This behavior is appropriate for most types of references, both inline references such as HTML a or DITA xref, as well as object-type references such as DITA link. If your schema requires a more specialized operation, you can change the operation used by setting the deleteOperationName prop in FxReferencePopover.

Additional considerations

Web references

The fontoxml-web-references add-on provides a standard WebReferencePopover for displaying the details of your web references. It also provides a modal for inserting and editing URLs (including mailto: e-mail URLs), with operations for inserting and editing:

As web references are usually absolute URLs, permanent IDs can be omitted for these references. The fontoxml-dita add-on provides operations for editing web references (using the fontoxml-web-references modal) with as well as without permanent IDs:

Cross-document references

The fontoxml-crosslink-references add-on provides a standard CrossReferencePopover for cross-document references. Using this popover, users can open a modal showing a preview of the document targeted by the reference, highlighting the targeted node (if any).

Various add-ons provide UI for selecting the target for a cross-document reference:

The fontoxml-dita add-on provides transforms that create and resolve URLs to other documents and nodes within them in accordance with the DITA standard. Note that such URLs may be relative if the target is located in the referring document. In other cases where the URL is guarenteed to be absolute, permanent IDs for cross-document references could be omitted (see the targetIsPermanentId popover data property for FxReferencePopover).

Images

Image support is included in the base platform using families such as configureAsImage (see above). The fontoxml-cms-browser add-on provides an open-image-browser-modal operation to browse for images in the CMS.

Note that the image families only support images represented as permanent IDs at this time.

DITA maps

DITA maps consist of topicref elements (and their specializations). These link to other DITA documents in much the same way as other DITA cross-document references, except that URLs must point to documents, not elements within.

The fontoxml-cms-browser add-on provides a number of modals for such references:

Use createDitaUrlFromLoadedTarget to turn the resulting document ID into a URL, then use createPermanentIdForReference to obtain a permanent ID. As DITA maps require some special processing when updated, make sure to use append-topicref to insert new topicref elements into the map.

Note that DITA map support currently requires URLs for other documents in the map to be specified as permanent IDs. When loading a DITA map, the href value for a topicref element is first resolved as a permanent ID. The resulting URL is then passed to the document GET endpoint with the map document containing the topicref as the referrer.

DITA conrefs

Use the configureAsConref family to display any conrefs in loaded documents as a read-only version of their target. To help with creating and editing conrefs, the same add-ons can be used as for cross-document references:

As with normal DITA cross-document references, use createDitaUrlFromLoadedTarget to turn the document ID and node ID returned by the browser into a URL, then use createPermanentIdForReference to obtain a permanent ID. Insert the conref using an appropriate operation, such as horizontal-insert, or edit an existing one using set-attributes to update the conref attribute.

Note that configureAsConref currently requires the conref attribute to contain a permanent reference ID.

Was this page helpful?