Client Configuration

Client Configuration¶

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

<script data-isso="/prefix/"
        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-sorting="newest"
        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-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.:

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

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

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:

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

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

Default: "{api-endpoint}/css/isso.css"

data-isso-css

Set to false prevents Isso from automatically appending the stylesheet.

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

Default: true

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, 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 of the source tree.

Default: null

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, such as en, ru, or pt-BR.

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

Default: "en"

Added in version 0.12.6.

data-isso-max-comments-top

Number of top level 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.

Default: "inf"

data-isso-max-comments-nested

Number of 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.

Default: 5

data-isso-reveal-on-click

Number of comments to reveal on clicking the “X Hidden” link.

Default: 5

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.

Default: true

data-isso-avatar-bg

Set avatar background color. Any valid CSS color will do.

Default: "#f0f0f0"

data-isso-avatar-fg

Set avatar foreground color. Up to 8 colors are possible. The default color scheme is based in this color palette. 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.

Default: "#9abf88 #5698c4 #e279a3 #9163b6 #be5168 #f19670 #e4bf80 #447c69"

data-isso-vote

Enable or disable voting feature on the client side.

Default: true

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)

Default: null

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:

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

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

.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;
}

Default: null

Added in version 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

Added in version 0.13.

data-isso-sorting

Sort thread comments by specified sorting method.

Possible sorting methods:

newest: Bring newest comments to the top
oldest: Bring oldest comments to the top
upvotes: Bring most liked comments to the top

Default sorting is oldest.

Added in version 0.13.1.

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 since version 0.12.6.

Set to true when spam guard is configured with reply-to-self = true.
data-isso-require-author: Deprecated since version 0.12.6.

Set to true when spam guard is configured with require-author = true.
data-isso-require-email: Deprecated since version 0.12.6.

Set to true when spam guard is configured with require-email = true.
data-isso-reply-notifications: Deprecated since version 0.12.6.

Set to true when reply notifications is configured with reply-notifications = true.
data-isso-gravatar: Deprecated since version 0.12.6.

Set to true when gravatars are enabled with gravatar = true in the server configuration.
data-isso-feed: Deprecated since version 0.13.

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.