-
-
Notifications
You must be signed in to change notification settings - Fork 3.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Allow for storing additional data related to roots #13395
Comments
Some final decisions to be made regarding the API. Do you have an opinion on naming for "additional data" and APIs related with it? We've been talking about root attributes, but currently I call it
Another proposal is One problem with With Some of the API proposals: writer.setRootMetadata( key: string, value: unknown, root: RootElement );
editor.getMetadata(); // -> { rootA: { ... }, rootB: { ... } } or .`getMetadata( rootName: string )` as with `getData()`
Editor.create( ..., { metadata: { rootA: { ... }, rootB: { ... } } } );
Editor.create( ..., { metadata: { ... } } ); // Single root version. |
Reposting my comment from Slack:
|
What worries me here is:
It’d IMO look better if metadata would be only visible on the editor level. If they didn’t leak anyhow to the writer. Then, we would have data and the accompanying metadata. Do you think there’s an option to rething what we have in the writer?Another problem I can see: when looking at the editor intereface, there’s data and then there’s metadata. If you saw it for the first time would you expect comments or track changes information to be metadata? I’m afraid so. Is this mechanism (on the editor layer) capable of becoming a store for comments too? I remember you were thinking about the future applications of metadata and how the editor interface could look like. That’s where I’d move back for a moment. |
TL;DR: Let's move the API to multi-root editor, and change as few things in engine and core as possible. If possible, make changes only in Fantastic, a two opposite opinions on where it should go ;). Let's first clarify, that the changes must go through the model, so they are:
In the end, metadata is kind of data, just stored in a different way. Thankfully, this is a part where we all agree (as I clarified with @Reinmar in F2F talk). The question is: do we know everything about metadata? What kind of uses for it can we imagine? Do we think there are more requirements we can learn and how probably it is that it can evolve in a "breaking" way? Here, I have to admit to @Reinmar that we do not have the whole data gathered. We focused on multi-root uses, with some very strict use cases, like section editing. It may be risky to introduce it heavily on the engine/core side as this might mean more breaking changes in the future. I personally think that root attributes -- or maybe general data stored synchronized between remote clients -- will be beneficial even for "single root" editors, and something that we may want to have. But I don't have good examples on hand. Instead, it will be better to focus on multi-root use cases. This means that it will be better to keep as much of the API as possible in multi-root editor. If breaking change happens (e.g. we will introduce a similar (but different) general scenario and what is proposed here will be obsolete) then it will concern smaller audience. Now, answering some of your questions:
And you are correct. But it has the same reason to be on I think that what confuses you and why you don't like it is because we don't have any official plugins using it. I can imagine this may change if we want to explore "section editing space" more and propose some own solutions.
Yes, and I don't have a great idea how to communicate it in a better way other than just have good docs (and examples). As I wrote, it is a problem that you don't know when you should be interested in saving this metadata.
Not in its current form, where metadata is related to roots.
I... don't remember it exactly :D, not sure if I had some concrete ideas :D. |
New proposal (in PR):
This way we have:
Example usage: MultiRootEditor.create( ..., {
rootAttributes: {
rootId1: { order: 10, ownerId: 'userId' },
rootId2: { order: 20, ownerId: null }
}
} ).then( editor => {
editor.model.document.getRoot( 'rootId1' ).getAttribute( 'order' ); // 10.
editor.model.document.getRoot( 'rootId2' ).hasAttribute( 'ownerId' ); // false.
} ); editor.model.change( writer => {
const root = editor.model.document.getRoot( 'rootId2' );
writer.setAttribute( 'order', 0, root );
} ); editor.model.document.on( 'change:data', () => {
for ( const change of editor.model.document.differ.getChangedRoots() ) {
if ( change.attributes && change.attributes.order ) {
const root = editor.model.document.getRoot( change.name );
// ...
}
}
} ); editor.getRootsAttributes();
/*
{
rootId1: { order: 10, ownerId: 'userId' },
rootId2: { order: 0, ownerId: null }
}
*/ |
Why do they have to init attributes with Also, it sounds like it applies e.g. to HTMLComments too. So I guess I misunderstood something. |
Since Unless, of course, at that point, we introduce something like
HTML comments feature uses roots attributes without any changes. Attributes used by that feature will not be available in |
Other (engine): `RootAttributeOperation` is now correctly handled by `Differ`. Root attribute changes will be returned in `Differ#getChangedRoots()`. Internal (editor-multi-root): Introduced API to easily save and load root attributes. Introduced `EditorConfig#rootsAttributes` and `MultiRootEditor#getRootsAttributes()`. Closes #13395. Internal (editor-multi-root): Introduced `MultiRootEditor#getFullData()`. The method returns document data for all roots in multi-root editor. Internal (editor-multi-root): `MultiRootEditor#addRoot()` has a new option `attributes`. Internal (engine): `model.Writer#detachRoot()` will now remove attributes from the detached root.
📝 Provide a description of the new feature
Allow for storing additional data related to roots. We already have
RootAttributeOperation
and it is possible to set an attribute on a root element usingwriter.setAttribute()
. However it is hard to use them outside of the editing pipeline. There's no simple API that would allow to store "metadata" that is connected with the document but is not the document data itself.This is especially important for applications that might want to use multi-root editors. If an application "document" is built from multiple, separated editing areas, it is common that these editing areas may also have their own properties that can be changed by users as they edit the document.
It should be possible to easily save and load such additional data and it also should be propagated in real-time collaborative editing.
The text was updated successfully, but these errors were encountered: