Create an annotation API
See original GitHub issueDo you want to request a feature or report a bug?
feature
What is the current behavior?
There is no API for annotating text.
What is the expected behavior?
To be able to create text annotations in the Gutenberg editor TinyMCE needs to have an API with which we can mark pieces of text.
The ideal API would be that TinyMCE accepts an array of annotations that it will then mark. Something like editor.addAnnotations( annotations )
. There could be extra related functions like editor.addAnnotation
, editor.removeAnnotation
, editor.removeAlllAnnotations
. An annotation should have at least the following data:
- An identifier.
- A starting XPath pointing to an element.
- A starting position within the element the XPath points to.
- An ending XPath pointing to an element.
- An ending position within the element the XPath points to.
The user can of course type inside an annotation which would change the position of the annotation. tinyMCE should provide an event that is called whenever an annotation is updated with new positions.
For example in the following scenario:
A piece of text.
|------|
The annotation starts and ends with the same element. The starting position is 5, the ending position is 13. If the text is now changed to:
A small piece of text.
|------|
6 characters have been added. This means that the internal representation of the annotation in TinyMCE should be updated to reflect that. The new starting positions are 11 and 19. An implementer needs to know about the fact that the annotation changed so it can be persisted, if relevant. This can be done using an onAnnotationChange
event.
The format I am exploring for Gutenberg right now looks like this:
{
type: 'RangeSelector',
startSelector: {
type: 'XPathSelector',
value: "/p[1]/text()[1]",
refinedBy: {
type: 'TextPositionSelector',
start: 11,
end: 11,
},
},
endSelector: {
type: 'XPathSelector',
value: '/p[1]/text()[1]',
refinedBy: {
type: 'TextPositionSelector',
start: 14,
end: 14,
},
},
}
This format is compatible with the W3C annotation standard. This means that we can use the same format for front-end annotation. I would highly recommend TinyMCE to consider using this format. If you choose not to use this format then you can refer to the 4 data points necessary for annotation at the top of this issue.
getContent
and setContent
should remain working the same way they always have. When getting content using getContent
any annotation elements created by TinyMCE should not be present. setContent
should first set the content and then apply the annotation already present to the new content.
Issue Analytics
- State:
- Created 5 years ago
- Comments:6 (3 by maintainers)
Looks like we have some work to do on the docs. Sorry about that
In the meantime, here is a fiddle that works: http://fiddle.tinymce.com/q1gaab/1