Frontend
========

In pages where you want comments, a little work is required.

New comment form
----------------

A minimal comment form should look like this:

.. code-block:: html

  <form id="newCommentForm" action="/OWN-COMMENTS-API-PREFIX/comments/form" method="POST">
    <input type="text" name="author_name" id="commenterName" placeholder="Your name" required="" />
    <textarea id="commentBody" name="text" placeholder="Your comment" required=""></textarea>
    <button id="commentSubmit">
      Add your comment
    </button>
  </form>

This will allow posting new comments, even without JS enabled.
If you decide to include the JS frontend, this ``newCommentForm`` will be modified in order to
use XHR calls instead of plain old form data over HTTP POST.

Templates
---------

The HTML must include two templates that the backend will use.

Have a look at the example
`in the repo <https://git.sr.ht/~nicoco/own-comments/tree/master/item/frontend/index.html>`_

Comment Thread
**************

This template must have a `commentThreadTemplate` ID and it must contain 2 HTML
elements that the JS script will use.

- an arbitrary HTML element whose ID is ``commentNumber``: its ``textContent`` will
  be replaced by a count, e.g. "0 comments" or "42 comments"
- a ``div id="comments"`` where individual comments will be appended as children

Individual comment
******************

This template must be ID'ed as ``commentTemplate`` have elements with the IDs and types listed in
`this file <https://git.sr.ht/~nicoco/own-comments/tree/master/item/frontend/comments.ts#L6>`_

Import
------

Pack the `minified release <https://www.npmjs.com/package/own-comments-frontend>`_
from npm with your website.

Import `OwnComments` from `comments.js` and instantiate an instance using the backend URL as
a parameter. Example:

.. code-block::javascript

  <script type="module">
    import {OwnComments} from '/where/you/packed/comments.js'
    window.comments = new OwnComments("/OWN-COMMENTS-API-PREFIX")
  </script>

Making the instance available as an attribute of ``window`` will make it possible to switch
to admin mode by opening the JS console and using ``comments.godMode(adminUserName, adminPassword)``

Behaviour
---------

In individual comments, the ``edit`` and ``admin`` will be hidden (and not usable) by default.
When posting a comment, the API gives an update key that will be stored to the browser's
``localStorage``.
When rendering a comment, if the corresponding update key is found in the browser's ``localStorage``,
the ``edit`` HTML element will be displayed, with the correct hooks including this update key.

Administration
--------------

If you want to be able to moderate the comments from the page itself, make the ``OwnComments``
instance available globally by using ``window.comments = yourOwnCommentInstance``.
In the JS console of your browser, type ``comments.godMode(yourAdminUserName, yourAdminPassword)``.
You can now (un)approve, delete, purge or edit comments.

.. note::

  Alternatively, or if you want to roll your own frontend, you could use the
  `REST endpoints <https://nicoco.srht.site/own-comments/back.html#openapi-schema>`_
  with CURL,
  use a graphical tool like `SQLite browser <https://sqlitebrowser.org/>`_, or something
  different.
  Be weird, do it in a fun way!