django-comments-dab 2.0.0

Requirements:

1. django>=2.1

2. djangorestframework # only for the API Framework

3. Bootstrap 4.1.1

Installation:

Installation is available via pip

$ pip install django-comments-dab

or via source on github

$ git clone https://github.com/radi85/Comment.git
$ cd Comment
$ python setup.py install

Comment Settings and urls:

1. Add comment to installed_apps in the settings.py file. It should be added after django.contrib.auth.

2. LOGIN_URL shall be defined in the settings.

settings.py should look like this:

INSTALLED_APPS = (
    'django.contrib.admin',
    'django.contrib.auth',
    ...
    'comment',
    ..
)

LOGIN_URL = 'login'  # or actual url

In urls.py:

urlpatterns = patterns(
    path('admin/', admin.site.urls),
    path('comment/', include('comment.urls')),
    ...
    path('api/', include('comment.api.urls')),  # only required for API Framework
    ...
)

Migrations:

Migrate comment app:

$ python manage.py migrate comment

Step 1 - Connecting comment model with the target model

In models.py add the field comments as a GenericRelation field to the required model.

PS: Please note that the field name must be comments NOT comment.

E.g. Post model, as shown below:

from django.contrib.contenttypes.fields import GenericRelation

from comment.models import Comment

class Post(models.Model):
    author = models.ForeignKey(User)
    title = models.CharField(max_length=200)
    body = models.TextField()
    # the field name should be comments
    comments = GenericRelation(Comment)

Step 2 - Adding template tags:

render_comments tag uses 2 required and 1 optional args:

1. Instance of the targeted model. (Required)

2. Request object. (Required)

3. oauth. (optional - Default is false)

1. Basics usage:

include_static this tag will include CSS and javascript files,

include_bootstrap tag is for bootstrap-4.1.1, if it’s already used in the project, get rid of this tag.

In the template (e.g. post_detail.) add the following template tags where obj is the instance of post model.

{% load comment_tags %}  {# Loading the template tag #}
{% render_comments obj request %}  {# Render all the comments belong to the passed object "obj" #}

2. Advanced usage:

{% load comment_tags %}  {# Loading the template tag #}

{% render_comments obj request %}  {# Include comments belonging to a certain object #}
{% include_bootstrap %} {# Include bootstrap 4.1.1 - remove this line if BS 4.1.1 is already used in your project #}
{% include_static %} {# Include comment CSS and JS files #}

PROFILE_APP_NAME = 'accounts'
PROFILE_MODEL_NAME = 'UserProfile' # letter case insensitive

from django.urls import reverse

class UserProfile(models.Model):
    user = models.OneToOneField(User, on_delete=models.CASCADE)
    ...
    ...

    # this method must be defined for appropriate url mapping in comments section
    def get_absolute_url(self):
        return reverse('your_profile_url_name')

COMMENT_FLAG_REASONS = [
    (1, _('Spam | Exists only to promote a service')),
    (2, _('Abusive | Intended at promoting hatred')),
    (3, _('Racist | Sick mentality')),
    (4, _('Whatever | Your reason')),
    ...
]

class Post(models.Model):
    ...

    slug = models.SlugField(unique=True)

    ...

    def get_absolute_url(self):
        return reverse('post:postdetail', kwargs={'slug': self.slug})

COMMENT_ALLOW_ANONYMOUS = True
COMMENT_FROM_EMAIL = 'no-reply@email.com'   # used for sending confirmation emails, if not set `EMAIL_HOST_USER` will be used.

EMAIL_HOST_USER = 'user@domain'
EMAIL_HOST_PASSWORD = 'password'
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'    # this backend won't send emails but will just print them to the console. For production use your own backend.

# for production you may want to set this as backend
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
# e.g for if you are using gmail , you may set:
EMAIL_HOST = 'smtp.gmail.com'

Setup:

To integrate the comment API in your content type (e.g Post model), in serializers.py for the Post model add comments field as shown below:

from rest_framework import serializers
from comment.models import Comment
from comment.api.serializers import CommentSerializer


class PostSerializer(serializers.ModelSerializer):

    comments = serializers.SerializerMethodField()

    class Meta:
        model = Post
        fields = (
            'id',
            ...
            ...
            'comments'
        )

    def get_comments(self, obj):
        comments_qs = Comment.objects.filter_parents_by_object(obj)
        return CommentSerializer(comments_qs, many=True).data

By default all fields in profile model will be nested inside the user object in JSON response. This can only happen if the profile attributes are defined in your settings.py. In case you would like to serialize particular fields in the profile model you should explicitly declare the COMMENT_PROFILE_API_FIELDS tuple inside your settings.py:

PROFILE_APP_NAME = 'accounts'
PROFILE_MODEL_NAME = 'userprofile'
# the field names below must be similar to your profile model fields
COMMENT_PROFILE_API_FIELDS = ('display_name', 'birth_date', 'image')

Comment API actions:

1- Retrieve the list of comments and associated replies to a given content type and object ID:

This action can be performed by providing the url with data queries related to the content type.

Get request accepts 3 params:

• model_name: is the model name of the content type that have comments associated with it.

• app_name: is the name of the app inside which this model is defined.

• model_id: is the id of an object of that model

For example if you are using axios to retrieve the comment list of second object (id=2) of a model (content type) called post inside the app(django app) post. you can do the following:

$ curl -H "Content-Type: application/json" 'http://localhost:8000/api/comments/?model_name=MODEL_NAME&model_id=ID&app_name=APP_NAME'

2- Create a comment or reply to an existing comment:

Authorization must be provided as a TOKEN or USERNAME:PASSWORD.

• model_name: is the model name of the content type that have comments associated with it.

• app_name: the name of the app that contains that model.

• model_id: is the id of an object of that model

• parent_id: is 0 or NOT PROVIDED for parent comments and for reply comments must be the id of parent comment

Example: posting a parent comment

$ curl -X POST -u USERNAME:PASSWORD -d "content=CONTENT" -H "Content-Type: application/json" "http://localhost:8000/api/comments/create//?model_name=MODEL_NAME&model_id=ID&app_name=APP_NAME&parent_id=0"

3- Update a comment:

Authorization must be provided as a TOKEN or USERNAME:PASSWORD.

This action requires the comment.id that you want to update:

$ curl -X PUT -u USERNAME:PASSWORD -d "content=CONTENT" -H "Content-Type: application/json" "http://localhost:8000/api/comments/ID/

4- Delete a comment:

Authorization must be provided as a TOKEN or USERNAME:PASSWORD.

This action requires the comment.id that you want to delete:

$ curl -X DELETE -u USERNAME:PASSWORD -H "Content-Type: application/json" "http://localhost:8000/api/comments/ID/

5- React to a comment:

POST is the allowed method to perform a reaction on a comment.

Authorization must be provided as a TOKEN or USERNAME:PASSWORD.

This action requires the comment.id. and, reaction_type: one of like or dislike

$ curl -X POST -u USERNAME:PASSWORD -H "Content-Type: application/json" "http://localhost:8000/api/comments/ID/react/REACTION_TYPE/

PS: As in the UI, clicking the liked button will remove the reaction => unlike the comment. This behaviour is performed when repeating the same post request.

6- Report a comment

Flagging system must be enabled by adding the attribute COMMENT_FLAGS_ALLOWED to settings.py. See Enable Flagging

POST is the allowed method to report a comment.

Authorization must be provided as a TOKEN or USERNAME:PASSWORD.

This action requires the comment.id.

1. Set a flag:

payload = {
    'reason': REASON,  # number of the reason
    'info': ''  # this is required if the reason is 100 ``Something else``
}

$ curl -X POST -u USERNAME:PASSWORD -H "Content-Type: application/json" -d '{"reason":1, "info":""}' http://localhost:8000/api/comments/ID/flag/

2. Un-flag a comment:

To un-flag a FLAGGED comment, set reason value to 0 or remove the payload from the request.

$ curl -X POST -u USERNAME:PASSWORD http://localhost:8000/api/comments/ID/flag/

7- Change flagged comment state

POST is the allowed method to report a comment.

Authorization must be provided as a TOKEN or USERNAME:PASSWORD.

This action requires comment admin or moderator privilege.

payload = {
    'state': 3  # accepted state is 3 (REJECTED) or 4 (RESOLVED) only
}

$ curl -X POST -u USERNAME:PASSWORD -H "Content-Type: application/json" -d '{"state":3}' http://localhost:8000/api/comments/ID/flag/state/change/

Repeating the same request and payload toggle the state to its original.

8- Confirm comment made by an anonymous users

GET is the allowed method to confirm an anonymous comment.

Get request accepts 3 params:

• key: is the encrypted key that contains the comment.

Example:

::

$ curl -X GET -H “Content-Type: application/json” http://localhost:8000/api/comments/confirm/KEY/

Since the key generated for each comment is unique, it can only be used once to verify. Any tampering with the key will result in a BAD HTTP request(400).

1- Default blocks:

BS classes, pagination and some other template values can be now customized from within your templates directory as follows:

1. Create comment folder inside templates directory.

2. Create a new template file .html give it the same name of the default template needs to be overridden and put it in the right directory.

Templates tree:

└── templates
    └── comment
        ├── anonymous
        │   ├── confirmation_request.html
        │   ├── confirmation_request.txt
        │   └── discarded.html
        ├── bootstrap.html
        ├── comments
        │   ├── apply_icon.html
        │   ├── base.html
        │   ├── cancel_icon.html
        │   ├── child_comment.html
        │   ├── comment_body.html
        │   ├── comment_content.html
        │   ├── comment_form.html
        │   ├── comment_modal.html
        │   ├── content.html
        │   ├── create_comment.html
        │   ├── delete_icon.html
        │   ├── edit_icon.html
        │   ├── messages.html
        │   ├── pagination.html
        │   ├── parent_comment.html
        │   ├── reject_icon.html
        │   ├── resolve_icon.html
        │   ├── update_comment.html
        │   └── urlhash.html
        ├── flags
        │   ├── flag_icon.html
        │   ├── flag_modal.html
        │   └── flags.html
        ├── reactions
        │   ├── dislike_icon.html
        │   ├── like_icon.html
        │   └── reactions.html
        └── static.html

for example to override the BS classes of submit buttons and pagination style do the following:

create templates/comment/comments/create_comment.

{% extends "comment/comments/create_comment." %}

{% block submit_button_cls %}
btn btn-primary btn-block btn-sm
{% endblock submit_button_cls %}

{# override pagination style: #}
{% block pagination %}
{% include 'comment/comments/pagination.' with active_btn='bg-danger' text_style='text-dark' li_cls='page-item rounded mx-1' %}
{% endblock pagination %}

For full guide on the default templates and block tags name Read the Doc

2- CSS file:

To customize the default style of comments app , you can create a comment.css file inside static/css directory.

The new created file will override the original file used in the app.