Element Metadata

Get and Set Element Metadata

Add-ons can store private metadata (custom data accessible only to the add-on that set it) on any node within the Express document. Currently, each node can hold up to 3 KB of data, organized as key/value pairs where both keys and values are Strings. Additionally, there is a limit of 20 key/value pairs per node.

All nodes that inherit from the BaseNode class have a addOnData property that can be used to store and retrieve metadata. It is an instance of the AddOnData class, which provides methods to perform operations such as getItem(), setItem(), removeItem(), and clear().

With the remainingQuota property, you can check how much space is left, both in terms of sizeInBytes and numKeys, while keys() returns an array of the keys in use.

Example

Copy
import { editor } from "express-document-sdk";

// Create some dummy node
const text = editor.createText();
text.fullContent.text = "Hello, World!";

// Store some metadata as key/value pairs
text.addOnData.setItem("originalText", "Hello, World!");
text.addOnData.setItem("date", new Date().toISOString());

// Retrieve the metadata
console.log("Original text: ", text.addOnData.getItem("originalText"));

// Check the remaining quota
console.log("Remaining quota: ", text.addOnData.remainingQuota);
// {
//   "sizeInBytes": 3062,
//   "numKeys": 19
// }

// Check the keys in use
console.log("Keys in use: ", text.addOnData.keys());
// ["originalText", "date"]

// Remove the metadata
text.addOnData.removeItem("originalText");

// clear all metadata
text.addOnData.clear();
Copied to your clipboard
import { editor } from "express-document-sdk";

// Create some dummy node
const text = editor.createText();
text.fullContent.text = "Hello, World!";

// Store some metadata as key/value pairs
text.addOnData.setItem("originalText", "Hello, World!");
text.addOnData.setItem("date", new Date().toISOString());

// Retrieve the metadata
console.log("Original text: ", text.addOnData.getItem("originalText"));

// Check the remaining quota
console.log("Remaining quota: ", text.addOnData.remainingQuota);
// {
//   "sizeInBytes": 3062,
//   "numKeys": 19
// }

// Check the keys in use
console.log("Keys in use: ", text.addOnData.keys());
// ["originalText", "date"]

// Remove the metadata
text.addOnData.removeItem("originalText");

// clear all metadata
text.addOnData.clear();

Please note that the addOnData property is iterable with for...of loops, so you can use it to iterate over the key/value pairs; each pair is an array with the key as the first element and the value as the second.

Copy
// iterate over key/value pairs
for (let pair of text.addOnData) {
  console.log(pair);
  // ['originalText', 'Hello, World!']
  // ['date', '2025-01-20T11:06:19.051Z']
}
Copied to your clipboard
// iterate over key/value pairs
for (let pair of text.addOnData) {
  console.log(pair);
  // ['originalText', 'Hello, World!']
  // ['date', '2025-01-20T11:06:19.051Z']
}

Alternatively, you can use the keys() method to get an array of all keys and then iterate over them.

Copy
// Iterate over all keys
text.addOnData.keys().forEach((key) => {
  console.log(`Key: ${key}, Value: ${text.addOnData.getItem(key)}`);
});
Copied to your clipboard
// Iterate over all keys
text.addOnData.keys().forEach((key) => {
  console.log(`Key: ${key}, Value: ${text.addOnData.getItem(key)}`);
});

Use Cases

Per-element metadata can be useful to keep track, for example, of the original properties a node has been created with, the history of the subsequent changes made to it, or to tag some nodes in a way that is meaningful for the add-on (e.g., it's supposed to be skipped when a certain routine is launched). It can also be used to store temporary data that is not meant to be persisted.

Please, refer to the SDK Reference section for AddOnData for a complete list of methods, and the per-element-metadata sample add-on for a demonstrative implementation.

Last updated 3/6/2025

Was this helpful?

Yes

No