<commit_before>Client Configuration
====================

You can configure the client (the JS part) with custom data attributes,
preferably in the script tag which embeds the JS:

.. code-block:: html

    <script data-isso="/prefix/"
            data-isso-id="thread-id"
            data-isso-css="true"
            data-isso-css-url="null"
            data-isso-lang="ru"
            data-isso-max-comments-top="10"
            data-isso-max-comments-nested="5"
            data-isso-reveal-on-click="5"
            data-isso-avatar="true"
            data-isso-avatar-bg="#f0f0f0"
            data-isso-avatar-fg="#9abf88 #5698c4 #e279a3 #9163b6 ..."
            data-isso-vote="true"
            data-isso-vote-levels=""
            data-isso-feed="false"
            data-isso-reply-notifications-default-enabled="false"
            src="/prefix/js/embed.js"></script>

Furthermore you can override the automatic title detection inside
the embed tag, as well as the thread ID, e.g.:

.. code-block:: html

    <section id="isso-thread" data-title="Foo!" data-isso-id="/path/to/resource"></section>

Overriding translation strings
------------------------------

Additionally, you can override any translation string for any language by adding
a ``data-isso-`` attribute that is equal to the translation key (found `here`__) with
``-text-[lang]`` appended to it. So, for example, if you want to override the
english translation of the ``postbox-notification`` message, you could add:

.. code-block:: html

    data-isso-postbox-notification-text-en="Select to be notified of replies to your comment"

.. __: https://github.com/posativ/isso/blob/master/isso/js/app/i18n/en.js

data-isso-* directives
------------------------

data-isso
   Isso usually detects the REST API automatically, but when you serve the JS
   script on a different location, this may fail. Use `data-isso` to
   override the API location:

   .. code-block:: html

       <script data-isso="/isso" src="/path/to/embed.min.js"></script>

data-isso-css-url
    Set URL from which to fetch ``isso.css``, e.g. from a CDN.
    Defaults to fetching from the API endpoint.

    .. code-block:: html

        <script src="..." data-isso-css-url="/path/to/isso.css"></script>

data-isso-css
    Set to `false` prevents Isso from automatically appending the stylesheet.
    Defaults to `true`.

    .. code-block:: html

        <script src="..." data-isso-css="false"></script>

data-isso-lang
    Always render the Isso UI in this language, ignoring what the
    user-agent says is the preferred language.  The default is to
    honor the user-agent's preferred language, and this can be
    specified explicitly by using ``data-isso-lang=""``.

    The value of this property should be a `BCP 47 language tag
    <https://tools.ietf.org/html/bcp47>`_, such as "en", "ru", or "pt-BR".
    Language tags are processed case-insensitively, and may use
    underscores as separators instead of dashes (e.g. "pt_br" is treated
    the same as same as "pt-BR").

    You can find a list of all supported languages by browsing the
    `i18n directory
    <https://github.com/posativ/isso/tree/master/isso/js/app/i18n>`_ of
    the source tree.

data-isso-default-lang
    Render the Isso UI in this language when the user-agent does not
    specify a preferred language, or if the language it specifies is not
    supported.  Like ``data-isso-lang``, the value of this property should
    be a BCP 47 language tag.  Defaults to "en".

    If you specify both ``data-isso-default-lang`` and ``data-isso-lang``,
    ``data-isso-lang`` takes precedence.

    .. versionadded:: 0.12.6

data-isso-max-comments-top, data-isso-max-comments-nested
    Number of top level (or nested) comments to show by default. If some
    comments are not shown, an "X Hidden" link is shown.

    Set to ``"inf"`` to show all, or ``"0"`` to hide all.

data-isso-reveal-on-click
    Number of comments to reveal on clicking the "X Hidden" link.

data-isso-avatar
    Enable or disable avatar generation. Ignored if gravatar is enabled on
    server side, since gravatars will take precedence and disable avatar
    generation.

data-isso-avatar-bg
    Set avatar background color. Any valid CSS color will do.

data-isso-avatar-fg
    Set avatar foreground color. Up to 8 colors are possible. The default color
    scheme is based in `this color palette <http://colrd.com/palette/19308/>`_.
    Multiple colors must be separated by space. If you use less than eight colors
    and not a multiple of 2, the color distribution is not even.

data-isso-vote
    Enable or disable voting feature on the client side.

data-isso-vote-levels
    List of vote levels used to customize comment appearance based on score.
    Provide a comma-separated values (eg. `"0,5,10,25,100"`) or a JSON array (eg. `"[-5,5,15]"`).

    For example, the value `"-5,5"` will cause each `isso-comment` to be given one of these 3 classes:

    - `isso-vote-level-0` for scores lower than `-5`
    - `isso-vote-level-1` for scores between `-5` and `4`
    - `isso-vote-level-2` for scores of `5` and greater

    These classes can then be used to customize the appearance of comments (eg. put a star on popular comments)

data-isso-feed
    Enable or disable the addition of a link to the feed for the comment
    thread. The link will only be valid if the appropriate setting, in
    ``[rss]`` section, is also enabled server-side.

data-isso-reply-notifications-default-enabled
    Set to ``true`` to make the reply notifications checkbox on the postbox be
    checked by default. Otherwise, the user will have to manually opt-in to
    reply notifications.

    This setting will have no effect if ``reply-notifications`` are not enabled
    on the server.

    Default: ``false``

    .. versionadded:: 0.13


Deprecated Client Settings
--------------------------

In earlier versions the following settings had to mirror the
corresponding settings in the server configuration, but they are now
read out from the server automatically.

data-isso-reply-to-self
    .. deprecated:: 0.12.6

    Set to `true` when spam guard is configured with `reply-to-self = true`.

data-isso-require-author
    .. deprecated:: 0.12.6

    Set to `true` when spam guard is configured with `require-author = true`.

data-isso-require-email<commit_msg>docs: client: Document `data-isso-page-author-hashes`<commit_after>Client Configuration
====================

You can configure the client (the JS part) with custom data attributes,
preferably in the script tag which embeds the JS:

.. code-block:: html

    <script data-isso="/prefix/"
            data-isso-id="thread-id"
            data-isso-css="true"
            data-isso-css-url="null"
            data-isso-lang="ru"
            data-isso-max-comments-top="10"
            data-isso-max-comments-nested="5"
            data-isso-reveal-on-click="5"
            data-isso-avatar="true"
            data-isso-avatar-bg="#f0f0f0"
            data-isso-avatar-fg="#9abf88 #5698c4 #e279a3 #9163b6 ..."
            data-isso-vote="true"
            data-isso-vote-levels=""
            data-isso-feed="false"
            data-isso-page-author-hashes="f124cf6b2f01,7831fe17a8cd"
            data-isso-reply-notifications-default-enabled="false"
            src="/prefix/js/embed.js"></script>

Furthermore you can override the automatic title detection inside
the embed tag, as well as the thread ID, e.g.:

.. code-block:: html

    <section id="isso-thread" data-title="Foo!" data-isso-id="/path/to/resource"></section>

Overriding translation strings
------------------------------

Additionally, you can override any translation string for any language by adding
a ``data-isso-`` attribute that is equal to the translation key (found `here`__) with
``-text-[lang]`` appended to it. So, for example, if you want to override the
english translation of the ``postbox-notification`` message, you could add:

.. code-block:: html

    data-isso-postbox-notification-text-en="Select to be notified of replies to your comment"

.. __: https://github.com/posativ/isso/blob/master/isso/js/app/i18n/en.js

data-isso-* directives
------------------------

data-isso
   Isso usually detects the REST API automatically, but when you serve the JS
   script on a different location, this may fail. Use `data-isso` to
   override the API location:

   .. code-block:: html

       <script data-isso="/isso" src="/path/to/embed.min.js"></script>

data-isso-css-url
    Set URL from which to fetch ``isso.css``, e.g. from a CDN.
    Defaults to fetching from the API endpoint.

    .. code-block:: html

        <script src="..." data-isso-css-url="/path/to/isso.css"></script>

data-isso-css
    Set to `false` prevents Isso from automatically appending the stylesheet.
    Defaults to `true`.

    .. code-block:: html

        <script src="..." data-isso-css="false"></script>

data-isso-lang
    Always render the Isso UI in this language, ignoring what the
    user-agent says is the preferred language.  The default is to
    honor the user-agent's preferred language, and this can be
    specified explicitly by using ``data-isso-lang=""``.

    The value of this property should be a `BCP 47 language tag
    <https://tools.ietf.org/html/bcp47>`_, such as "en", "ru", or "pt-BR".
    Language tags are processed case-insensitively, and may use
    underscores as separators instead of dashes (e.g. "pt_br" is treated
    the same as same as "pt-BR").

    You can find a list of all supported languages by browsing the
    `i18n directory
    <https://github.com/posativ/isso/tree/master/isso/js/app/i18n>`_ of
    the source tree.

data-isso-default-lang
    Render the Isso UI in this language when the user-agent does not
    specify a preferred language, or if the language it specifies is not
    supported.  Like ``data-isso-lang``, the value of this property should
    be a BCP 47 language tag.  Defaults to "en".

    If you specify both ``data-isso-default-lang`` and ``data-isso-lang``,
    ``data-isso-lang`` takes precedence.

    .. versionadded:: 0.12.6

data-isso-max-comments-top, data-isso-max-comments-nested
    Number of top level (or nested) comments to show by default. If some
    comments are not shown, an "X Hidden" link is shown.

    Set to ``"inf"`` to show all, or ``"0"`` to hide all.

data-isso-reveal-on-click
    Number of comments to reveal on clicking the "X Hidden" link.

data-isso-avatar
    Enable or disable avatar generation. Ignored if gravatar is enabled on
    server side, since gravatars will take precedence and disable avatar
    generation.

data-isso-avatar-bg
    Set avatar background color. Any valid CSS color will do.

data-isso-avatar-fg
    Set avatar foreground color. Up to 8 colors are possible. The default color
    scheme is based in `this color palette <http://colrd.com/palette/19308/>`_.
    Multiple colors must be separated by space. If you use less than eight colors
    and not a multiple of 2, the color distribution is not even.

data-isso-vote
    Enable or disable voting feature on the client side.

data-isso-vote-levels
    List of vote levels used to customize comment appearance based on score.
    Provide a comma-separated values (eg. `"0,5,10,25,100"`) or a JSON array (eg. `"[-5,5,15]"`).

    For example, the value `"-5,5"` will cause each `isso-comment` to be given one of these 3 classes:

    - `isso-vote-level-0` for scores lower than `-5`
    - `isso-vote-level-1` for scores between `-5` and `4`
    - `isso-vote-level-2` for scores of `5` and greater

    These classes can then be used to customize the appearance of comments (eg. put a star on popular comments)

data-isso-feed
    Enable or disable the addition of a link to the feed for the comment
    thread. The link will only be valid if the appropriate setting, in
    ``[rss]`` section, is also enabled server-side.

data-isso-page-author-hashes
    Provide the hash (or list of hashes) of the current page's author. Any
    comments made by those authors will be given the ``isso-is-page-author``
    class. This can be styled using CSS.

    The hash of a user can be found by checking the ``data-hash`` parameter on the
    ``<div>`` tag containing their comment. This is what the element looks like:

    .. code-block:: html

        <div class="isso-comment isso-no-votes" id="isso-14" data-hash="41faef0a49fc">

    According to this example, your script tag would look something like this:

    .. code-block:: html

        <script src="..." data-isso-page-author-hashes="41faef0a49fc"></script>

    When adding multiple hashes to support multiple page authors, separate the
    hashes by a command and/or space. All of the following are acceptable
    (although the hashes are made up):

    - ``data-isso-page-author-hashes="86g7n8g67nm,8m787mg8"``
    - ``data-isso-page-author-hashes="86g7n8g67nm 8m787mg8"``
    - ``data-isso-page-author-hashes="86g7n8g67nm, 8m787mg8"``

    For example, these CSS rules make the page author's name a sort of
    turquoise color, and the comment's background a lighter version of that:

    .. code-block:: css

        .isso-comment.isso-is-page-author > .isso-text-wrapper {
            background-color: #bae0ea;
        }

        .isso-comment.isso-is-page-author > .isso-text-wrapper > .isso-comment-header > .isso-author {
            color: #19798d;
        }


    .. versionadded:: 0.13


data-isso-reply-notifications-default-enabled
    Set to ``true`` to make the reply notifications checkbox on the postbox be
    checked by default. Otherwise, the user will have to manually opt-in to
    reply notifications.

    This setting will have no effect if ``reply-notifications`` are not enabled
    on the server.

    Default: ``false``

    .. versionadded:: 0.13


Deprecated Client Settings
--------------------------

In earlier versions the following settings had to mirror the
corresponding settings in the server configuration, but they are now
read out from the server automatically.

data-isso-reply-to-self
    .. deprecated:: 0.12.6

    Set to `true` when spam guard is configured with `reply-to-self = true`.

data-isso-require-author
    .. deprecated:: 0.12.6

    Set to `true` when spam guard is configured with `require-author = true`.

data-isso-require-email
{'fraction_non_alphanumeric': 0.11776600195230791, 'fraction_numerical': 0.01617626551387533, 'mean_word_length': 2.828884143085958, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 37, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1868959', 'n_tokens_mistral': 4526, 'n_tokens_neox': 4255, 'n_words': 1601}