A Document represents a shared collaborative space where users can interact. Documents live inside the Organization.

Documents contain:

  • All feature data (e.g., Comments, Presence, Cursors, etc.).
  • Locations
  • Users: These are different from Organization Users. (more details in Access Control section)

Users logged into the same Document ID can see each other’s Presence, Cursors, Comments etc.

For example, in a slide presentation application, the entire slide deck is a document.

​
Set a Single Document

  • Use this to initialize and subscribe to a single Document.
  • Once you set the document, you will start receiving realtime updates from the document.
  • Params:
    • documentId: The unique identifier for the document.
    • metadata: (optional) This is a key/value pair object where you can set metadata about the document such as documentName. documentName is a special field that we use to display the document name in some Velt Components.

Using Hooks:

useSetDocument('unique-document-id', {documentName: 'Document Name'});

Using API:

const { client } = useVeltClient();

useEffect(() => {
    if (client) {
        client.setDocument('unique-document-id', {documentName: 'Document Name'});
    }
}, [client]);

​
Set Multiple Documents

  • Use this to set and subscribe to multiple documents at the same time.
  • You can specify 30 documents at a time.
  • The first document in the list will be considered as the root document.
  • For features like comments, notifications, recorder, reactions etc. you will be able to read and write to multiple documents at the same time.
  • For features like cursors, presence, huddle, live state sync etc. it will default to the root document.
  • Sidebar will automatically show data from all the documents.

Params:

Using Hooks:

const documents = [
  {
    id: 'document-1',
    metadata: {
      documentName: 'Document 1'
    }
  },
  {
    id: 'document-2',
    metadata: {
      documentName: 'Document 2'
    }
  }
];
const { setDocuments } = useSetDocuments();
setDocuments(documents);

Using API:

const documents = [
  {
    id: 'document-1',
    metadata: {
      documentName: 'Document 1'
    }
  },
  {
    id: 'document-2',
    metadata: {
      documentName: 'Document 2'
    }
  }
];
client.setDocuments(documents);

​
Read/Write data from multiple documents on the same page

  • If you want to display data (eg: comments) from multiple documents on the same page, add data-velt-document-id attribute to the container that contains the document.
  • It will be used to identify which part of the DOM belongs to which document.
<div class="document-container" data-velt-document-id="document-1">
  ...
</div>

<div class="document-container" data-velt-document-id="document-2">
  ...
</div>

<div class="document-container" data-velt-document-id="document-3">
  ...
</div>

​
Unset a Single Document

  • Use this to unsubscribe from the root Document
  • Once you unset the document, you will no longer receive realtime updates from the document.
  • For some parts of your app, you may not need Velt. In such cases, you can unset the document.

Using Hooks:

useUnsetDocumentId();

Using API:

const { client } = useVeltClient();

useEffect(() => {
    if (client) {
        client.unsetDocumentId();
    }
}, [client]);

​
Unset Multiple Documents

  • Use this to unsubscribe from all documents at once.

Using Hooks:

useUnsetDocuments();

Using API:

const { client } = useVeltClient();

useEffect(() => {
    if (client) {
        client.unsetDocuments();
    }
}, [client]);

​
Get Document Metadata

  • Use this to get the metadata of a Document.
  • This is useful when you want to display the document name in your app or any custom metadata that you have set.
  • This returns a subscription with DocumentMetadata object.
const { client } = useVeltClient();

useEffect(() => {
    if (client) {
        client.getDocumentMetadata().subscribe((documentMetadata) => {
            console.log("Current document metadata: ", documentMetadata);
        });
    }
}, [client]);

​
Access Documents from Other Organizations

  • By default, users can only access documents within their own organization.
  • Enable cross-organization access by specifying the organizationId of the target document in the document metadata.
  • Ensure that the user has access to the target document in the target organization.

Using Hook:

{/* Single Document */}
useSetDocument("DOCUMENT_ID", {
  organizationId: 'ANOTHER_ORGANIZATION_ID'
});

{/* Multiple Documents */}
const documents = [
  {
    id: 'document-1',
    metadata: {
      documentName: 'Document 1'
    }
  },
  {
    id: 'document-2',
    metadata: {
      documentName: 'Document 2'
    }
  }
];
useSetDocuments(documents, {
  organizationId: 'ANOTHER_ORGANIZATION_ID'
});

Using API:

{/* Single Document */}
client.setDocument("DOCUMENT_ID", {
  organizationId: 'ANOTHER_ORGANIZATION_ID'
});

{/* Multiple Documents */}
const documents = [
  {
    id: 'document-1',
    metadata: {
      documentName: 'Document 1'
    }
  },
  {
    id: 'document-2',
    metadata: {
      documentName: 'Document 2'
    }
  }
];
client.setDocuments(documents, {
  organizationId: 'ANOTHER_ORGANIZATION_ID'
});