hypothesis / hypothesis/client

Allow host page to restrict which parts of the page can be annotated

Open
#5,507 1 comment 0 reactions 0 assignees View on GitHub
project: video annotations
Dominant language
Mustache
Stars
730
Forks
224
PR merge metrics
No merged PRs in 30d

Description

In the context of video transcript annotation, we want some way to [constrain annotation to the transcript](https://github.com/hypothesis/via/issues/940).

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:

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

Or:

```json
{
"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:

```js
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.

```js
// 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]);
```

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.