.. _ref-quickstart:

.. index::
   single: Guide
   pair: Quick; Start

=================
Quick start guide
=================

To get started using django-comments-xtd follow these steps:

#. ``pip install django-comments-xtd``

#. :ref:`Enable the "sites" framework <enabling-the-sites-framework>` by adding ``'django.contrib.sites'`` to :setting:`INSTALLED_APPS` and defining :setting:`SITE_ID`. Visit the admin site and be sure that the domain field of the ``Site`` instance points to the correct domain (``localhost:8000`` when running the default development server), as it will be used to create comment verification URLs, follow-up cancellations, etc.

#. Add ``'django_comments_xtd'`` and ``'django_comments'``, in that order [1]_, to :setting:`INSTALLED_APPS`.

#. Set the :setting:`COMMENTS_APP` setting to ``'django_comments_xtd'``.

#. Set the :setting:`COMMENTS_XTD_MAX_THREAD_LEVEL` to ``N``, being ``N`` the maximum level of threading up to which comments will be nested in your project.

.. code-block:: python

    # 0: No nested comments:
    #  Comment (level 0)
    # 1: Nested up to level one:
    #  Comment (level 0)
    #   |-- Comment (level 1)
    # 2: Nested up to level two:
    #  Comment (level 0)
    #   |-- Comment (level 1)
    #        |-- Comment (level 2)
    COMMENTS_XTD_MAX_THREAD_LEVEL = 2

The thread level can also be established on a per ``<app>.<model>`` basis by using the :setting:`COMMENTS_XTD_MAX_THREAD_LEVEL_BY_APP_MODEL` setting. Use it to establish different maximum threading levels for each model. ie: no nested comments for quotes, up to thread level 2 for blog stories, etc.

#. Set the :setting:`COMMENTS_XTD_CONFIRM_EMAIL` to ``True`` to require comment confirmation by email for no logged-in users.

#. Run ``manage.py migrate`` to create the tables.

#. Add the URLs of the comments-xtd app to your project's ``urls.py``:

.. code-block:: python

    urlpatterns = [
        ...
        url(r'^comments/', include('django_comments_xtd.urls')),
        ...
    ]

#. Customize your project's email settings:

.. code-block:: python

    EMAIL_HOST = "smtp.mail.com"
    EMAIL_PORT = "587"
    EMAIL_HOST_USER = "alias@mail.com"
    EMAIL_HOST_PASSWORD = "yourpassword"
    DEFAULT_FROM_EMAIL = "Helpdesk <helpdesk@yourdomain>"

#. To allow a quick start django-comments-xtd makes use of `bootstrap`_. From django-comments-xtd v2.9.10 on, it uses Bootstrap v5.3. If you want to build your own templates, use the `comments <https://django-contrib-comments.readthedocs.io/en/latest/quickstart.html#comment-template-tags>`_ templatetag module, provided by the `django-comments <https://django-contrib-comments.readthedocs.io/en/latest/index.html>`_ app. Create a ``comments/`` directory in your templates directory and copy the templates you want to customise from the Django Comments Framework. The following are the most important:

   * ``comments/list.html``, used by the ``render_comments_list`` templatetag.

   * ``comments/form.html``, used by the ``render_comment_form`` templatetag.

   * ``comments/preview.html``, used to preview the comment or when there are errors submitting it.

   * ``comments/posted.html``, which gets rendered after the comment is sent.

#. Add extra settings to control comments in your project. Check the available settings in the :ref:`Django Comments Framework <settings-comments>` and in the :ref:`django-comments-xtd app <settings-comments-xtd>`.


These are the steps to quickly start using django-comments-xtd. Follow to the next page, the :ref:`ref-tutorial`, to read a detailed guide that takes everything into account. In addition to the tutorial, the :ref:`ref-example` implement several commenting applications.


.. _bootstrap: https://getbootstrap.com
.. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

.. [1] To mind the :ref:`template-loading-order`.