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

[Randall Leeds]

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/71ed2d34/attachment-0004.html>