How the comment system works
This section is incomplete. Expanded documentation on how ucomment works will be coming soon.
How a web visitor leaves a comment
Visitors to the site must click on the side bar, next to the node they wish to comment on.
Start a comment by clicking on the blue speech bubble.
Once they have typed in their comment, they must preview it before submitting it. They can click the Submit your comment button once they are satisfied with their comment’s accuracy.
Visitors must first preview their comment before submitting it.
Server processing after a web visitor leaves a comment
The Django application will execute the submit_and_store_comment(...) function after a visitor has clicked the Submit your comment button. Quite a bit of processing takes place on the web server from this point.
The comment is compiled to HTML using the RST source entered by the visitor.
A CommentPoster entry will be created in the Django database, using the visitor’s email address and name. If an email address was not submitted, then an entry is still created using the user’s IP address and user agent string.
The reStructuredText (RST source code for the document is updated at the point where the comment was created.
A reStructuredText directive is added to the document’s source as shown in the figure.
The 6-digit code is a comment reference, while the 2-letter code is the comment node. More details on these are provided below.
If you do not like your document’s source being altered, then ucomment may not be suitable for you. There are two advantages to this approach though - it allows you to trivially delete or move a visitor’s comment to another part of the document.
Of course we also must store the actual comment in the database, which is defined by the Comment class in the Django models.py file.
This object has 3 foreign keys: a CommentPoster object, already discussed above; a CommentReference object and a Page object.
The CommentReference object stores the name of the RST source file, and the line number for the node which was commented on. It also stores the type of node (e.g. paragraph, title, list_item, image, literal_block), and the distributed version control system (DVCS) revision number for the file.
In fact the CommentReference object, coupled with the DVCS is what makes this entire application work.
For example: a user might load a webpage, commenting on a certain paragraph. In the mean time, the author commits a new version of the page, which changes the line number of the paragraph the user is commenting on. If the user submits the comment, and we only used line numbers to track the comment location, then is a risk the comment will attach to the wrong paragraph. (And of course all existing comments below the current one will also have to have their line numbers updated.)
Comment references allow the comment to be successfully made to the correct paragraph, since we can always revert the state of the document to the version that the web visitor made the comment (we checkout an earlier revision). Then we rely on the DVCS to merge previous and current revisions.
Below is a screenshot of the Django administration page for the CommentReference objects, illustrating the various types of nodes, their line number and their revision changeset number.
It is highly recommended that you use the built-in Django admin interface to view and understand how ucomment works. You can see all comments, document pages, people making the comments, etc.
You will need to edit your Django project (not application) urls.py and settings.py files to enable the admin interface.