Marginalia Update and Feature Upgrade for Plone 4.1

A requirement for the Bungeni-Plone system, is that it should be possible to 
annotate and amend documents through the web. This will be done via the product 
Marginalia installed on the Plone content management system. Here 
http://www.geof.net/code/annotation/demo/ you can see a demo of the 
“annotation” functionality

Marginalia consists of a javascript client which runs on the browser, and which 
provides the UI and rendering of annotations and amendments as overlays, and of 
a server component, which receives and stores new annotations and amendments 
from the client and sends existing annotations and amendments upon request. The 
communication between the client and the server is defined in the marginalia 
client implementation, and uses an ATOM feed for the transfer of annotations. 

Current Status

An implementation of Marginalia for Plone 3 exists at: 
http://bungeni-portal.googlecode.com/svn/Marginalia/

The following key requirements are currently met by the existing Marginalia 
Product.

Annotatable documents are identified in Plone using the documents UID;
Annotatabledocuments show two tabs: 
comment (allow comments only)  
amend (allow comments, insertions, replacements and deletions);
Annotatable documents are stored as Archetype-based objects in Plone, and have 
the normal schema, security and workflow characteristics of Archetype-based 
content;
Annotations and Amendments can reference other Plone content using the 
ATReferenceBrowserWidget which is made be available to the marginalia 
javascript client. It is possible to incorporate rich content objects within 
annotations by reference;
The UI makes available the following features and functionality:
filtering by user and group;
for amendments, filtering by amendment type;
private and public status of amendments and annotations (set by the user);
text search filter (the filter is carried out on public amendments/annotations;
amendments and annotations can be deleted by the user;
super user view - the super user can see all public amendments/annotations.
For each amendment/annotation the super user can change the state of the 
amendment/annotation by either accepting, declining or setting it to pending 
state.

Requirements / TO DO 

Task 1 Upgrade Marginalia to Plone 4.1

Bungeni-Plone is currently on Plone 4.1 and uses the updated Plone 4 style 
build for setting up Plone.- A partial upgrade of Marginalia for Plone 4 can be 
accessed here: 
http://code.google.com/p/bungeni-portal/source/browse/Marginalia/branches/sterch
-issue740. Marginalia must be update to support the same version of Plone 4 
being used by Bungeni Plone (the Bungeni Plone buildout can be accessed here: 
http://bungeni-portal.googlecode.com/svn/plone.buildout/trunk , installation 
instructions are here : 
http://code.google.com/p/bungeni-portal/wiki/Install_Plone_Fabric )

Task 2 make “Marginalia” a feature of Plone documents.

Currently Annotatable documents are identified in Plone using the documents UID 
and are created as documents of type “Annotatable 
Document”.”Marginalia” has to become a feature that can be used across 
all Plone documents rather than creating a specific type of document.

If an owner of a document wants to make a document available for 
comment/amendment he will have to choose between the two alternative options:
“open document for comment”
“open document for amendment”.

The action of selecting “open document for comment/amendment” will force 
the creation of a new “version” of the Plone document.

The document will have status “opened for comments/amendments” and will be 
accessible:
in comment/amend mode for the  users who have the right to see the document;
in comment/amend mode only also for the owner, who will not able to edit the 
document while it is in this state “opened for comments/amendments”.

Task 3 Create versions of Marginalia annotations.

The owner of a document may set a date when the document will be “closed for 
comments/amendments”  or the owner may just use the workflow option “close 
for comments/amendments”.

The action “close for comments/amendments” will force the creation of a new 
version that takes a snapshot of all Marginalia annotations/amendments 
associated with the document.

The document will then have status “closed for comments/amendments” and 
will be accessible:
in view mode only for the users who have the right to see the document;
with super-user rights for the owner who can accept/reject 
comments/amendments” as well as to add amendments.

Once the owner has completed the revision of comments/amendments he will have 
the option to set the document to “new version with annotations” or “new 
version with amendments”.

The action “new version with annotation/amendments” will force the creation 
of an new version that takes a snapshot of all Marginalia 
annotations/amendments. 

The system must allow browsing the different versions of the documents and see 
the full marginalia comment / amendment view on each version of the document.

e.g. If the document had 5 marginalia comments in version 1, and then further 2 
marginalia comments were added by the owner and version 2 generated - browsing 
to version 1 of the document should show 5 marginalia comments , and browsing 
to version 2 should show 7 marginalia comments. 

Task 4 Create new document that incorporate proposed changes

Currently in Marginalia annotations/changes are recorded separately from the 
document being annotated. These change annotations are “overlaid” onto the 
annotated document at runtime using the Marginalia javascript library i.e. the 
change annotations are rendered onto the DOM of the html document.

Once the “new version with annotation/amendments” is finalised (as 
described in Task 3), it should be possible to create a new version of the 
Plone document itself that actually incorporates all the changes proposed to 
the document in the Marginal amendments and comments. This will be done by the 
"consolidate into a new version" action.

The “consolidate into a new version” action will:

Merge all the marginalia amendments into the content of the Plone document , 
for example, if a marginalia amendment was for -insert- a word "hello" between 
the words "new" and "world" in paragraph 3 sentence 1 of the body, the 
"consolidate..."  action will incorporate the word "hello" into the position 
specified into the physical body of the document. This action will create a new 
version of the Plone document
In the new version of the document there will be no marginalia changes shown as 
these changes have been merged into the document. To view the marginalia 
amendments changes in the document, the user will have to browse to an older 
version of the document prior to when the "consolidate into a version" action 
was applied.
A check is required , PRIOR to the "consolidate into a new version" action : 
Overlapping changes must not be present in the text, if they exist a warning 
should be given and require that those changes need to be resolved (manually by 
the super-user) before consolidation into a new document can take place. An 
example of an overlapping change is when a user deletes a sentence, and another 
user proposes a change to the same sentence, there are other similar scenarios 
possible for overlapping changes.

At this point it will be possible to begin afresh a new cycle of 
“comment/amendment”.

General Guidelines

The Marginalia js library has been updated 
(http://code.google.com/p/marginalia/source/list). These latest updates should 
be included in the Plone Marginalia package.

Integration with existing Plone content types should be non-intrusive, it 
should be sufficient to apply the required marker interfaces and document 
actions via ZCML.
Original issue reported on code.google.com by ashok.ha...@gmail.com on 27 Jun 2012 at 9:07
BenoitTalbot / bungeni-portal

Marginalia Update and Feature Upgrade for Plone 4.1 #758
