DocumentReference

How to get DocumentReference

ES2015+:

import DocumentReference from 'fontoxml-documents/DocumentReference'

ES5:

define([
	'fontoxml-documents/DocumentReference'
], function (
	DocumentReference
) {
});

Type: Class

A DocumentReference represents a reference to a document. The precise identity of the target document may not be known. This allows it to represent references to external content or those which reference content for which the identity is only known after loading (e.g., documents referenced by their relative path).

A document can either be referenced directly by its remote document ID, or indirectly using a potentially relative URL and the remote document ID of the referrer.

Constructor

# Name Type Description
1. [sourceDocumentId] DocumentId | Null
2. [sourceNodeId] NodeId | Null

Properties

Name Type Description
documentId DocumentId | Null

If the document this reference refers to is loaded, this is set to the corresponding document ID.

error Error | Null

A DocumentReference can be in an error state in a number of ways:

  • An error may have been encountered after the document was loaded, in which case the documentId property is set but the document is no longer available.

  • An error may have been encountered during loading, in which case only the remoteDocumentId or relativeUrl and referrerId properties have been set.

  • The reference itself may be erroneous, in which case this error property will be set.

The getLoadingStateForDocumentReference function can be used to obtain the error that may have occurred in any of these cases.

isVisible Boolean

Can be used to hide referenced documents from the editor.

This may be set to false, for instance, to include resource documents that are part of a project but are not editable directly.

referrerId RemoteDocumentId | Null

In case the reference refers to a potentially relative ID with respect to a referrer document, this is the remote document ID of the referrer document.

relativeUrl RemoteDocumentId | String | Null

In case the reference refers to a potentially relative ID with respect to a referrer document, this is the ID or URL being targeted.

remoteDocumentId RemoteDocumentId | Null

In case the reference refers to an absolute remote document ID, this is that ID.

sourceDocumentId DocumentId | Null

If the reference originates from another loaded document, this is set to the document ID of that document.

sourceNodeId DocumentId | Null

If the reference originates from another loaded document, this is set to the node ID of the node representing the reference in that document.

traversalRootNodeId NodeId | Null

If the document this reference refers to is loaded and this reference references a part of the document, this is set to the corresponding node ID. If set to null, the document is either not loaded or the reference references the root of the document.

Methods

Name Description
getSourceNode

Returns the source node, that is, the node that represents the reference itself, or null if there is no such node.


  Returns

Type: Node | Null

getTraversalRootNode

Returns the traversal root node, representing the target of the reference.

If the reference refers to the root of the document, its Document node is returned. If the target document is not loaded, this returns null.


  Returns

Type: Node | Null

isLoaded

Returns whether the target document is currently loaded.


  Returns

Type: Boolean

setError

Mark the reference as erroneous. This will clear any instance set, so the targeted document will no longer be visualized under this reference.

This should only be used in cases where the reference itself is erroneous. Errors in the targeted document are handled in the DocumentsManager, and loading errors are handled by the DocumentLoader.


  Arguments
# Name Type Description
1. error Error
  Related links
setInstance

Should be called with the document instance ID when the document targeted by the reference is loaded in the DocumentsManager, and with null as soon as it is unloaded.


  Arguments
# Name Type Description
1. documentId DocumentId | Null

Set to null to mark the document reference as not loaded anymore

2. [traversalRootNodeId] NodeId

Defaults to the document node

setRelatedDocumentTarget

Set the target of the document reference to a related document. The setTarget method should be called to make the reference absolute once its ID is known.


  Arguments
# Name Type Description
1. relativeUrl String
2. referrerId RemoteDocumentId
setTarget

Should be called when the absolute remote ID of the document targeted by the reference is known. It does not need to have an instance currently loaded in the documents manager.


  Arguments
# Name Type Description
1. remoteDocumentId RemoteDocumentId