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

[Jan Paul Posma]

Yep, that all makes a lot of sense. Thanks for the pointers. I'll find
some time soon to implement that, and also get rid of some
Factlink-specific stuff to make it more understandable for other
developers. :-)

On Mon, May 4, 2015 at 2:44 PM, Randall Leeds <tilgovi at hypothes.is> wrote:
> 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.
>>>
>>
>