question-mark
Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Create an annotation API

See original GitHub issue

Do 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:closed
  • Created 5 years ago
  • Comments:6 (3 by maintainers)

github_iconTop GitHub Comments

1reaction
androbcommented, Oct 3, 2018

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

0reactions
Lewiscowles1986commented, Oct 1, 2018

annotator-err

Read more comments on GitHub >

github_iconTop Results From Across the Web

Create Annotations
... Annotations API, Overview, Retrieve Annotations, List Annotations, Get Annotation, Create Annotations, Create Annotations, Patch Annotation ...
Read more >
Developer - Integration API - Getting Started - Annotate
This guide covers the essentials of the Annotate API. It demonstrates how to create a workspace, upload a document to it, create user...
Read more >
Create an annotation set | Vertex AI - Google Cloud
Create a new annotation set · In the Google Cloud console, go to the Vertex AI Datasets page. · Click the dataset that...
Read more >
Annotations API | Europeana Pro
The Annotations API is an extension to the Europeana REST API which allows you to create, retrieve and manage annotations on Europeana objects....
Read more >
Create an annotation - Akamai TechDocs
Create a new annotation from an external application.
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Dev.to Post

No results found

github_iconTop Related Hashnode Post

No results found