Store annotations relative to content, not content display

[danohu]

• add nid field and index to database
• allow query by nid through store API
• configure store plugin to query by nid and ignore URI
• create a plugin for node-based annotation (annotator_drupalnode.js)

DESIGN

We store the appropriate node id (nid) with every annotation. We override the
annotation API to search by nid rather than URL. We also manipulate the url to
be always the path to the node detail page.

SETUP

• in admin/config/content/annotator, enable the DrupalNode plugin
• in admin/config/content/annotator, set Annotator element to ".node :has(>p)"
  [this selects the div immediately surrounding the node content. Any other selector should
  also be fine, provided the markup within it will be identical on both node and index pages]
• there is a new field in the annotation module. So you will need to either reinstall, or
  manually add the nid field

[danohu]

oops, looks like I broke some stuff while separating out my code. hold off testing, update is on its way.

[paolomainardi]

I think that is better to use a check_plain() on this data.

[danohu]

Thanks for the comment, Paolo.

I don't think we need sanitization here, but I could well be wrong.

In this particular line, nid is possibly used in a database query, but not returned in html. So check_plain won't do anything useful. And we're using the drupal database API, which does its own escaping/sanitization of query parameters.

Annotations are stored in the db without any html escaping. but when they are retrieved they go through drupal_json_output, which escapes HTML. [at least, if I put html tags into a comment, they come out displayed as text rather than interpreted as HTML].

[paolomainardi]

You are absolutely right, PDO already escapes arguments, sorry for the wrong suggestion.

[tanius]

Tested all this now, and basically got it to work. Nice work! :) I added a pull request with some small changes back, which you can merge into your branch. Before I merge this into master, here are some remaining issues that I found:

• The annotation search API function is called multiple times on page load. 5 times on one page, 20 times on another ... don't know yet what influences this, but it seems to slow page load down considerably. I mean the GET requests to sth. like https://edgeryders.localdomain/annotation/api/search?nid=3028
• Probably related to the above, one stored annotation lead to marking multiple selections of text. But this can wait, let's just fix the above issue and, if it does not also fix this, see over time what pattern it has.
• We also want to be able to annotate comments. If you can't find a single jQuery selector for the "node plus comments" block, I will modify the template to create one. It also means storing with two columns: entity_type (node, comment, user etc.) and eid (entity id). You can watch this technique in other Drupal tables as well. It also needs changes to the annotator_drupalnode.js code for determining the ID to store, obviously.
• It's probably better to not store any URL into the annotation.uri field in case we have a node / comment ID instead. To avoid redundancy in the database. I would even suggest to remove the uri column completely, since that's no semantic / Drupal-ish way to store things.

[danohu]

@tanius
"The annotation search API function is called multiple times on page load. 5 times on one page, 20 times on another ... don't know yet what influences this, but it seems to slow page load down considerably."

Is this multiple calls to the SAME search url, or to different ones?
What currently happens is that every entry on a page gets its own instance of the annotator. These each make their own calls to the API.
So:

• if you are on a node detail page, you'll get one call to the search URL
• if you are on a page with multiple nodes, you'll get one call for each node on the page:
  https://edgeryders.localdomain/annotation/api/search?nid=3028
  https://edgeryders.localdomain/annotation/api/search?nid=3027
  https://edgeryders.localdomain/annotation/api/search?nid=3026

[tanius]

@danohuiginn It's multiple calls to the same URI, like:

https://edgeryders.localdomain/annotation/api/search?nid=3028
https://edgeryders.localdomain/annotation/api/search?nid=3028
https://edgeryders.localdomain/annotation/api/search?nid=3028

Could it have to do with the jQuery selector of the annotator plugin applying multiple times? Just a wild guess though.

[tanius]

Found the reason for the multiple calls to annotation/api/search. I had used .node :has(>p) for the annotator config as you proposed above, but this selected multiple tags on single-node pages (all .node descendants that have a p child). Each result meant one object in Annotator._instances and one call to annotation/api/search.

Now I use .node .node-content, which works fine for the Drupal Commons template on edgeryders.eu. The idea is seemingly to select a single descendant of .node; when using an ancestor of it, the current code will fail.

So, this one's fixed. I'll put it into the docs.

[tanius]

Merged what we have so far to. It's working as is, so I'll put in enhancement type issues for the fine tuning related above (no uri field, and also allowing to annotate comments).

Also, I have put @danohuiginn's setup instructions into the Open Ethnographer manual.