createPermanentIdForReference

How to get createPermanentIdForReference

Depend on fontoxml-references to make this transform available.

Ask the CMS to create a permanent identifier for a given reference.

Interpreting a reference in an XML document may depend on the context document. This makes it hard to move such references between documents (e.g., using copy/paste). To solve this, Fonto uses the CMS to create permanent identifiers for any reference in the document, to turn them into a context-free representation.

This transform is used to create a new permanent ID for a given reference. A reference is normally resolved from a permanent ID using transform/retrieveReferenceFromPermanentId or ReferencesManager#retrieve.

As this involves CMS communication, the permanent ID is only created when the operation containing the transform is executed. When getting the state of such an operation, this transform returns a fake placeholder ID, which should allow subsequent steps to compute their state correctly.

Creating a permanent ID requires specifying the referrer document. This can be specified as either referrerDocumentId or contextNodeId operation data. If neither is provided, the current focused document is used as the referrer.

The CMS contract for creating a reference, POST /reference/create, includes a referenceType parameter. In previous releases of Fonto this was required to detect the type of a reference. While the type is no longer used for this purpose, it is still required to create a permanent ID. Ask your CMS provider which type should be used.

Finally, references can be assigned arbitrary metadata at the time of creation. This metadata will be available when the reference is retrieved, and may be extended by the CMS, e.g., to provide additional details about the target.

Example:

"insert-image": {
  "label": "Insert image",
   "steps": [
      {
        "type": "operation/open-image-browser-modal"
      },
      {
        "type": "transform/createPermanentIdForReference",
        "data": {
          "target": "{{selectedImageId}}",
          "referenceType": "image",
          "metadata": {}
        }
      },
      {
        "type": "operation/vertical-insert",
        "data": {
          "childNodeStructure": [
            "img",
            {
              "src": "{{permanentId}}"
            }
          ]
        }
      }
   ]
}

The result of this example would be an <img /> element of which the @src attribute is set to an identifier determined by the CMS, and linked to an asset identifier or other.

Imported operation data

Name Type Description
[contextNodeId] NodeId
metadata Object
referenceType String
[referrerDocumentId] DocumentId
target String

Exported operation data

Name Type Description
permanentId String