Annotation Module
The annotation module is the core of the ResourceContracts. This living wiki document attempts to summarize the concept and working of the annotation module.
annotator.js for annotating text based documents
annotorious.js for the annotating pdf, and used as annotatos.js plugin
Each annotation belongs to one annotation category. There are 95 such categories defined here. Each of the category belong to the topic (used to call cluster at several instances in the past).
Several issues have been raised about linking annotation to multiple pages. Once such good use-case is from https://github.com/NRGI/resourcecontracts.org/issues/71
Eg. Art 7 says "Company must have an EIA". Art. 50 says "Company must pay a fine if it does not comply with EIA".
I want just one annotation that says: "The company must prepare an EIA and will be fined if it doesn't comply with it".
But I want the annotation to link physically to Arts 7 and 50.
Topic contains multiple categories. Each category may have only one annotation. Each annotation may be linked to multiple pages and it will use the same annotation-text throughout.
"Environment" Topic has 4 categories viz
- Environmental impact assessment and management plan
- Environmental monitoring
- Water use
- Environmental protection
Say "Environment Protection" has 4 annotations linked to 3 pages.
This should be the structure of the annotation.
| Topic | Category | Annotation | Article-reference | Page |
|---|---|---|---|---|
| Environment | Environmental protection | annotation-text-1-here | Art 1 | 1 |
| Art 10 | 1 | |||
| Annex-1 | 2 | |||
| 10 |
In the database, the structure should be something like this
| Id | Topic | Category | Annotation |
|---|---|---|---|
| 1 | Environment | Environmental Protection | annotation-text-1-here |
| Annotation-Id | Article-reference | Page |
|---|---|---|
| 1 | Art 1 | 1 |
| 1 | Art 10 | 1 |
| 1 | Annex-1 | 2 |
| 1 | 10 |
Once the annotation is structured in above model, we can then show the annotations in the list as follows. Page number/Article-reference will be linked to specific annotation locations in the content (either text or pdf).
Environment
- Environment Protection
- annotations-text-1-here
- Pg 1 (Art 1, Art 10), 2 (Annex-1), 10
Or we could now present this as follows
Environment
- annotations-text-1-here
- Environment Protection
- Pg 1 (Art 1, Art 10), 2 (Annex-1), 10
Here's how annotation is added/inserted to the document.
Add first annotation in page 1
Choose "Environment Protection" and other info - Annotation Text and Article Reference.
Add new annotation in the same page
Select "Environment Protection", the text from "Environmental Protection" will be pulled from previously entered annotation. The text could be edited from the second annotation as well. The edited Annotation-text will be reflected in all the annotations for that category.
Now if you look at page 1, you will see link to both the pages where you have annotated.
Now you may add any number of annotations under "Environmental Protection" and all the pages and article-reference (annotated under that annotation category) will be listed with links.
Here's how annotations are viewed in a list.
Here's how annotation is viewed in the document.
Annotation - Any note that can be added to the text or pdf content and contains different metadata like page, Article Reference.
Annotation Text - The content part of the annotation which is written during annotation creation.
Article Reference - Annotation may be added to different articles of the content, to different annexes of different pages. These are called Article Reference (used to be called Section before)
Category - Each of the added annotation belongs to one and only one category. There are 95 categories defined so far.
Topic - Each of the category belongs to one of these topics. Topics group the categories. There are 6 topics defined, which group 95 categories.
Annotation box - the yellow rectangular marker that locates each annotation on the PDF version of the contract.
Parent Annotation - There is no concept of parent annotation now. There will be only one "Annotation Text" for each category. This was the case when we had different annotation data model before.