You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@annotator.apache.org by Richard Eckart de Castilho <re...@apache.org> on 2017/05/10 13:09:56 UTC
Just a simple example?
Hi all,
does anybody have a simple example of annotatorjs or Apache Annotator
that would work without a server-side storage?
I am imagining something like
* a static HTML page with some text in it and
* a JSON structure being created locally in that page which represents the annotations
* an invocation of annotatorjs/annotator that takes the JSON and renders it over the text
As an outcome, one would see parts of the texts highlighted and on-mouse-over information about the annotations would be displayed.
For this simple example, editing these annotations wouldn't even be required.
If anybody could point me to such an example, that would be great!
Cheers,
-- Richard
Re: DOM Iteration (was Re: Just a simple example?)
Posted by Sasha Goodman <em...@sashagoodman.com>.
Thanks TB Dinesh for finding the bug. I just fixed this, at least on my
Firefox, so hopefully the github pages content provider has updated the
files...you might need to hit refresh or wait a few minutes. The issue was
that in Firefox has a stricter implementation of document.evaluate where no
default value is provided for the fifth argument. The code also seems to
work on my Safari.
On Tue, May 16, 2017 at 10:46 AM TB Dinesh <di...@servelots.com> wrote:
> Sasha. Thanks.
> Fyi. Demo works on Chrome. Not on Firefox.
>
> On Tue, May 16, 2017 at 12:49 AM, Sasha Goodman <em...@sashagoodman.com>
> wrote:
> > Here is a demo of simple annotation, thanks to Benjamin:
> >
> > https://predict-r.github.io/annotation-model/
> >
> >
> > On Fri, May 12, 2017 at 12:19 PM Sasha Goodman <em...@sashagoodman.com>
> > wrote:
> >
> >> I would be delighted if my efforts were useful in this project!!!
> >> Regarding that code, if any parts are used it would make my week. The
> class
> >> structure is sorta self-documented by the standard, and combined with
> >> builders the classes it can accommodate a variety of motives.
> >>
> >> Highlighting is the most common motive now (correct me if I'm wrong). My
> >> gut-feeling is that to get the support and time of hard core annotators,
> >> the code needs to accommodate the idiosyncrasies of highlighting first.
> For
> >> example, if there are thousands of highlights on a page, an annotation
> >> builder might iterate/walk the document just once and fill in the
> thousands
> >> of highlights in one pass. Also, a highlighting app would probably need
> to
> >> modify the source document by inserting spans and such.
> >>
> >> If Randall needs familiar code for node iteration, tree walking, range
> >> splitting, string similarity and normalization, that's cool! Custom
> code,
> >> *especially* Polyfill type implementations, could smooth over browser
> >> idiosyncrasies. Also, I saw a Jsperf.com microbenchmark that put custom
> >> walkers on par with the native browser based ones.
> >>
> >> On a personal note, I do archival work and did not initially see the
> value
> >> in modifying the source document by inserting spans (however, a
> highlight
> >> app would need that). The main reason I'm excited about annotation is
> its
> >> value for labeling data for text analysis and machine learning. A lot of
> >> the advancements in machine learning are because of large bodies of data
> >> that have been tagged. The most common examples are usually of images
> that
> >> have regions selected and then labeled, but annotation could also help
> turn
> >> semi-structured text into more structured text data (e.g. for labeling
> >> parts of government documents). For archival work on mostly static
> >> documents, there does not seem to be a need to modify source document.
> On
> >> the other hand, for dynamically changing documents, inserting spans with
> >> unique IDs seems appropriate because its more robust to document
> changes.
> >> Yet, it is also vulnerable to turf battles with other extensions and the
> >> page's own javascript, so I hope it's not a requirement of the Apache
> >> library but rather a feature.
> >>
> >>
> >> On Thu, May 11, 2017 at 1:43 PM Benjamin Young <by...@bigbluehat.com>
> >> wrote:
> >>
> >>> Exciting to see this conversation happening. ^_^
> >>>
> >>>
> >>> Randall, how feasible would it be to bring (soon) your libraries (even
> >>> via copy/paste) into the Apache Annotator repo. I believe (according to
> >>> GitHub) you're author/owner of 90%+ of the code in them, and
> (consequently)
> >>> able to do that if you believe that's the right step.
> >>>
> >>>
> >>> Sasha you're classes modeled around the selector and a "builder" sound
> >>> very similar to the hopes I wrote up in
> >>> https://cwiki.apache.org/confluence/display/ANNO/Planning
> >>>
> >>>
> >>> I'd very much like to combine these efforts in some way.
> >>>
> >>>
> >>> Additionally--and the thing driving me personally at the moment--I have
> >>> to present on Apache Annotator next Wednesday!
> >>>
> >>> https://apachecon2017.sched.com/event/AbBW
> >>>
> >>>
> >>> Consequently, I'd very much love it if we (collectively) could build a
> >>> demo together! There's plenty to talk about wrt to annotation,
> community
> >>> building, Web Annotation Data Model & Protocol, as well as why (those
> of us
> >>> that are here at least) have chosen to start collaborating at the ASF.
> >>>
> >>>
> >>> At any rate, I plan to be coding on all the things leading up to
> >>> Wednesday, so any help, input, pointers, and code (hehe) that anyone
> wants
> >>> to toss in ahead of my codez, I'd be most grateful to code together!
> >>>
> >>>
> >>> Thanks, all!
> >>>
> >>> Benjamin
> >>>
> >>> --
> >>>
> >>> http://bigbluehat.com/
> >>>
> >>> http://linkedin.com/in/benjaminyoung
> >>>
> >>> ________________________________
> >>> From: Randall Leeds <ra...@apache.org>
> >>> Sent: Thursday, May 11, 2017 3:34:24 PM
> >>> To: dev@annotator.incubator.apache.org
> >>> Subject: DOM Iteration (was Re: Just a simple example?)
> >>>
> >>> Great to see you here, Sasha!
> >>>
> >>> On Wed, May 10, 2017 at 5:39 PM Sasha Goodman <em...@sashagoodman.com>
> >>> wrote:
> >>>
> >>> >
> >>> > P.S. This afternoon I streamlined the TextQuoteSelector and
> >>> > TextPositionSelector to work (in principle ) consistently with
> Randall
> >>> > Leed's implementation that used NodeIterator and textContents.
> >>> >
> >>> >
> >>> Neat :).
> >>>
> >>> I think my takeaway from the simple example thread, and something of
> which
> >>> many of us were likely already well aware, is that there's a desire
> for a
> >>> good highlighter implementation. A way to highlight text is often the
> >>> first
> >>> example people want to see.
> >>>
> >>> While I hope to see experimentation with implementations that try to
> limit
> >>> the impact on the DOM, I think <mark> or <span> wrapping of text nodes
> is
> >>> still the easiest to understand. In this approach, the actual wrapping
> is
> >>> easy. The difficult part is iteration.
> >>>
> >>> Now, some quick background on node iteration.
> >>>
> >>> I chose to use NodeIterator rather than TreeWalker for my dom-seek
> library
> >>> because it meant that the seek function could be stateless, support
> >>> seeking
> >>> forward and backward, and still be able to return the number of
> characters
> >>> consumed by a seek. The desire to know whether to include the current
> >>> node's content in the seek count is fulfilled by NodeIterator's
> >>> "pointerBeforeReferenceNode". Essentially, a NodeIterator stores a
> point
> >>> before or after a node, rather than simply a current node.
> >>>
> >>> However, using NodeIterator to traverse a Range is not really great.
> Since
> >>> it has a read only currentNode, the best that can be done is to start
> with
> >>> the commonAncestorContainer of the Range. Range has compareNode,
> >>> comparePoint, and isPointInRange. I have no idea how expensive these
> are.
> >>> Iterating all the nodes under the commonAncestorContainer doesn't feel
> >>> great to begin with. TreeWalker might be more appropriate since its
> >>> currentNode could be set to startContainer directly. TreeWalker also
> >>> appears to have consistent platform support.
> >>>
> >>> All of this is complicated by the Range being able to point to offsets
> >>> within text nodes. For the purposes of highlighting with wrapper
> elements
> >>> it's necessary to split the boundary nodes. I think there are probably
> a
> >>> number of libraries for this, but I propose we write one under our
> repo.
> >>>
> >>> We might also find that normalizing the endpoints of a Range in some
> >>> fashion is a helpful prerequisite. There is a library I found that does
> >>> this, but I found its algorithm terribly confusing. I put time into
> >>> rewriting it without dependencies. Despite some initial excitement, the
> >>> author never fully vetted and accepted my pull request:
> >>> https://github.com/webmodules/range-normalize/pull/2
> >>>
> >>> In conclusion, I think there'd be value in bringing some functional
> >>> utilities into Apache Annotator for dealing with iteration, range
> >>> splitting, and range normalization, with the goal of providing a very
> >>> succinct and simple highlighter that looks like this:
> >>>
> >>> ```
> >>> for (const node of textNodes(range)) {
> >>> const mark = document.createElement('mark');
> >>> node.replaceWith(mark);
> >>> mark.appendChild(node);
> >>> }
> >>> ```
> >>>
> >>> Some care needs to be taken that whatever iteration we use is not
> >>> invalidated by the replacement of the text node with its wrapper.
> >>>
> >>> The fact that a simple example like this is hard to produce is
> evidence of
> >>> the underlying complexity described in the above paragraphs. When I see
> >>> people wanting a simple highlighter what I hear is that they actually
> need
> >>> simple abstractions upon which to build a highlighter. The highlighter
> >>> itself should be easy. Often, highlighters that projects provide are
> not
> >>> shipped standalone or don't do exactly what the author needs (use spans
> >>> instead of marks, add a particular class, coalesce overlapping
> highlights
> >>> or not, etc). There is lots of room to do different things but being
> able
> >>> to simply get the nodes to be highlighted is the prerequisite task that
> >>> contains most of the complexity.
> >>>
> >>> That's all (and probably way too much) for now. Finding all the tools
> for
> >>> all these things is a pain enough that I think we should have a
> >>> comprehensive set of such utilities in Apache Annotator, even if that
> >>> risks
> >>> looking like a bit of NIH syndrome.
> >>>
> >>> Unless anyone objects, I think I'll aim to ship libraries for these:
> >>> - Node iteration (https://github.com/tilgovi/dom-node-iterator)
> >>> - Tree walking (might not need a library if support is good)
> >>> - Range splitting
> >>> - Range normalization (see my pull request reference, above)
> >>> - Range iterating
> >>> - Text distance (https://github.com/tilgovi/dom-seek)
> >>>
> >>> If anyone wants to start on any of the above, you're welcome to depend
> on
> >>> libraries that are outside Apache Annotator. In the case of libraries
> that
> >>> I've written, there is value to bringing them into Apache Annotator
> >>> because
> >>> they are all written in ES6 but not packaged to be consumed as ES6.
> >>> Bringing them inside our repo means better code deduplication by tree
> >>> shaking in tools like rollup and webpack. They could be packaged as ES6
> >>> where they are, but if I'm going to spend time improving the packaging
> I
> >>> would rather just toss out the packaging and get the benefits of the
> >>> monorepo having all that build/test boilerplate done once for all of
> them.
> >>>
> >>
>
Re: DOM Iteration (was Re: Just a simple example?)
Posted by TB Dinesh <di...@servelots.com>.
Sasha. Thanks.
Fyi. Demo works on Chrome. Not on Firefox.
On Tue, May 16, 2017 at 12:49 AM, Sasha Goodman <em...@sashagoodman.com> wrote:
> Here is a demo of simple annotation, thanks to Benjamin:
>
> https://predict-r.github.io/annotation-model/
>
>
> On Fri, May 12, 2017 at 12:19 PM Sasha Goodman <em...@sashagoodman.com>
> wrote:
>
>> I would be delighted if my efforts were useful in this project!!!
>> Regarding that code, if any parts are used it would make my week. The class
>> structure is sorta self-documented by the standard, and combined with
>> builders the classes it can accommodate a variety of motives.
>>
>> Highlighting is the most common motive now (correct me if I'm wrong). My
>> gut-feeling is that to get the support and time of hard core annotators,
>> the code needs to accommodate the idiosyncrasies of highlighting first. For
>> example, if there are thousands of highlights on a page, an annotation
>> builder might iterate/walk the document just once and fill in the thousands
>> of highlights in one pass. Also, a highlighting app would probably need to
>> modify the source document by inserting spans and such.
>>
>> If Randall needs familiar code for node iteration, tree walking, range
>> splitting, string similarity and normalization, that's cool! Custom code,
>> *especially* Polyfill type implementations, could smooth over browser
>> idiosyncrasies. Also, I saw a Jsperf.com microbenchmark that put custom
>> walkers on par with the native browser based ones.
>>
>> On a personal note, I do archival work and did not initially see the value
>> in modifying the source document by inserting spans (however, a highlight
>> app would need that). The main reason I'm excited about annotation is its
>> value for labeling data for text analysis and machine learning. A lot of
>> the advancements in machine learning are because of large bodies of data
>> that have been tagged. The most common examples are usually of images that
>> have regions selected and then labeled, but annotation could also help turn
>> semi-structured text into more structured text data (e.g. for labeling
>> parts of government documents). For archival work on mostly static
>> documents, there does not seem to be a need to modify source document. On
>> the other hand, for dynamically changing documents, inserting spans with
>> unique IDs seems appropriate because its more robust to document changes.
>> Yet, it is also vulnerable to turf battles with other extensions and the
>> page's own javascript, so I hope it's not a requirement of the Apache
>> library but rather a feature.
>>
>>
>> On Thu, May 11, 2017 at 1:43 PM Benjamin Young <by...@bigbluehat.com>
>> wrote:
>>
>>> Exciting to see this conversation happening. ^_^
>>>
>>>
>>> Randall, how feasible would it be to bring (soon) your libraries (even
>>> via copy/paste) into the Apache Annotator repo. I believe (according to
>>> GitHub) you're author/owner of 90%+ of the code in them, and (consequently)
>>> able to do that if you believe that's the right step.
>>>
>>>
>>> Sasha you're classes modeled around the selector and a "builder" sound
>>> very similar to the hopes I wrote up in
>>> https://cwiki.apache.org/confluence/display/ANNO/Planning
>>>
>>>
>>> I'd very much like to combine these efforts in some way.
>>>
>>>
>>> Additionally--and the thing driving me personally at the moment--I have
>>> to present on Apache Annotator next Wednesday!
>>>
>>> https://apachecon2017.sched.com/event/AbBW
>>>
>>>
>>> Consequently, I'd very much love it if we (collectively) could build a
>>> demo together! There's plenty to talk about wrt to annotation, community
>>> building, Web Annotation Data Model & Protocol, as well as why (those of us
>>> that are here at least) have chosen to start collaborating at the ASF.
>>>
>>>
>>> At any rate, I plan to be coding on all the things leading up to
>>> Wednesday, so any help, input, pointers, and code (hehe) that anyone wants
>>> to toss in ahead of my codez, I'd be most grateful to code together!
>>>
>>>
>>> Thanks, all!
>>>
>>> Benjamin
>>>
>>> --
>>>
>>> http://bigbluehat.com/
>>>
>>> http://linkedin.com/in/benjaminyoung
>>>
>>> ________________________________
>>> From: Randall Leeds <ra...@apache.org>
>>> Sent: Thursday, May 11, 2017 3:34:24 PM
>>> To: dev@annotator.incubator.apache.org
>>> Subject: DOM Iteration (was Re: Just a simple example?)
>>>
>>> Great to see you here, Sasha!
>>>
>>> On Wed, May 10, 2017 at 5:39 PM Sasha Goodman <em...@sashagoodman.com>
>>> wrote:
>>>
>>> >
>>> > P.S. This afternoon I streamlined the TextQuoteSelector and
>>> > TextPositionSelector to work (in principle ) consistently with Randall
>>> > Leed's implementation that used NodeIterator and textContents.
>>> >
>>> >
>>> Neat :).
>>>
>>> I think my takeaway from the simple example thread, and something of which
>>> many of us were likely already well aware, is that there's a desire for a
>>> good highlighter implementation. A way to highlight text is often the
>>> first
>>> example people want to see.
>>>
>>> While I hope to see experimentation with implementations that try to limit
>>> the impact on the DOM, I think <mark> or <span> wrapping of text nodes is
>>> still the easiest to understand. In this approach, the actual wrapping is
>>> easy. The difficult part is iteration.
>>>
>>> Now, some quick background on node iteration.
>>>
>>> I chose to use NodeIterator rather than TreeWalker for my dom-seek library
>>> because it meant that the seek function could be stateless, support
>>> seeking
>>> forward and backward, and still be able to return the number of characters
>>> consumed by a seek. The desire to know whether to include the current
>>> node's content in the seek count is fulfilled by NodeIterator's
>>> "pointerBeforeReferenceNode". Essentially, a NodeIterator stores a point
>>> before or after a node, rather than simply a current node.
>>>
>>> However, using NodeIterator to traverse a Range is not really great. Since
>>> it has a read only currentNode, the best that can be done is to start with
>>> the commonAncestorContainer of the Range. Range has compareNode,
>>> comparePoint, and isPointInRange. I have no idea how expensive these are.
>>> Iterating all the nodes under the commonAncestorContainer doesn't feel
>>> great to begin with. TreeWalker might be more appropriate since its
>>> currentNode could be set to startContainer directly. TreeWalker also
>>> appears to have consistent platform support.
>>>
>>> All of this is complicated by the Range being able to point to offsets
>>> within text nodes. For the purposes of highlighting with wrapper elements
>>> it's necessary to split the boundary nodes. I think there are probably a
>>> number of libraries for this, but I propose we write one under our repo.
>>>
>>> We might also find that normalizing the endpoints of a Range in some
>>> fashion is a helpful prerequisite. There is a library I found that does
>>> this, but I found its algorithm terribly confusing. I put time into
>>> rewriting it without dependencies. Despite some initial excitement, the
>>> author never fully vetted and accepted my pull request:
>>> https://github.com/webmodules/range-normalize/pull/2
>>>
>>> In conclusion, I think there'd be value in bringing some functional
>>> utilities into Apache Annotator for dealing with iteration, range
>>> splitting, and range normalization, with the goal of providing a very
>>> succinct and simple highlighter that looks like this:
>>>
>>> ```
>>> for (const node of textNodes(range)) {
>>> const mark = document.createElement('mark');
>>> node.replaceWith(mark);
>>> mark.appendChild(node);
>>> }
>>> ```
>>>
>>> Some care needs to be taken that whatever iteration we use is not
>>> invalidated by the replacement of the text node with its wrapper.
>>>
>>> The fact that a simple example like this is hard to produce is evidence of
>>> the underlying complexity described in the above paragraphs. When I see
>>> people wanting a simple highlighter what I hear is that they actually need
>>> simple abstractions upon which to build a highlighter. The highlighter
>>> itself should be easy. Often, highlighters that projects provide are not
>>> shipped standalone or don't do exactly what the author needs (use spans
>>> instead of marks, add a particular class, coalesce overlapping highlights
>>> or not, etc). There is lots of room to do different things but being able
>>> to simply get the nodes to be highlighted is the prerequisite task that
>>> contains most of the complexity.
>>>
>>> That's all (and probably way too much) for now. Finding all the tools for
>>> all these things is a pain enough that I think we should have a
>>> comprehensive set of such utilities in Apache Annotator, even if that
>>> risks
>>> looking like a bit of NIH syndrome.
>>>
>>> Unless anyone objects, I think I'll aim to ship libraries for these:
>>> - Node iteration (https://github.com/tilgovi/dom-node-iterator)
>>> - Tree walking (might not need a library if support is good)
>>> - Range splitting
>>> - Range normalization (see my pull request reference, above)
>>> - Range iterating
>>> - Text distance (https://github.com/tilgovi/dom-seek)
>>>
>>> If anyone wants to start on any of the above, you're welcome to depend on
>>> libraries that are outside Apache Annotator. In the case of libraries that
>>> I've written, there is value to bringing them into Apache Annotator
>>> because
>>> they are all written in ES6 but not packaged to be consumed as ES6.
>>> Bringing them inside our repo means better code deduplication by tree
>>> shaking in tools like rollup and webpack. They could be packaged as ES6
>>> where they are, but if I'm going to spend time improving the packaging I
>>> would rather just toss out the packaging and get the benefits of the
>>> monorepo having all that build/test boilerplate done once for all of them.
>>>
>>
Re: DOM Iteration (was Re: Just a simple example?)
Posted by Sasha Goodman <em...@sashagoodman.com>.
Here is a demo of simple annotation, thanks to Benjamin:
https://predict-r.github.io/annotation-model/
On Fri, May 12, 2017 at 12:19 PM Sasha Goodman <em...@sashagoodman.com>
wrote:
> I would be delighted if my efforts were useful in this project!!!
> Regarding that code, if any parts are used it would make my week. The class
> structure is sorta self-documented by the standard, and combined with
> builders the classes it can accommodate a variety of motives.
>
> Highlighting is the most common motive now (correct me if I'm wrong). My
> gut-feeling is that to get the support and time of hard core annotators,
> the code needs to accommodate the idiosyncrasies of highlighting first. For
> example, if there are thousands of highlights on a page, an annotation
> builder might iterate/walk the document just once and fill in the thousands
> of highlights in one pass. Also, a highlighting app would probably need to
> modify the source document by inserting spans and such.
>
> If Randall needs familiar code for node iteration, tree walking, range
> splitting, string similarity and normalization, that's cool! Custom code,
> *especially* Polyfill type implementations, could smooth over browser
> idiosyncrasies. Also, I saw a Jsperf.com microbenchmark that put custom
> walkers on par with the native browser based ones.
>
> On a personal note, I do archival work and did not initially see the value
> in modifying the source document by inserting spans (however, a highlight
> app would need that). The main reason I'm excited about annotation is its
> value for labeling data for text analysis and machine learning. A lot of
> the advancements in machine learning are because of large bodies of data
> that have been tagged. The most common examples are usually of images that
> have regions selected and then labeled, but annotation could also help turn
> semi-structured text into more structured text data (e.g. for labeling
> parts of government documents). For archival work on mostly static
> documents, there does not seem to be a need to modify source document. On
> the other hand, for dynamically changing documents, inserting spans with
> unique IDs seems appropriate because its more robust to document changes.
> Yet, it is also vulnerable to turf battles with other extensions and the
> page's own javascript, so I hope it's not a requirement of the Apache
> library but rather a feature.
>
>
> On Thu, May 11, 2017 at 1:43 PM Benjamin Young <by...@bigbluehat.com>
> wrote:
>
>> Exciting to see this conversation happening. ^_^
>>
>>
>> Randall, how feasible would it be to bring (soon) your libraries (even
>> via copy/paste) into the Apache Annotator repo. I believe (according to
>> GitHub) you're author/owner of 90%+ of the code in them, and (consequently)
>> able to do that if you believe that's the right step.
>>
>>
>> Sasha you're classes modeled around the selector and a "builder" sound
>> very similar to the hopes I wrote up in
>> https://cwiki.apache.org/confluence/display/ANNO/Planning
>>
>>
>> I'd very much like to combine these efforts in some way.
>>
>>
>> Additionally--and the thing driving me personally at the moment--I have
>> to present on Apache Annotator next Wednesday!
>>
>> https://apachecon2017.sched.com/event/AbBW
>>
>>
>> Consequently, I'd very much love it if we (collectively) could build a
>> demo together! There's plenty to talk about wrt to annotation, community
>> building, Web Annotation Data Model & Protocol, as well as why (those of us
>> that are here at least) have chosen to start collaborating at the ASF.
>>
>>
>> At any rate, I plan to be coding on all the things leading up to
>> Wednesday, so any help, input, pointers, and code (hehe) that anyone wants
>> to toss in ahead of my codez, I'd be most grateful to code together!
>>
>>
>> Thanks, all!
>>
>> Benjamin
>>
>> --
>>
>> http://bigbluehat.com/
>>
>> http://linkedin.com/in/benjaminyoung
>>
>> ________________________________
>> From: Randall Leeds <ra...@apache.org>
>> Sent: Thursday, May 11, 2017 3:34:24 PM
>> To: dev@annotator.incubator.apache.org
>> Subject: DOM Iteration (was Re: Just a simple example?)
>>
>> Great to see you here, Sasha!
>>
>> On Wed, May 10, 2017 at 5:39 PM Sasha Goodman <em...@sashagoodman.com>
>> wrote:
>>
>> >
>> > P.S. This afternoon I streamlined the TextQuoteSelector and
>> > TextPositionSelector to work (in principle ) consistently with Randall
>> > Leed's implementation that used NodeIterator and textContents.
>> >
>> >
>> Neat :).
>>
>> I think my takeaway from the simple example thread, and something of which
>> many of us were likely already well aware, is that there's a desire for a
>> good highlighter implementation. A way to highlight text is often the
>> first
>> example people want to see.
>>
>> While I hope to see experimentation with implementations that try to limit
>> the impact on the DOM, I think <mark> or <span> wrapping of text nodes is
>> still the easiest to understand. In this approach, the actual wrapping is
>> easy. The difficult part is iteration.
>>
>> Now, some quick background on node iteration.
>>
>> I chose to use NodeIterator rather than TreeWalker for my dom-seek library
>> because it meant that the seek function could be stateless, support
>> seeking
>> forward and backward, and still be able to return the number of characters
>> consumed by a seek. The desire to know whether to include the current
>> node's content in the seek count is fulfilled by NodeIterator's
>> "pointerBeforeReferenceNode". Essentially, a NodeIterator stores a point
>> before or after a node, rather than simply a current node.
>>
>> However, using NodeIterator to traverse a Range is not really great. Since
>> it has a read only currentNode, the best that can be done is to start with
>> the commonAncestorContainer of the Range. Range has compareNode,
>> comparePoint, and isPointInRange. I have no idea how expensive these are.
>> Iterating all the nodes under the commonAncestorContainer doesn't feel
>> great to begin with. TreeWalker might be more appropriate since its
>> currentNode could be set to startContainer directly. TreeWalker also
>> appears to have consistent platform support.
>>
>> All of this is complicated by the Range being able to point to offsets
>> within text nodes. For the purposes of highlighting with wrapper elements
>> it's necessary to split the boundary nodes. I think there are probably a
>> number of libraries for this, but I propose we write one under our repo.
>>
>> We might also find that normalizing the endpoints of a Range in some
>> fashion is a helpful prerequisite. There is a library I found that does
>> this, but I found its algorithm terribly confusing. I put time into
>> rewriting it without dependencies. Despite some initial excitement, the
>> author never fully vetted and accepted my pull request:
>> https://github.com/webmodules/range-normalize/pull/2
>>
>> In conclusion, I think there'd be value in bringing some functional
>> utilities into Apache Annotator for dealing with iteration, range
>> splitting, and range normalization, with the goal of providing a very
>> succinct and simple highlighter that looks like this:
>>
>> ```
>> for (const node of textNodes(range)) {
>> const mark = document.createElement('mark');
>> node.replaceWith(mark);
>> mark.appendChild(node);
>> }
>> ```
>>
>> Some care needs to be taken that whatever iteration we use is not
>> invalidated by the replacement of the text node with its wrapper.
>>
>> The fact that a simple example like this is hard to produce is evidence of
>> the underlying complexity described in the above paragraphs. When I see
>> people wanting a simple highlighter what I hear is that they actually need
>> simple abstractions upon which to build a highlighter. The highlighter
>> itself should be easy. Often, highlighters that projects provide are not
>> shipped standalone or don't do exactly what the author needs (use spans
>> instead of marks, add a particular class, coalesce overlapping highlights
>> or not, etc). There is lots of room to do different things but being able
>> to simply get the nodes to be highlighted is the prerequisite task that
>> contains most of the complexity.
>>
>> That's all (and probably way too much) for now. Finding all the tools for
>> all these things is a pain enough that I think we should have a
>> comprehensive set of such utilities in Apache Annotator, even if that
>> risks
>> looking like a bit of NIH syndrome.
>>
>> Unless anyone objects, I think I'll aim to ship libraries for these:
>> - Node iteration (https://github.com/tilgovi/dom-node-iterator)
>> - Tree walking (might not need a library if support is good)
>> - Range splitting
>> - Range normalization (see my pull request reference, above)
>> - Range iterating
>> - Text distance (https://github.com/tilgovi/dom-seek)
>>
>> If anyone wants to start on any of the above, you're welcome to depend on
>> libraries that are outside Apache Annotator. In the case of libraries that
>> I've written, there is value to bringing them into Apache Annotator
>> because
>> they are all written in ES6 but not packaged to be consumed as ES6.
>> Bringing them inside our repo means better code deduplication by tree
>> shaking in tools like rollup and webpack. They could be packaged as ES6
>> where they are, but if I'm going to spend time improving the packaging I
>> would rather just toss out the packaging and get the benefits of the
>> monorepo having all that build/test boilerplate done once for all of them.
>>
>
Re: DOM Iteration (was Re: Just a simple example?)
Posted by Sasha Goodman <em...@sashagoodman.com>.
I would be delighted if my efforts were useful in this project!!!
Regarding that code, if any parts are used it would make my week. The class
structure is sorta self-documented by the standard, and combined with
builders the classes it can accommodate a variety of motives.
Highlighting is the most common motive now (correct me if I'm wrong). My
gut-feeling is that to get the support and time of hard core annotators,
the code needs to accommodate the idiosyncrasies of highlighting first. For
example, if there are thousands of highlights on a page, an annotation
builder might iterate/walk the document just once and fill in the thousands
of highlights in one pass. Also, a highlighting app would probably need to
modify the source document by inserting spans and such.
If Randall needs familiar code for node iteration, tree walking, range
splitting, string similarity and normalization, that's cool! Custom code,
*especially* Polyfill type implementations, could smooth over browser
idiosyncrasies. Also, I saw a Jsperf.com microbenchmark that put custom
walkers on par with the native browser based ones.
On a personal note, I do archival work and did not initially see the value
in modifying the source document by inserting spans (however, a highlight
app would need that). The main reason I'm excited about annotation is its
value for labeling data for text analysis and machine learning. A lot of
the advancements in machine learning are because of large bodies of data
that have been tagged. The most common examples are usually of images that
have regions selected and then labeled, but annotation could also help turn
semi-structured text into more structured text data (e.g. for labeling
parts of government documents). For archival work on mostly static
documents, there does not seem to be a need to modify source document. On
the other hand, for dynamically changing documents, inserting spans with
unique IDs seems appropriate because its more robust to document changes.
Yet, it is also vulnerable to turf battles with other extensions and the
page's own javascript, so I hope it's not a requirement of the Apache
library but rather a feature.
On Thu, May 11, 2017 at 1:43 PM Benjamin Young <by...@bigbluehat.com>
wrote:
> Exciting to see this conversation happening. ^_^
>
>
> Randall, how feasible would it be to bring (soon) your libraries (even via
> copy/paste) into the Apache Annotator repo. I believe (according to GitHub)
> you're author/owner of 90%+ of the code in them, and (consequently) able to
> do that if you believe that's the right step.
>
>
> Sasha you're classes modeled around the selector and a "builder" sound
> very similar to the hopes I wrote up in
> https://cwiki.apache.org/confluence/display/ANNO/Planning
>
>
> I'd very much like to combine these efforts in some way.
>
>
> Additionally--and the thing driving me personally at the moment--I have to
> present on Apache Annotator next Wednesday!
>
> https://apachecon2017.sched.com/event/AbBW
>
>
> Consequently, I'd very much love it if we (collectively) could build a
> demo together! There's plenty to talk about wrt to annotation, community
> building, Web Annotation Data Model & Protocol, as well as why (those of us
> that are here at least) have chosen to start collaborating at the ASF.
>
>
> At any rate, I plan to be coding on all the things leading up to
> Wednesday, so any help, input, pointers, and code (hehe) that anyone wants
> to toss in ahead of my codez, I'd be most grateful to code together!
>
>
> Thanks, all!
>
> Benjamin
>
> --
>
> http://bigbluehat.com/
>
> http://linkedin.com/in/benjaminyoung
>
> ________________________________
> From: Randall Leeds <ra...@apache.org>
> Sent: Thursday, May 11, 2017 3:34:24 PM
> To: dev@annotator.incubator.apache.org
> Subject: DOM Iteration (was Re: Just a simple example?)
>
> Great to see you here, Sasha!
>
> On Wed, May 10, 2017 at 5:39 PM Sasha Goodman <em...@sashagoodman.com>
> wrote:
>
> >
> > P.S. This afternoon I streamlined the TextQuoteSelector and
> > TextPositionSelector to work (in principle ) consistently with Randall
> > Leed's implementation that used NodeIterator and textContents.
> >
> >
> Neat :).
>
> I think my takeaway from the simple example thread, and something of which
> many of us were likely already well aware, is that there's a desire for a
> good highlighter implementation. A way to highlight text is often the first
> example people want to see.
>
> While I hope to see experimentation with implementations that try to limit
> the impact on the DOM, I think <mark> or <span> wrapping of text nodes is
> still the easiest to understand. In this approach, the actual wrapping is
> easy. The difficult part is iteration.
>
> Now, some quick background on node iteration.
>
> I chose to use NodeIterator rather than TreeWalker for my dom-seek library
> because it meant that the seek function could be stateless, support seeking
> forward and backward, and still be able to return the number of characters
> consumed by a seek. The desire to know whether to include the current
> node's content in the seek count is fulfilled by NodeIterator's
> "pointerBeforeReferenceNode". Essentially, a NodeIterator stores a point
> before or after a node, rather than simply a current node.
>
> However, using NodeIterator to traverse a Range is not really great. Since
> it has a read only currentNode, the best that can be done is to start with
> the commonAncestorContainer of the Range. Range has compareNode,
> comparePoint, and isPointInRange. I have no idea how expensive these are.
> Iterating all the nodes under the commonAncestorContainer doesn't feel
> great to begin with. TreeWalker might be more appropriate since its
> currentNode could be set to startContainer directly. TreeWalker also
> appears to have consistent platform support.
>
> All of this is complicated by the Range being able to point to offsets
> within text nodes. For the purposes of highlighting with wrapper elements
> it's necessary to split the boundary nodes. I think there are probably a
> number of libraries for this, but I propose we write one under our repo.
>
> We might also find that normalizing the endpoints of a Range in some
> fashion is a helpful prerequisite. There is a library I found that does
> this, but I found its algorithm terribly confusing. I put time into
> rewriting it without dependencies. Despite some initial excitement, the
> author never fully vetted and accepted my pull request:
> https://github.com/webmodules/range-normalize/pull/2
>
> In conclusion, I think there'd be value in bringing some functional
> utilities into Apache Annotator for dealing with iteration, range
> splitting, and range normalization, with the goal of providing a very
> succinct and simple highlighter that looks like this:
>
> ```
> for (const node of textNodes(range)) {
> const mark = document.createElement('mark');
> node.replaceWith(mark);
> mark.appendChild(node);
> }
> ```
>
> Some care needs to be taken that whatever iteration we use is not
> invalidated by the replacement of the text node with its wrapper.
>
> The fact that a simple example like this is hard to produce is evidence of
> the underlying complexity described in the above paragraphs. When I see
> people wanting a simple highlighter what I hear is that they actually need
> simple abstractions upon which to build a highlighter. The highlighter
> itself should be easy. Often, highlighters that projects provide are not
> shipped standalone or don't do exactly what the author needs (use spans
> instead of marks, add a particular class, coalesce overlapping highlights
> or not, etc). There is lots of room to do different things but being able
> to simply get the nodes to be highlighted is the prerequisite task that
> contains most of the complexity.
>
> That's all (and probably way too much) for now. Finding all the tools for
> all these things is a pain enough that I think we should have a
> comprehensive set of such utilities in Apache Annotator, even if that risks
> looking like a bit of NIH syndrome.
>
> Unless anyone objects, I think I'll aim to ship libraries for these:
> - Node iteration (https://github.com/tilgovi/dom-node-iterator)
> - Tree walking (might not need a library if support is good)
> - Range splitting
> - Range normalization (see my pull request reference, above)
> - Range iterating
> - Text distance (https://github.com/tilgovi/dom-seek)
>
> If anyone wants to start on any of the above, you're welcome to depend on
> libraries that are outside Apache Annotator. In the case of libraries that
> I've written, there is value to bringing them into Apache Annotator because
> they are all written in ES6 but not packaged to be consumed as ES6.
> Bringing them inside our repo means better code deduplication by tree
> shaking in tools like rollup and webpack. They could be packaged as ES6
> where they are, but if I'm going to spend time improving the packaging I
> would rather just toss out the packaging and get the benefits of the
> monorepo having all that build/test boilerplate done once for all of them.
>
Re: DOM Iteration (was Re: Just a simple example?)
Posted by Benjamin Young <by...@bigbluehat.com>.
Exciting to see this conversation happening. ^_^
Randall, how feasible would it be to bring (soon) your libraries (even via copy/paste) into the Apache Annotator repo. I believe (according to GitHub) you're author/owner of 90%+ of the code in them, and (consequently) able to do that if you believe that's the right step.
Sasha you're classes modeled around the selector and a "builder" sound very similar to the hopes I wrote up in https://cwiki.apache.org/confluence/display/ANNO/Planning
I'd very much like to combine these efforts in some way.
Additionally--and the thing driving me personally at the moment--I have to present on Apache Annotator next Wednesday!
https://apachecon2017.sched.com/event/AbBW
Consequently, I'd very much love it if we (collectively) could build a demo together! There's plenty to talk about wrt to annotation, community building, Web Annotation Data Model & Protocol, as well as why (those of us that are here at least) have chosen to start collaborating at the ASF.
At any rate, I plan to be coding on all the things leading up to Wednesday, so any help, input, pointers, and code (hehe) that anyone wants to toss in ahead of my codez, I'd be most grateful to code together!
Thanks, all!
Benjamin
--
http://bigbluehat.com/
http://linkedin.com/in/benjaminyoung
________________________________
From: Randall Leeds <ra...@apache.org>
Sent: Thursday, May 11, 2017 3:34:24 PM
To: dev@annotator.incubator.apache.org
Subject: DOM Iteration (was Re: Just a simple example?)
Great to see you here, Sasha!
On Wed, May 10, 2017 at 5:39 PM Sasha Goodman <em...@sashagoodman.com>
wrote:
>
> P.S. This afternoon I streamlined the TextQuoteSelector and
> TextPositionSelector to work (in principle ) consistently with Randall
> Leed's implementation that used NodeIterator and textContents.
>
>
Neat :).
I think my takeaway from the simple example thread, and something of which
many of us were likely already well aware, is that there's a desire for a
good highlighter implementation. A way to highlight text is often the first
example people want to see.
While I hope to see experimentation with implementations that try to limit
the impact on the DOM, I think <mark> or <span> wrapping of text nodes is
still the easiest to understand. In this approach, the actual wrapping is
easy. The difficult part is iteration.
Now, some quick background on node iteration.
I chose to use NodeIterator rather than TreeWalker for my dom-seek library
because it meant that the seek function could be stateless, support seeking
forward and backward, and still be able to return the number of characters
consumed by a seek. The desire to know whether to include the current
node's content in the seek count is fulfilled by NodeIterator's
"pointerBeforeReferenceNode". Essentially, a NodeIterator stores a point
before or after a node, rather than simply a current node.
However, using NodeIterator to traverse a Range is not really great. Since
it has a read only currentNode, the best that can be done is to start with
the commonAncestorContainer of the Range. Range has compareNode,
comparePoint, and isPointInRange. I have no idea how expensive these are.
Iterating all the nodes under the commonAncestorContainer doesn't feel
great to begin with. TreeWalker might be more appropriate since its
currentNode could be set to startContainer directly. TreeWalker also
appears to have consistent platform support.
All of this is complicated by the Range being able to point to offsets
within text nodes. For the purposes of highlighting with wrapper elements
it's necessary to split the boundary nodes. I think there are probably a
number of libraries for this, but I propose we write one under our repo.
We might also find that normalizing the endpoints of a Range in some
fashion is a helpful prerequisite. There is a library I found that does
this, but I found its algorithm terribly confusing. I put time into
rewriting it without dependencies. Despite some initial excitement, the
author never fully vetted and accepted my pull request:
https://github.com/webmodules/range-normalize/pull/2
In conclusion, I think there'd be value in bringing some functional
utilities into Apache Annotator for dealing with iteration, range
splitting, and range normalization, with the goal of providing a very
succinct and simple highlighter that looks like this:
```
for (const node of textNodes(range)) {
const mark = document.createElement('mark');
node.replaceWith(mark);
mark.appendChild(node);
}
```
Some care needs to be taken that whatever iteration we use is not
invalidated by the replacement of the text node with its wrapper.
The fact that a simple example like this is hard to produce is evidence of
the underlying complexity described in the above paragraphs. When I see
people wanting a simple highlighter what I hear is that they actually need
simple abstractions upon which to build a highlighter. The highlighter
itself should be easy. Often, highlighters that projects provide are not
shipped standalone or don't do exactly what the author needs (use spans
instead of marks, add a particular class, coalesce overlapping highlights
or not, etc). There is lots of room to do different things but being able
to simply get the nodes to be highlighted is the prerequisite task that
contains most of the complexity.
That's all (and probably way too much) for now. Finding all the tools for
all these things is a pain enough that I think we should have a
comprehensive set of such utilities in Apache Annotator, even if that risks
looking like a bit of NIH syndrome.
Unless anyone objects, I think I'll aim to ship libraries for these:
- Node iteration (https://github.com/tilgovi/dom-node-iterator)
- Tree walking (might not need a library if support is good)
- Range splitting
- Range normalization (see my pull request reference, above)
- Range iterating
- Text distance (https://github.com/tilgovi/dom-seek)
If anyone wants to start on any of the above, you're welcome to depend on
libraries that are outside Apache Annotator. In the case of libraries that
I've written, there is value to bringing them into Apache Annotator because
they are all written in ES6 but not packaged to be consumed as ES6.
Bringing them inside our repo means better code deduplication by tree
shaking in tools like rollup and webpack. They could be packaged as ES6
where they are, but if I'm going to spend time improving the packaging I
would rather just toss out the packaging and get the benefits of the
monorepo having all that build/test boilerplate done once for all of them.
DOM Iteration (was Re: Just a simple example?)
Posted by Randall Leeds <ra...@apache.org>.
Great to see you here, Sasha!
On Wed, May 10, 2017 at 5:39 PM Sasha Goodman <em...@sashagoodman.com>
wrote:
>
> P.S. This afternoon I streamlined the TextQuoteSelector and
> TextPositionSelector to work (in principle ) consistently with Randall
> Leed's implementation that used NodeIterator and textContents.
>
>
Neat :).
I think my takeaway from the simple example thread, and something of which
many of us were likely already well aware, is that there's a desire for a
good highlighter implementation. A way to highlight text is often the first
example people want to see.
While I hope to see experimentation with implementations that try to limit
the impact on the DOM, I think <mark> or <span> wrapping of text nodes is
still the easiest to understand. In this approach, the actual wrapping is
easy. The difficult part is iteration.
Now, some quick background on node iteration.
I chose to use NodeIterator rather than TreeWalker for my dom-seek library
because it meant that the seek function could be stateless, support seeking
forward and backward, and still be able to return the number of characters
consumed by a seek. The desire to know whether to include the current
node's content in the seek count is fulfilled by NodeIterator's
"pointerBeforeReferenceNode". Essentially, a NodeIterator stores a point
before or after a node, rather than simply a current node.
However, using NodeIterator to traverse a Range is not really great. Since
it has a read only currentNode, the best that can be done is to start with
the commonAncestorContainer of the Range. Range has compareNode,
comparePoint, and isPointInRange. I have no idea how expensive these are.
Iterating all the nodes under the commonAncestorContainer doesn't feel
great to begin with. TreeWalker might be more appropriate since its
currentNode could be set to startContainer directly. TreeWalker also
appears to have consistent platform support.
All of this is complicated by the Range being able to point to offsets
within text nodes. For the purposes of highlighting with wrapper elements
it's necessary to split the boundary nodes. I think there are probably a
number of libraries for this, but I propose we write one under our repo.
We might also find that normalizing the endpoints of a Range in some
fashion is a helpful prerequisite. There is a library I found that does
this, but I found its algorithm terribly confusing. I put time into
rewriting it without dependencies. Despite some initial excitement, the
author never fully vetted and accepted my pull request:
https://github.com/webmodules/range-normalize/pull/2
In conclusion, I think there'd be value in bringing some functional
utilities into Apache Annotator for dealing with iteration, range
splitting, and range normalization, with the goal of providing a very
succinct and simple highlighter that looks like this:
```
for (const node of textNodes(range)) {
const mark = document.createElement('mark');
node.replaceWith(mark);
mark.appendChild(node);
}
```
Some care needs to be taken that whatever iteration we use is not
invalidated by the replacement of the text node with its wrapper.
The fact that a simple example like this is hard to produce is evidence of
the underlying complexity described in the above paragraphs. When I see
people wanting a simple highlighter what I hear is that they actually need
simple abstractions upon which to build a highlighter. The highlighter
itself should be easy. Often, highlighters that projects provide are not
shipped standalone or don't do exactly what the author needs (use spans
instead of marks, add a particular class, coalesce overlapping highlights
or not, etc). There is lots of room to do different things but being able
to simply get the nodes to be highlighted is the prerequisite task that
contains most of the complexity.
That's all (and probably way too much) for now. Finding all the tools for
all these things is a pain enough that I think we should have a
comprehensive set of such utilities in Apache Annotator, even if that risks
looking like a bit of NIH syndrome.
Unless anyone objects, I think I'll aim to ship libraries for these:
- Node iteration (https://github.com/tilgovi/dom-node-iterator)
- Tree walking (might not need a library if support is good)
- Range splitting
- Range normalization (see my pull request reference, above)
- Range iterating
- Text distance (https://github.com/tilgovi/dom-seek)
If anyone wants to start on any of the above, you're welcome to depend on
libraries that are outside Apache Annotator. In the case of libraries that
I've written, there is value to bringing them into Apache Annotator because
they are all written in ES6 but not packaged to be consumed as ES6.
Bringing them inside our repo means better code deduplication by tree
shaking in tools like rollup and webpack. They could be packaged as ES6
where they are, but if I'm going to spend time improving the packaging I
would rather just toss out the packaging and get the benefits of the
monorepo having all that build/test boilerplate done once for all of them.
Re: Just a simple example?
Posted by Sasha Goodman <em...@sashagoodman.com>.
Hope this is the right place to bring this up, but there is a simple
example in my early stab at Selectors. Instead of modifying the document
persistently, it merely observes the document and uses the browser's native
Selection API to select or highlight the text. The code is here:
https://github.com/predict-r/annotation-model
To address the original poster's question...
* a static HTML page with some text in it and
In my github repository there is a little tests.hmtl file with some text,
but you could use anything. Cut and paste the code from annotation-model.js
into the page using the console in DevTools
* a JSON structure being created locally in that page which represents the
annotations
Select some text with your mouse and then enter:
var ab = new AnnotationBuilder().highlight(); //takes current user
selection and builds an Annotation
var json = ab.toJSON(); // exports serialized version to JSON-LD
* an invocation of annotatorjs/annotator that takes the JSON and renders it
over the text
var ab2 = new AnnotationBuilder().fromJSON(json); //revives serialized version
ab2.result.target.toSelection(); //highlights the original selection
P.S. This afternoon I streamlined the TextQuoteSelector and
TextPositionSelector to work (in principle ) consistently with Randall
Leed's implementation that used NodeIterator and textContents.
On Wed, May 10, 2017 at 11:08 AM Benjamin Young <by...@bigbluehat.com>
wrote:
> Hey Richard,
>
>
> thanks for the quick answer. I wish I knew how to write up such a demo!
> I was hoping you could point me to an example from which I could learn ;)
>
>
> At this point it's still quite early for showing demos...but we're working
> quickly to make that happen!
>
>
> What we're focused on now is some foundational tooling for a) the whole
> project and b) the core functionality of Web Annotation Data Model <=> DOM
> "stuff" (ie. Selection API and DOM element-based highlights--built from
> <span>, <mark>, or similar).
>
>
> Are we talking about the same thing?
>
>
> More or less. :) If you mean building something similar to that *demo*,
> then yes, we're on the same page. :) However, ours will be using the Web
> Annotation Data Model [1] and as little code as we can possibly write to
> prove that the developer using the tools we are making can be used to do
> things in the DOM of a web page. For instance...
>
>
> I am not very familiar with the DOM Selection API, but I thought that
> it controls text selection, e.g. for copy-paste operations.
>
>
> We hope to have a demo specifically for a) quick, temporal highlighting
> using the DOM Selection API (no DOM-based elements and no persistence
> beyond the first selection--meaning, clicking on the page removes the
> selection).
>
>
> Later, we hope to have a copy-paste operation/thing that let's you
> copy/paste annotations between web pages. Similar to this earlier demo by
> Randall:
> http://run.plnkr.co/plunks/FJibLnSRElKG3k5s5jH9/
>
>
> Is that at all usable for rendering annotations?
>
>
> Only on the first page load. It's not meant (in this case) to be permanent.
>
>
> I mean, can you create multiple selections with different colorings and
> that
> don't go away when the user manually click-drags a new selection, e.g. to
> copy
> a piece of text?
>
>
> So. No. Not this Selection API-based stuff. However, later demos that use
> span or mark tags could certainly be used as a foundation for individually
> colored highlights.
>
>
> Also, does that actually support events such as on-mouse-over popups that
> would
> show additional information about an annotated piece of text?
>
>
> Again, no. :) It's not what the Selection API is about. Later demos with
> DOM persisted annotations, yes. :)
>
>
> I had a brief look of how annotatorjs rendered highlights, and at least
> in the version I tried, it was using span elements. Is that going to
> change now?
>
>
> Right. Annotation.js offered only DOM persisted annotations. If you wanted
> to do something more inventive (or server side!), you'd be on your own or
> have to desperately hack away at Annotator.js until you found the bits you
> needed or successfully removed the bits you didn't.
>
>
> Apache Annotator aims to build much more minimal more easily compose-able
> libraries that can be used in N number of idiosyncratic annotation tools.
>
>
> Hopefully that explains the objectives a bit better. :)
>
>
> Happy to answer other questions if you have them!
>
> Benjamin
>
>
> [1] https://www.w3.org/TR/annotation-model/
>
>
> --
>
> http://bigbluehat.com/
>
> http://linkedin.com/in/benjaminyoung
>
> ________________________________
> From: Richard Eckart de Castilho <re...@apache.org>
> Sent: Wednesday, May 10, 2017 10:03:55 AM
> To: dev@annotator.incubator.apache.org
> Subject: Re: Just a simple example?
>
> Hi Benjamin,
>
> thanks for the quick answer. I wish I knew how to write up such a demo!
> I was hoping you could point me to an example from which I could learn ;)
>
> Just to make sure again we have a similar thing in mind. I am looking
> for something similar to the brat embedding feature [1], just using
> annotatorjs instead of brat. Are we talking about the same thing?
>
> I am not very familiar with the DOM Selection API, but I thought that
> it controls text selection, e.g. for copy-paste operations. Is that
> at all usable for rendering annotations?
>
> I mean, can you create multiple selections with different colorings and
> that
> don't go away when the user manually click-drags a new selection, e.g. to
> copy
> a piece of text?
>
> Also, does that actually support events such as on-mouse-over popups that
> would
> show additional information about an annotated piece of text?
>
> I had a brief look of how annotatorjs rendered highlights, and at least
> in the version I tried, it was using span elements. Is that going to
> change now?
>
> Best,
>
> -- Richard
>
> [1] http://brat.nlplab.org/embed.html#embedding-event-example
>
> > On 10.05.2017, at 15:40, Benjamin Young <by...@bigbluehat.com> wrote:
> >
> > Hey Richard!
> >
> > Thanks for writing. There are exactly such things in the works. I've
> seen an in-progress demo from Randall (when we were hanging out at I
> Annotate) that uses fragment selectors to highlight (via the DOM Selection
> API).
> >
> > Here's W3C Note that defines the fragment selector format:
> >
> > http://w3c.github.io/web-annotation/selector-note/#frags
> >
> > We also discussed a demo pretty similar to what you describe that has a
> Web Annotation Data Model document shown in a textarea (perhaps) that is
> also used to highlight a thing on the page.
> >
> > At any rate, these exact things are in progress. :)
> >
> > If you'd like to write-up a demo page and a Web Annotation Data Model
> annotation (or a few) that highlight some stuff, that'd be a great help to
> demo on.
> >
> > We also plan to make the fragment selector thing (at least) usable on
> the http://annotator.apache.org/ site for demoing there.
> >
> > Thanks again for writing!
> >
> > Benjamin
>
>
Re: Just a simple example?
Posted by Benjamin Young <by...@bigbluehat.com>.
Hey Richard,
thanks for the quick answer. I wish I knew how to write up such a demo!
I was hoping you could point me to an example from which I could learn ;)
At this point it's still quite early for showing demos...but we're working quickly to make that happen!
What we're focused on now is some foundational tooling for a) the whole project and b) the core functionality of Web Annotation Data Model <=> DOM "stuff" (ie. Selection API and DOM element-based highlights--built from <span>, <mark>, or similar).
Are we talking about the same thing?
More or less. :) If you mean building something similar to that *demo*, then yes, we're on the same page. :) However, ours will be using the Web Annotation Data Model [1] and as little code as we can possibly write to prove that the developer using the tools we are making can be used to do things in the DOM of a web page. For instance...
I am not very familiar with the DOM Selection API, but I thought that
it controls text selection, e.g. for copy-paste operations.
We hope to have a demo specifically for a) quick, temporal highlighting using the DOM Selection API (no DOM-based elements and no persistence beyond the first selection--meaning, clicking on the page removes the selection).
Later, we hope to have a copy-paste operation/thing that let's you copy/paste annotations between web pages. Similar to this earlier demo by Randall:
http://run.plnkr.co/plunks/FJibLnSRElKG3k5s5jH9/
Is that at all usable for rendering annotations?
Only on the first page load. It's not meant (in this case) to be permanent.
I mean, can you create multiple selections with different colorings and that
don't go away when the user manually click-drags a new selection, e.g. to copy
a piece of text?
So. No. Not this Selection API-based stuff. However, later demos that use span or mark tags could certainly be used as a foundation for individually colored highlights.
Also, does that actually support events such as on-mouse-over popups that would
show additional information about an annotated piece of text?
Again, no. :) It's not what the Selection API is about. Later demos with DOM persisted annotations, yes. :)
I had a brief look of how annotatorjs rendered highlights, and at least
in the version I tried, it was using span elements. Is that going to change now?
Right. Annotation.js offered only DOM persisted annotations. If you wanted to do something more inventive (or server side!), you'd be on your own or have to desperately hack away at Annotator.js until you found the bits you needed or successfully removed the bits you didn't.
Apache Annotator aims to build much more minimal more easily compose-able libraries that can be used in N number of idiosyncratic annotation tools.
Hopefully that explains the objectives a bit better. :)
Happy to answer other questions if you have them!
Benjamin
[1] https://www.w3.org/TR/annotation-model/
--
http://bigbluehat.com/
http://linkedin.com/in/benjaminyoung
________________________________
From: Richard Eckart de Castilho <re...@apache.org>
Sent: Wednesday, May 10, 2017 10:03:55 AM
To: dev@annotator.incubator.apache.org
Subject: Re: Just a simple example?
Hi Benjamin,
thanks for the quick answer. I wish I knew how to write up such a demo!
I was hoping you could point me to an example from which I could learn ;)
Just to make sure again we have a similar thing in mind. I am looking
for something similar to the brat embedding feature [1], just using
annotatorjs instead of brat. Are we talking about the same thing?
I am not very familiar with the DOM Selection API, but I thought that
it controls text selection, e.g. for copy-paste operations. Is that
at all usable for rendering annotations?
I mean, can you create multiple selections with different colorings and that
don't go away when the user manually click-drags a new selection, e.g. to copy
a piece of text?
Also, does that actually support events such as on-mouse-over popups that would
show additional information about an annotated piece of text?
I had a brief look of how annotatorjs rendered highlights, and at least
in the version I tried, it was using span elements. Is that going to change now?
Best,
-- Richard
[1] http://brat.nlplab.org/embed.html#embedding-event-example
> On 10.05.2017, at 15:40, Benjamin Young <by...@bigbluehat.com> wrote:
>
> Hey Richard!
>
> Thanks for writing. There are exactly such things in the works. I've seen an in-progress demo from Randall (when we were hanging out at I Annotate) that uses fragment selectors to highlight (via the DOM Selection API).
>
> Here's W3C Note that defines the fragment selector format:
>
> http://w3c.github.io/web-annotation/selector-note/#frags
>
> We also discussed a demo pretty similar to what you describe that has a Web Annotation Data Model document shown in a textarea (perhaps) that is also used to highlight a thing on the page.
>
> At any rate, these exact things are in progress. :)
>
> If you'd like to write-up a demo page and a Web Annotation Data Model annotation (or a few) that highlight some stuff, that'd be a great help to demo on.
>
> We also plan to make the fragment selector thing (at least) usable on the http://annotator.apache.org/ site for demoing there.
>
> Thanks again for writing!
>
> Benjamin
Re: Just a simple example?
Posted by Richard Eckart de Castilho <re...@apache.org>.
Hi Benjamin,
thanks for the quick answer. I wish I knew how to write up such a demo!
I was hoping you could point me to an example from which I could learn ;)
Just to make sure again we have a similar thing in mind. I am looking
for something similar to the brat embedding feature [1], just using
annotatorjs instead of brat. Are we talking about the same thing?
I am not very familiar with the DOM Selection API, but I thought that
it controls text selection, e.g. for copy-paste operations. Is that
at all usable for rendering annotations?
I mean, can you create multiple selections with different colorings and that
don't go away when the user manually click-drags a new selection, e.g. to copy
a piece of text?
Also, does that actually support events such as on-mouse-over popups that would
show additional information about an annotated piece of text?
I had a brief look of how annotatorjs rendered highlights, and at least
in the version I tried, it was using span elements. Is that going to change now?
Best,
-- Richard
[1] http://brat.nlplab.org/embed.html#embedding-event-example
> On 10.05.2017, at 15:40, Benjamin Young <by...@bigbluehat.com> wrote:
>
> Hey Richard!
>
> Thanks for writing. There are exactly such things in the works. I've seen an in-progress demo from Randall (when we were hanging out at I Annotate) that uses fragment selectors to highlight (via the DOM Selection API).
>
> Here's W3C Note that defines the fragment selector format:
>
> http://w3c.github.io/web-annotation/selector-note/#frags
>
> We also discussed a demo pretty similar to what you describe that has a Web Annotation Data Model document shown in a textarea (perhaps) that is also used to highlight a thing on the page.
>
> At any rate, these exact things are in progress. :)
>
> If you'd like to write-up a demo page and a Web Annotation Data Model annotation (or a few) that highlight some stuff, that'd be a great help to demo on.
>
> We also plan to make the fragment selector thing (at least) usable on the http://annotator.apache.org/ site for demoing there.
>
> Thanks again for writing!
>
> Benjamin
Re: Just a simple example?
Posted by Benjamin Young <by...@bigbluehat.com>.
Hey Richard!
Thanks for writing. There are exactly such things in the works. I've seen an in-progress demo from Randall (when we were hanging out at I Annotate) that uses fragment selectors to highlight (via the DOM Selection API).
Here's W3C Note that defines the fragment selector format:
http://w3c.github.io/web-annotation/selector-note/#frags
We also discussed a demo pretty similar to what you describe that has a Web Annotation Data Model document shown in a textarea (perhaps) that is also used to highlight a thing on the page.
At any rate, these exact things are in progress. :)
If you'd like to write-up a demo page and a Web Annotation Data Model annotation (or a few) that highlight some stuff, that'd be a great help to demo on.
We also plan to make the fragment selector thing (at least) usable on the http://annotator.apache.org/ site for demoing there.
Thanks again for writing!
Benjamin
--
http://bigbluehat.com/
http://linkedin.com/in/benjaminyoung
________________________________
From: Richard Eckart de Castilho <re...@apache.org>
Sent: Wednesday, May 10, 2017 9:09:56 AM
To: dev@annotator.incubator.apache.org
Subject: Just a simple example?
Hi all,
does anybody have a simple example of annotatorjs or Apache Annotator
that would work without a server-side storage?
I am imagining something like
* a static HTML page with some text in it and
* a JSON structure being created locally in that page which represents the annotations
* an invocation of annotatorjs/annotator that takes the JSON and renders it over the text
As an outcome, one would see parts of the texts highlighted and on-mouse-over information about the annotations would be displayed.
For this simple example, editing these annotations wouldn't even be required.
If anybody could point me to such an example, that would be great!
Cheers,
-- Richard