`comments` : The comments framework¶

The lino.modlib.comments plugin adds a framework for handling comments.

This article is a general description, see also comments (comments in Noi) and comments (comments in Avanti).

Side note: Code snippets (lines starting with >>>) in this document get tested as part of our development workflow. The following initialization snippet tells you which demo project is being used in this document.

>>> from lino import startup
>>> startup('lino_book.projects.noi1e.settings.demo')
>>> from lino.api.doctest import *

Don’t read this ¶

>>> for cls in comments.Comment.mro():
...     edm = cls.__dict__.get('extra_display_modes', None)
...     if edm is not None and DISPLAY_MODE_SUMMARY in edm:
...         print(cls)

>>> for cls in comments.Comments.mro():
...     ddm = cls.__dict__.get('default_display_modes', None)
...     if ddm is not None and DISPLAY_MODE_SUMMARY in ddm:
...         print(cls)

>>> for cls in comments.Comments.mro():
...     edm = cls.__dict__.get('extra_display_modes', None)
...     if edm is not None and DISPLAY_MODE_SUMMARY in edm:
...         print(cls)

>>> DISPLAY_MODE_SUMMARY in comments.RepliesByComment.extra_display_modes
False

Comments ¶

class lino.modlib.comments.Comment¶

The database model to represent a comment.

user¶: The author of the comment.

owner¶

The discussion topic this comment is about.

The owner of a comment must be an instance of a subclass of Commentable.

body¶: The full body text of your comment.

short_preview¶: The first paragraph of your body.

emotion¶: The emotion of this comment.

published¶: When this comment has been published. A timestamp.

The Comment.owner field is a generic foreign key, i.e. theoretically users can discuss about any database object, but actually the application developer decides which database models can serve as topics for commenting by

having these database models inherit from Commentable and
adding the CommentsByRFC panel to their detail layout.

class lino.modlib.comments.Comments¶

show_published¶: Whether to show only (un)published comments, independently of the publication date.

start_date¶: Hide comments before this date.

end_date¶: Hide comments after this date.

observed_event¶: Which event (created, modified or published) to consider when applying the date range given by start_date and end_date.

class lino.modlib.comments.AllComments¶: Show all comments.

class lino.modlib.comments.MyComments¶: Show the comments posted by the current user.

class lino.modlib.comments.RecentComments¶: Show the most recent comments that have been posted on this site.

class lino.modlib.comments.CommentsByX¶

class lino.modlib.comments.CommentsByType¶

class lino.modlib.comments.CommentsByRFC¶: Shows the comments for a given database object.

class lino.modlib.comments.ObservedTime¶

class lino.modlib.comments.CommentEvents¶: The choicelist with selections for Comments.observed_event.

class lino.modlib.comments.PublishComment¶
Publish this comment.

class lino.modlib.comments.PublishAllComments¶
Publish all comments.

Emotions ¶

class lino.modlib.comments.Emotions¶: The list of available values for the Comment.emotion field.

>>> rt.show("comments.Emotions")
========== ========== ========== =============
 value      name       text       Button text
---------- ---------- ---------- -------------
 ok         ok         Okay
 agree      agree      Agree      ✅
 disagree   disagree   Disagree   ❎
========== ========== ========== =============

Comment types ¶

class lino.modlib.comments.CommentType¶: The CommentType model is not being used in production, one day we will probably remove it.

class lino.modlib.comments.CommentTypes¶

The table with all existing comment types.

This usually is accessible via the Configure menu.

Commentable ¶

class lino.modlib.comments.Commentable¶

Mixin for models that are commentable, i.e. the rows of which can become discussion topic of comments.

create_comment_template = _("Created a new {model}.")

The template to use for the comment that gets generated automatically when an end user creates an instance of this.

Set this to None if you don’t want Lino to generate any comment when an instance gets created.

add_comments_filter(cls, qs, user)¶

Add filters to the given queryset of comments, requested by the given user.

Return None to not add any filter. Otherwise the return value should be a django.db.models.Q object.

Default behaviour is that public comments are visible even to anonymous while private comments are visible only to their author and to PrivateCommentsReader.

You can override this class method to define your own privacy settings.

Usage example in lino_xl.lib.groups.Group and lino_xl.lib.tickets.Ticket.

If you override this method, you probably want to define a django.contrib.contenttypes.fields.GenericRelation field on your model in order to write filter conditions based on the owner of the comment.

get_rfc_description(self, ar)¶

Return a HTML formatted string with the description of this Commentable as it should be displayed by the slave summary of CommentsByOwner.

It must be a string and not an etree element. That’s because it usually includes the content of RichTextField. If the API required an element, it would require us to parse this content just in order to generate HTML from it.

on_commented(self, comment, ar, cw)¶: This is automatically called when a comment has been created or modified.

get_comment_group(self)¶

(Currently not used)

Return either None or a database object that represents the commenting group where this comment is being done.

If not None, the object must have a field ref which will be shown in the summary of RecentComments.

comments : The comments framework¶

Don’t read this¶

Comments¶

Emotions¶

Comment types¶

Commentable¶