Google Git
Sign in
chromium / chromium / src / d1cee5d400e8ee4575652be8d3d9bf6d9eac7732 / . / third_party / blink / renderer / core / annotation
tree: 42daf9f7c54da01d84d525e4ad94d3b1efc92d3e [path history] [tgz]
  1. annotation_agent_container_impl.cc
  2. annotation_agent_container_impl.h
  3. annotation_agent_container_impl_test.cc
  4. annotation_agent_impl.cc
  5. annotation_agent_impl.h
  6. annotation_agent_impl_test.cc
  7. annotation_selector.cc
  8. annotation_selector.h
  9. annotation_test_utils.h
  10. build.gni
  11. OWNERS
  12. README.md
  13. text_annotation_selector.cc
  14. text_annotation_selector.h
third_party/blink/renderer/core/annotation/README.md

Annotation

Rendered

The core/annotation directory contains the implementation of Blink web content annotations.

This component allows Blink features and embedders to attach annotations to content in a page rendered by Blink. It provides support only for attachment and interaction with markers in the web content. The actual data and rendering of any annotation content (e.g. the text of a user note) is not in scope for this component and must be implemented by the embedder.

On a feature level, core/annotation provides:

  • Selectors - a way for a client to specify which part of the DOM an annotation should be attached to. E.g. “The text string ‘brown dog’ prefixed by ‘The quick’ and suffixed by ‘jumped over’”.
  • In-page markers of the content that an annotation is attached to (e.g. highlight annotated text).
  • User interaction with annotation markers - e.g. providing notification to client when a marker is clicked or invokes the context menu.
  • Client interaction with annotation markers - e.g. scroll marker into view, get notified when marked content is removed from DOM or changes.

Use Cases

Current consumers of core/annotation are:

Concepts

  • Annotation: in a very general sense, content added to a page that is not part of the Document as authored by its creator. Examples might include: users attaching notes to images or text snippets, making highlights or attaching reactions/emojis, users or services attaching metadata like “time to read” or ratings, etc.

  • Annotation Agent: An object in Blink used to support annotating content. An agent does not implement any kind of annotation content or semantics; it provides a means by which a client implementing some form of annotation can attach itself to specific content in a page, mark/highlight it, and provides the client with functionality and notifications to interact with the attachment.

  • Agent Container: Every agent is created by and stored in a container. When removed, the agent is disposed and all its effects (e.g. highlights) are removed. Containers are owned by a Document and created lazily on demand. Clients interact with annotation agents via the container; that is, by binding to the AnnotationAgentContainer mojo interface and requesting new AnnotationAgents from it.

  • Selector: A selector is used to attach an annotation to some content in a page. A selector has enough information to uniquely identify an intended instance of content on a page, for example, a text selector might include the snippet of text a note is attached to with some prefix/suffix context to disambiguate that snippet from other instances of the same text.

  • Attachment: Is the process by which an agent invokes a selector to find a range of DOM that matches the selector's parameters. If such a range is found, the agent is considered attached. Attachment may fail, for example, if the text of the page has changed since the annotation was created and no longer exists. In this case, the agent is unattached.

Design

TODO(bokan)