django-comments-dab App - v1.2.0
================================

**dab stands for Django-Ajax-Bootstrap**

``django-comments-dab`` is a commenting application for Django-powered
websites.

It allows you to integrate commenting functionality with any model you
have e.g. blogs, pictures, etc…

*List of actions you can do:*

    1. Post a new comment. (Authenticated)

    2. Reply to an existing comment. (Authenticated)

    3. Edit a comment you posted. (Authenticated)

    4. Delete a comment you posted. (Authenticated)


- All actions are done by ajax - JQuery 3.2.1

- Bootstrap 4.1.1 is used in comment templates for responsive design.

Installation
------------


Requirements:
~~~~~~~~~~~~~

    1. **django==2.1**
    2. **django-widget-tweaks==1.4.2**
    3. **djangorestframework==3.8.2**  # for API Framework
    4. **Bootstrap 4.1.1**
    5. **jQuery 3.2.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


Settings and urls:
~~~~~~~~~~~~~~~~~~

    1. Add ``comment`` to your installed_apps in your ``settings.py`` file. It should be added after ``django.contrib.auth``. and,
    2. Make sure that ``widget-tweaks`` is already included in installed_apps as well.
    3. ``LOGIN_URL`` shall be defined in the settings.

your ``settings.py`` should look like the following:

.. code:: python

    INSTALLED_APPS = (
        'django.contrib.admin',
        'django.contrib.auth',
        ...
        'widget_tweaks',
        'comment',
        'rest_framework',  # for API Framework
        ..
    )

    LOGIN_URL = 'login'  # or your actual url

In your urls.py:

.. code:: python

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

Migrations:
~~~~~~~~~~~

Migrate comment app:

::

    $ python manage.py migrate comment



Setup
-----

Step 1
~~~~~~

In your models.py add the field comments (Please note that field name
must be ``comments`` not ``comment``) to the model for which comments
should be added (e.g. Post) and **the appropriate imports** as shown below:

.. code:: python

    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
~~~~~~

``get_comments`` *tag uses 2 positional and 3 optional args*:

    1. The instance of the model. (**positional**)
    2. Request object. (**positional**)
    3. oauth. (optional - Default is false)
    4. paginate. (optional - Default is false)
    5. cpp (number of Comments Per Page - Default is 10)


1. Basics usage:
^^^^^^^^^^^^^^^^

``include_static`` this tag will include required jquery and javascript file,
if you already use jquery please make sure it is not the slim version which doesn't support ajax.
``include_bootstrap`` tag is for bootstrap-4.1.1, if it’s already included
in your project, get rid of this tag.

In your template (e.g. post-detail.html) add the following template tags where object is the instance of post model.

.. code:: python

    {% load comment_tags %}  # Loading the template tag
    {% get_comments object request %}  # Include all the 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 jQuery 3.2.1 and required js file



2. Advanced usage:
^^^^^^^^^^^^^^^^^^

    **1. Add pagination:**

    To add pagination to your comments, you need to pass two variables to the ``get_comments`` tag.
    ``paginate`` must be set to ``True`` and set ``cpp`` var (number of comments per page - default is 10) to the desired number of comments per page.
    e.g. If you would like to have 5 comments per page, the ``get_comments`` tag should look like this:

    .. code:: python

        {% load comment_tags %}  # Loading the template tag
        {% get_comments object request paginate=True cpp=5 %}  # Include all the 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 jQuery 3.2.1 and required js file



    **2. Integrate existing profile app with comments app:**

    If you have profile model for the user and you would like to show the
    profile image on each comment, you need to do these two steps:

    - Assign ``PROFILE_APP_NAME`` and ``PROFILE_MODEL_NAME`` variables in your ``settings.py`` file.
        (e.g if user profile app is called ``accounts`` and profile model is called ``UserProfile``)
        Update your ``settings.py`` as follows:

        .. code:: python

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



    - Make sure that get_absolute_url method is defined in your profile model.
        Update your ``user profile model`` as follows:

        .. code:: python

            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('profile_url_name')


Web API
-------

django-comments-dab uses django-rest-framework to expose a Web API that provides
developers with access to the same functionalities offered through the web user interface.

There are 6 methods available to perform the following actions:


    1. Post a new comment. (Authenticated)

    2. Reply to an existing comment. (Authenticated)

    3. Edit a comment you posted. (Authenticated)

    4. Delete a comment you posted. (Authenticated)

    5. Retrieve the list of all comments and associated replies.

    6. Retrieve the list of comments and associated replies to a given content type and object ID.



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:


.. code:: python

    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_by_object(obj)
            return CommentSerializer(comments_qs, many=True).data

if you would like to have comment list url in your api root url, include the
comment-list url in the returned response as follows:


.. code:: python

    from rest_framework.decorators import api_view
    from rest_framework.response import Response
    from rest_framework.reverse import reverse

    @api_view(['GET'])
    def api_root(request, format=None):
        return Response({
            'Posts': reverse('post-list', request=request, format=format),
            'comments': reverse('comments-list', request=request, format=format),
        })


Customize Styling
-----------------

If you want to customize the default style of comments app , you can do the following steps:
    1. Create a ``comment.css`` file inside your ``static/css`` directory.
    2. The new created file will overwrite the original file used in the app.

and you’re done.
