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

Annotation API #7718

Open
wants to merge 6 commits into
base: master
from

Conversation

3 participants
@atimmer
Member

atimmer commented Jul 5, 2018

Description

This PR includes an API to annotation text inside blocks. This PR on its own is mostly useful to plugin authors. This would make it possible for a feature plugin to build #3026. It also allows plugins like Jetpack or Yoast SEO to highlight certain parts of the text to make their feedback more contextual and actionable.

The best way to see this in action is combine it with this Yoast SEO PR: Yoast/wordpress-seo#10265

XPath has been chosen because it is a format that is compatible with the W3C annotation standard. This will give it future compatibility with front-end annotations. Partial XPaths can really easily be combined into a fully qualified XPath that works globally on a certain page. XPath is also the only format in the W3C annotation standard that can refer to text node. This is in contrast to the CSS selector which can't refer to text nodes.

All annotations in the editor get an annotation-text and an annotation-text-[source] class to they can be styled by the source of the annotation.

Browser compatibility

document.evaluate is not supported in all browsers, but for this version of the PR I don't use document.evaluate. I parse the XPath myself to result in a position within the data structure for rich-text.

Doesn't include, but should be added in a later iteration

  • A custom block should be able to track which RichText an annotation is for. Currently this implementation only works for block with a single RichText.
  • More data can be added to an annotation such as comment, author, etc.

How has this been tested?

Screenshots

annotation poc

Related

Commenting API: #3026.
REST API for annotations (required for Commenting API): #4685

Checklist:

  • My code is tested.
  • My code follows the WordPress code style.
  • My code follows the accessibility standards.
  • My code has proper inline documentation.

@atimmer atimmer requested review from aduth, gziolo and youknowriad Aug 3, 2018

@gziolo

This comment has been minimized.

Show comment
Hide comment
@gziolo

gziolo Aug 6, 2018

Member

It looks like we should find a good solution for making RichText extensible so this could be developed as a plugin initially to speed up things. Related issues: #3688 and #4658. /cc @iseulde

Screencast looks really nice 👍

Member

gziolo commented Aug 6, 2018

It looks like we should find a good solution for making RichText extensible so this could be developed as a plugin initially to speed up things. Related issues: #3688 and #4658. /cc @iseulde

Screencast looks really nice 👍

@gziolo

This comment has been minimized.

Show comment
Hide comment
@gziolo

gziolo Aug 22, 2018

Member

@iseulde - is there any way we could allow register custom TinyMCE plugins? It looks like this is the blocker for having annotations developed as a plugin. Another question is if we want to have it included in the core at some point.

Member

gziolo commented Aug 22, 2018

@iseulde - is there any way we could allow register custom TinyMCE plugins? It looks like this is the blocker for having annotations developed as a plugin. Another question is if we want to have it included in the core at some point.

@iseulde

This comment has been minimized.

Show comment
Hide comment
@iseulde

iseulde Aug 22, 2018

Member

With the RichText state PR (#7890) and future helpers build on that, it should no longer be necessary to do this as a TinyMCE plugin, and then it can also easily be made as a plugin for Gutenberg.

Member

iseulde commented Aug 22, 2018

With the RichText state PR (#7890) and future helpers build on that, it should no longer be necessary to do this as a TinyMCE plugin, and then it can also easily be made as a plugin for Gutenberg.

@iseulde iseulde referenced this pull request Aug 28, 2018

Merged

RichText state structure for value manipulation #7890

4 of 4 tasks complete
@atimmer

This comment has been minimized.

Show comment
Hide comment
@atimmer

atimmer Sep 12, 2018

Member

An alternative implementation of this PR can be found in the try/annotations-with-rich-text-refactor branch. That branch is based on #7890 and I've updated Yoast/wordpress-seo#10265 to work with that branch.

Whenever #7890 is merged I will make try/annotations work with the new rich text structure.

Member

atimmer commented Sep 12, 2018

An alternative implementation of this PR can be found in the try/annotations-with-rich-text-refactor branch. That branch is based on #7890 and I've updated Yoast/wordpress-seo#10265 to work with that branch.

Whenever #7890 is merged I will make try/annotations work with the new rich text structure.

@aduth aduth referenced this pull request Sep 13, 2018

Closed

Try block annotation, starting with full block annotation #3628

3 of 5 tasks complete

atimmer added some commits Sep 11, 2018

Add class to text annotations
This makes them stylable by plugins.

@atimmer atimmer changed the title from Try an annotation API to Annotation API Oct 2, 2018

Add block annotations
This has no styling because this is only API. For
text annotation the browser applies some styling already,
but for block annotation plugins can decide on styling
themselves.
@@ -436,13 +438,16 @@ export class RichText extends Component {
* the live DOM.
*/
onChange( record, _withoutApply ) {
// Filter out annotations
const filteredRecord = removeFormat( record, 'mark', 0, record.text.length );

This comment has been minimized.

@iseulde

iseulde Oct 3, 2018

Member

We should make sure the right APIs are in place so we don't have to modify RichText at all. Working on that after the Formatting API.

@iseulde

iseulde Oct 3, 2018

Member

We should make sure the right APIs are in place so we don't have to modify RichText at all. Working on that after the Formatting API.

This comment has been minimized.

@atimmer

atimmer Oct 4, 2018

Member

How do you see this working? Would you apply the annotations on the rich-text state in the the RichText withSelect method? I'm coming at it from the assumption that one should be able to pass an array of annotations to RichText and have them be rendered.

@atimmer

atimmer Oct 4, 2018

Member

How do you see this working? Would you apply the annotations on the rich-text state in the the RichText withSelect method? I'm coming at it from the assumption that one should be able to pass an array of annotations to RichText and have them be rendered.

This comment has been minimized.

@iseulde

iseulde Oct 4, 2018

Member

I'll need some more information first to understand what you want to do, which I should have asked before. Why is there formatting be stripped on every change? That seems a bit odd. I can understand that you don't want the format to be serialised, but then we should leave it away as part of the serialisation (to HTML). This also makes me think that we might benefit from having and "editor only" format, that get automatically stripped out. Maybe it can even be something different: only a node that's put in place when the DOM is created for the editor, just like the way we will make invisible character visible (non breaking space etc.) and might create inline boundaries based on the selection.

@iseulde

iseulde Oct 4, 2018

Member

I'll need some more information first to understand what you want to do, which I should have asked before. Why is there formatting be stripped on every change? That seems a bit odd. I can understand that you don't want the format to be serialised, but then we should leave it away as part of the serialisation (to HTML). This also makes me think that we might benefit from having and "editor only" format, that get automatically stripped out. Maybe it can even be something different: only a node that's put in place when the DOM is created for the editor, just like the way we will make invisible character visible (non breaking space etc.) and might create inline boundaries based on the selection.

This comment has been minimized.

@atimmer

atimmer Oct 4, 2018

Member

I opted for not having the formatting for annotations in the state of the editor, because that would mean that they would end up in the attributes of blocks. And I don't think they are actually part of the blocks. The use-cases of marking something up is always a meta concern:

  • Spellchecking
  • Editorial highlighting
  • Highlighting pieces of text for writing assistance

Putting these into the attributes of a block would muddy the actual content of a block.

What I can see is another abstraction underneath RichText that handles 'formatting that isn't in the state'. Which annotations could be one use-case of. I don't have any other use-cases for such an abstraction though, so I opted for the simplest solution.

@atimmer

atimmer Oct 4, 2018

Member

I opted for not having the formatting for annotations in the state of the editor, because that would mean that they would end up in the attributes of blocks. And I don't think they are actually part of the blocks. The use-cases of marking something up is always a meta concern:

  • Spellchecking
  • Editorial highlighting
  • Highlighting pieces of text for writing assistance

Putting these into the attributes of a block would muddy the actual content of a block.

What I can see is another abstraction underneath RichText that handles 'formatting that isn't in the state'. Which annotations could be one use-case of. I don't have any other use-cases for such an abstraction though, so I opted for the simplest solution.

Show outdated Hide outdated packages/rich-text/src/xpath.js Outdated

atimmer added some commits Oct 4, 2018

@iseulde

This comment has been minimized.

Show comment
Hide comment
@iseulde

iseulde Oct 4, 2018

Member

Could you write some docs as part of this PR that explain how to use the annotations API?

It is not possible to have overlapping annotations.

Could you elaborate? Why not?

Member

iseulde commented Oct 4, 2018

Could you write some docs as part of this PR that explain how to use the annotations API?

It is not possible to have overlapping annotations.

Could you elaborate? Why not?

@atimmer

This comment has been minimized.

Show comment
Hide comment
@atimmer

atimmer Oct 4, 2018

Member

Could you elaborate? Why not?

Because of the new RichText structure this is no longer the case. The TinyMCE plugin that I used for matching XPaths couldn't do it (yet).

Could you write some docs as part of this PR that explain how to use the annotations API?

Will do.

Member

atimmer commented Oct 4, 2018

Could you elaborate? Why not?

Because of the new RichText structure this is no longer the case. The TinyMCE plugin that I used for matching XPaths couldn't do it (yet).

Could you write some docs as part of this PR that explain how to use the annotations API?

Will do.

@gziolo gziolo added this to the 4.1 milestone Oct 10, 2018

@gziolo

This comment has been minimized.

Show comment
Hide comment
@gziolo

gziolo Oct 10, 2018

Member

I'm adding this PR to 4.1 milestone to ensure it is included early in the process. As discussed during JS weekly chat yesterday, it depends on #10068 which @iseulde is going to work on as soon as 4.0-RC is out. Those two task depend on each other, so let's make sure we shape formatting API for RichText in a way which makes this PR work :)

Member

gziolo commented Oct 10, 2018

I'm adding this PR to 4.1 milestone to ensure it is included early in the process. As discussed during JS weekly chat yesterday, it depends on #10068 which @iseulde is going to work on as soon as 4.0-RC is out. Those two task depend on each other, so let's make sure we shape formatting API for RichText in a way which makes this PR work :)

@gziolo

This comment has been minimized.

Show comment
Hide comment
@gziolo

gziolo Oct 10, 2018

Member

There is work in progress PR for formatting API #10209, @atimmer we would love to hear your feedback early on 🙇

Member

gziolo commented Oct 10, 2018

There is work in progress PR for formatting API #10209, @atimmer we would love to hear your feedback early on 🙇

@gziolo gziolo removed this from the 4.1 milestone Oct 15, 2018

@gziolo gziolo added this to the 4.2 milestone Oct 15, 2018

@gziolo

This comment has been minimized.

Show comment
Hide comment
@gziolo

gziolo Oct 15, 2018

Member

I'm moving it to 4.2 as we decided that 4.1 should be UI freeze focused. 4.2 is planned to be focused on API freeze and this PR fits perfectly to that description :)

Member

gziolo commented Oct 15, 2018

I'm moving it to 4.2 as we decided that 4.1 should be UI freeze focused. 4.2 is planned to be focused on API freeze and this PR fits perfectly to that description :)

@gziolo gziolo added this to In Progress in API freeze via automation Oct 22, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment