This is an automated email from the ASF dual-hosted git repository.
gerben pushed a commit to branch asf-site
in repository
https://gitbox.apache.org/repos/asf/incubator-annotator-website.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 3f47d73 Add note&workaround for issue #112 in 'Getting Started'
3f47d73 is described below
commit 3f47d73101c0585201358319f243daeed9f9465a
Author: Gerben <[email protected]>
AuthorDate: Fri Jun 25 18:56:52 2021 +0200
Add note&workaround for issue #112 in 'Getting Started'
---
content/docs/getting-started/index.html | 2 +-
src/docs/getting-started.md | 10 +++++++---
2 files changed, 8 insertions(+), 4 deletions(-)
diff --git a/content/docs/getting-started/index.html
b/content/docs/getting-started/index.html
index 17dd36b..7cbc8da 100644
--- a/content/docs/getting-started/index.html
+++ b/content/docs/getting-started/index.html
@@ -86,7 +86,7 @@
<pre class="language-json"><code class="language-json"><span class="token
punctuation">{</span><br> type<span class="token operator">:</span>
'TextQuoteSelector'<span class="token punctuation">,</span><br> exact<span
class="token operator">:</span> 'ipsum'<span class="token
punctuation">,</span><br> prefix<span class="token operator">:</span> 'Lorem
'<span class="token punctuation">,</span><br> suffix<span class="token
operator">:</span> ' dolor'<br><span class="token punctuation">}< [...]
<p>The <em>prefix</em> and <em>suffix</em> attributes are there to know which
of multiple occurrences of <em>“ipsum”</em> the Selector points to. They will
include just enough surrounding words to make the selector unambiguous.</p>
<p>Next, we define roughly the inverse function: given a TextQuoteSelector, we
highlight the text it points to.</p>
-<pre class="language-js"><code class="language-js"><span class="token
keyword">import</span> <span class="token punctuation">{</span>
createTextQuoteSelectorMatcher<span class="token punctuation">,</span>
highlightText <span class="token punctuation">}</span> <span class="token
keyword">from</span> <span class="token
string">'@apache-annotator/dom'</span><span class="token
punctuation">;</span><br><br><span class="token keyword">async</span> <span
class="token keyword">function</span> <s [...]
+<pre class="language-js"><code class="language-js"><span class="token
keyword">import</span> <span class="token punctuation">{</span>
createTextQuoteSelectorMatcher<span class="token punctuation">,</span>
highlightText <span class="token punctuation">}</span> <span class="token
keyword">from</span> <span class="token
string">'@apache-annotator/dom'</span><span class="token
punctuation">;</span><br><br><span class="token keyword">async</span> <span
class="token keyword">function</span> <s [...]
<p>As the <a
href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of";><code>for
await … of</code></a> statement suggests, the matcher does not return just one
match, but a stream (an async iterable) of matches. This is because it cannot
be certain that a selector only has a single match (even when it includes a
prefix & suffix, perhaps the document changed!).</p>
<p>We could use the functions defined above in many ways; keeping highlighted
quotes in local storage, or in one’s bookmarks, or sharing them with others,
and so on. For this example, we keep it simple and highlight each selection
upon release of the mouse button; and store the selector to make it appear
again after a page reload.</p>
<pre class="language-js"><code class="language-js">document<span class="token
punctuation">.</span><span class="token function">addEventListener</span><span
class="token punctuation">(</span><span class="token
string">'mouseup'</span><span class="token punctuation">,</span> <span
class="token keyword">async</span> <span class="token
punctuation">(</span><span class="token punctuation">)</span> <span
class="token operator">=></span> <span class="token punctuation">{</span><br>
<span clas [...]
diff --git a/src/docs/getting-started.md b/src/docs/getting-started.md
index cf4ff6b..53035fe 100644
--- a/src/docs/getting-started.md
+++ b/src/docs/getting-started.md
@@ -70,9 +70,13 @@ import { createTextQuoteSelectorMatcher, highlightText }
from '@apache-annotator
async function highlightSelectorTarget(textQuoteSelector) {
const matches =
createTextQuoteSelectorMatcher(textQuoteSelector)(document.body);
- for await (const match of matches) {
- highlightText(match);
- }
+
+ // Modifying the DOM while searching can mess up; see issue #112.
+ // Therefore, we first collect all matches before highlighting them.
+ const matchList = [];
+ for await (const match of matches) matchList.push(match);
+
+ for (const match of matchList) highlightText(match);
}
```
