hypothesis / hypothesis/client
Allow host page to restrict which parts of the page can be annotated
- 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.