Skip to content
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 host page to restrict which parts of the page can be annotated #5507

Open
robertknight opened this issue Jun 2, 2023 · 1 comment
Open

Comments

@robertknight
Copy link
Member

robertknight commented Jun 2, 2023

In the context of video transcript annotation, we want some way to constrain annotation to the transcript.

A possible solution is some generic mechanism which allows the page embedding Hypothesis to control which element(s) can be annotated. Some ideas for API:

1. Configuration option

Add a configuration option to the client which specifies element(s) that can be annotated. The configuration should support a serializable representation of the element (eg. CSS selector, element ID), for cases where the configuration is injected as JSON.

For example:

{
  "contentRoot": "#some-container"
}

Or:

{
  "contentElements": ["#container-a", "#container-b"]
}

2. DOM event

Dispatch a DOM event prior to showing the adder, which the host page can intercept to prevent annotation or modify the annotated range. Example of how the host page might achieve this:

document.body.addEventListener('hypothesis:beforeannotate', event => {
  // Modify `event.range` to alter the annotated range, or
  // `event.preventDefault()` to prevent annotation of this region
});

3. JS API

Expose a JavaScript API which allows the host page to interact with the client after it loads and configure behavior like this. We don't currently have any such API in place.

// TBD - How does the host page get the `hypothesisClient` object.
// As a property of a DOM event after the client loads, or via a callback specified
// in client configuration?

// Restrict annotation to `someElement`
hypothesisClient.setContentElements([someElement]);
@robertknight
Copy link
Member Author

robertknight commented Jun 2, 2023

Pros of static configuration:

  • Easier to specify, especially for less technically adept page authors
  • Easier to reason about for debugging

Pros of dynamic APIs:

  • Allows changing the annotatable regions over time without reloading the client
  • More flexible

For the use case in the video player, I believe static configuration will be adequate.

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

No branches or pull requests

1 participant