[annotator-dev] Port of Factlink's paragraph icons to Annotator.js

Mon May 4 21:44:24 UTC 2015

Rough sketch of how I would want to use this as an application developer:

var app = new annotator.App();
app.include(annotatorParagraphs);
app.include(function (registry) {
  return {
    createFromParagraph: function (p) {
       var targetText = p.textContent;
       var annotation = {
           target: // mySerializedParagraphIdentifier(p);
           // add other data here
       };
       app.annotations.create(annotation);
    }
  }
});

On Mon, May 4, 2015 at 2:40 PM, Randall Leeds <tilgovi at hypothes.is> wrote:

> Ahh, I should have looked closer. I see in your index.html
> "app.include(window.paragraphUi);"
>
> It would certainly be nicer if this were packaged as a module so that it
> is possible to import it without it modifying the global object, but that's
> a nice-to-have.
>
> To answer your question, I think you do not want to expect the storage
> object. You want to fire hooks. Grab a reference to the application in your
> start hook and then use it later as follows:
>
>     app.runHook('create', [annotation])
>
> Probably, some of these will graduate to the level of deserving their own
> API, but we want to move slowly on adding API.
>
> However, I will say that these hooks are for creating annotations when
> your code is essentially about creating targets for potentially annotating.
> It is best for extensibility that you not encode assumptions about the
> structure of annotations into your hooks since that is where application
> developers need to have freedom. As such, it's far better to fire your own
> hooks providing just the data you need to and let application developers
> listen to those hooks and decide how to include that information into a new
> annotation and when to call the create hook themselves.
>
> If I were you, I would:
>
> - Expose _onClick in ParagraphIconButtonContainer to be public "onClick"
> and configurable.
>
> - Make sure this option is accessible from the way you construct the
> component in the Annotator "start" hook.
>
> - When you construct the component, construct it with an onClick that
> calls `app.runHook('myCustomHook', [data])`.
>
> - Your data should be about the paragraph button that was clicked and the
> paragraph it corresponds to. In particular:
>
>   - Don't make assumptions about how text should be extracted, or if it
> needs to be at all.
>
>   - Don't make assumptions about how to address that paragraph in a
> persistent way or attempt to provide that information.
>
>   - Do make enough of the raw event data available that the application
> developer can do these things for themselves.
>
> Thanks, JP. This looks great and I'd love to help you make this more
> accessible to the community.
>
>
>
>
>
> On Mon, May 4, 2015 at 2:27 PM, Randall Leeds <tilgovi at hypothes.is> wrote:
>
>> Thanks, JP!
>>
>> On Sun, May 3, 2015 at 10:36 PM, Jan Paul Posma <janpaul at factlink.com>
>> wrote:
>>
>>> For those of you who are interested in icons next to paragraphs that
>>> automatically integrate with a host website (paragraph detection,
>>> colour/size adjustment, style/script isolation, etc), I ported our
>>> code from Factlink to Annotator.js.
>>>
>>
>> Aside from getting jQuery from annotator.util, does this use Annotator at
>> all or implement its extension module pattern?
>>
>> http://docs.annotatorjs.org/en/latest/module-development.html
>>
>>
>>> Code: https://github.com/Factlink/annotator-paragraph-icons
>>> Demo: http://factlink.github.io/annotator-paragraph-icons/
>>>
>>> Main advantages are that this interface is easier to discover, could
>>> be made to work well on mobile (show icon when touching a paragraph),
>>> and could be used to group annotations instead of highlights or a more
>>> complicated sidebar as Hypothes.is has (though this grouping is
>>> currently not implemented).
>>>
>>> Only thing missing is the actual saving of the annotation, that seemed
>>> a bit tricky for me to figure out, and not really documented. If
>>> someone from the Annotator team could fill this in, that would be
>>> awesome:
>>> https://github.com/Factlink/annotator-paragraph-icons/blob/784bf4c60db28e0612d2ae711abcb0c1b9f90972/app/icon_buttons.coffee#L136
>>>
>>
>> The `start` hook receives the `App` as an argument.
>>
>> It's probably reasonable to expect that instance to have a property,
>> `annotations` conforming to the Storage interface. The details of this are
>> not 100% settled and the robustness of using the application instance to
>> get these properties is not known yet, until we see more applications built.
>>
>> The absolute best thing you can do to start with is to make sure your
>> code has a public interface. One should be able to instantiate it, likely
>> given a root element under which to act, and it should provide some way for
>> the user to be notified about events that your code handles, for instance
>> by providing an `onClick` option to the constructor.
>>
>> From there, wrapping it as an Annotator module and including it in an
>> application should be straightforward. However, crucially, the core of what
>> you've done becomes independent of Annotator or any other annotation
>> application/framework.
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/annotator-dev/attachments/20150504/ea2f6506/attachment-0004.html>