├── src
    └── index.js
├── webpack.config.js
├── package.json
└── README.md


/src/index.js:
--------------------------------------------------------------------------------
1 | module.exports.TextQuoteAnchor = require ('dom-anchor-text-quote'),
2 | module.exports.TextPositionAnchor = require ('dom-anchor-text-position')
3 | module.exports.WrapRangeText = require ('wrap-range-text')
4 | 


--------------------------------------------------------------------------------
/webpack.config.js:
--------------------------------------------------------------------------------
 1 | var path = require('path')
 2 | 
 3 | module.exports = {
 4 |   mode: "development",
 5 |   entry: './src/index.js',
 6 |   output: {
 7 |     path: path.join(__dirname, '.'),
 8 |     filename: './dist/standalone-anchoring.js',
 9 |     library: 'anchoring',
10 |   },
11 | };


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "standalone-anchoring",
 3 |   "version": "0.1.0",
 4 |   "description": "Encapsulate dom-anchor-text-quote, dom-anchor-text-position, and wrap-range-text for use in browser scripts",
 5 |   "main": "index.js",
 6 |   "author": "Jon Udell <judell@hypothes.is>",
 7 |   "dependencies": {
 8 |     "dom-anchor-text-quote": "^4.0.2",
 9 |     "wrap-range-text": "^1.0.1"
10 |   }
11 | }
12 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # TextQuoteAndPosition
 2 | 
 3 | ## Purpose
 4 | 
 5 | Hypothesis uses two modules, https://www.npmjs.com/package/dom-anchor-text-position and https://www.npmjs.com/package/dom-anchor-text-quote, to convert between DOM ranges and annotation selectors.
 6 | 
 7 | This repo packages those modules for standalone use in the browser. They are exported as `anchoring.TextQuoteAnchor` and `anchoring.TextPositionSelector`. 
 8 | 
 9 | It also exports https://www.npmjs.com/package/wrap-range-text, as `anchoring.WrapRangeText`, in order to wrap highlights around annotation targets.
10 | 
11 | ## Requirements
12 | 
13 | yarn
14 | 
15 | webpack
16 | 
17 | ## Build
18 | 
19 | Run `yarn` to install dependencies
20 | 
21 | Run `webpack` to build `dist\standalone-anchoring.js`
22 | 
23 | ## Use
24 | 
25 | ### To convert a selection in a web page into the same selectors included in the payload when the Hypothesis client creates an annotation.
26 | 
27 | Visit a web page. 
28 | 
29 | In a browser console, paste these lines to load the module.
30 | 
31 | ```
32 | s = document.createElement('script')
33 | s.src = 'https://jonudell.info/hlib/standalone-anchoring.js'
34 | document.body.appendChild(s)
35 | ```
36 | 
37 | Now make a selection in the page, then paste these lines into the console:
38 | 
39 | ```
40 | range = getSelection().getRangeAt(0)
41 | quoteSelector = anchoring.TextQuoteAnchor.fromRange(document.body, range)
42 | positionSelector = anchoring.TextPositionAnchor.fromRange(document.body, range)
43 | ```
44 | 
45 | And inspect the values of the selectors:
46 | 
47 | positionSelector: {start: 51, end: 72}
48 | 
49 | quoteSelector: {exact: "illustrative examples", prefix: "n↵    This domain is for use in ", suffix: " in documents. You may use this↵"}
50 | 
51 | ### To do the reverse: anchor to a target using selectors in a Hypothesis annotation.
52 | 
53 | The target for the example above is the exact phrase "illustrative examples" on the web page example.com. 
54 | 
55 | Visit http://example.com
56 | 
57 | In a browser console, paste these lines to load the module.
58 | 
59 | ```
60 | s = document.createElement('script')
61 | s.src = 'https://jonudell.info/hlib/standalone-anchoring.js'
62 | document.body.appendChild(s)
63 | ```
64 | 
65 | Assume we've retrieved an annotation from the Hypothesis service. The TextQuoteSelector in its JSON payload may have been created programmatically, as above, or by using the Hypothesis client. 
66 | 
67 | Its value is as shown below.
68 | 
69 | Paste these lines to anchor the annotation by painting a highlight.
70 | 
71 | ```
72 | exact = 'illustrative examples'
73 | prefix = '\n    This domain is for use in '
74 | range = anchoring.TextQuoteAnchor.toRange(document.body, {"exact":exact,"prefix":prefix})
75 | highlight = document.createElement('mark')
76 | anchoring.WrapRangeText(highlight, range)
77 | ```
78 | 
79 | The phrase "illustrative examples" should be highlighted.
80 | 


--------------------------------------------------------------------------------