Setup

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.

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

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:

• documents: Document[]
• options?: SetDocumentsRequestOptions

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

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.

useUnsetDocumentId();

const { client } = useVeltClient();

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

​

Unset Multiple Documents

• Use this to unsubscribe from all documents at once.

useUnsetDocuments();

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.

{/* 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'
});

{/* 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'
});