Welcome | Get started | Dive into Lino | Contribute | Reference

comments : The comments framework

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

This is a tested document. The following instructions are used for initialization:

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

Comments

class lino.modlib.comments.Comment

Django model to represent a comment.

user

The author of the comment.

owner

The topic this comment is about. This field is a Generic Foreign Key, i.e. users can basically comment on any database object. It is however the application developer who decides where comments can be created and how they are being displayed.

The owner of a comment is always 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.

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.

>>> from lino.core import constants
>>> rt.show(comments.RecentComments, display_mode=constants.DISPLAY_MODE_CARDS)
... 
Previewbreaking

...
PreviewStyled comment <span>pasted from word!</span>
class lino.modlib.comments.CommentsByX
class lino.modlib.comments.CommentsByType
class lino.modlib.comments.CommentsByRFC

Shows the comments for a given database object.

slave_summary
get_table_summary(cls, obj, ar)

The summary view for this table.

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 whose instances can be 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.

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)

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.

get_comments_filter(cls, user):

Return the filter to be added when a given user requests comments about commentables of this type.

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 on your Commentable in order to write filter conditions based on the owner of the comment.

Utilities

lino.modlib.comments.comments_by_owner()