Aggiungi commenti alla tua app Django

• Python 3.10+
• Django 4.2, 5.0, 5.1, o 5.2
• Un ID tenant FastComments (usa demo per provarlo senza un account)
• Un segreto API è richiesto solo per Secure SSO

Install from a release tag (this project is distributed via git tags, not PyPI):

pip install "git+https://github.com/fastcomments/fastcomments-django.git@v0.1.0"

For server-side REST access (the admin() / public_api() helpers), add the api extra, which pulls in the SDK's generated client:

pip install "fastcomments-django[api] @ git+https://github.com/fastcomments/fastcomments-django.git@v0.1.0"

Add the app to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "fastcomments_django",
]

Configura il tuo tenant in settings.py:

import os

FASTCOMMENTS = {
    "TENANT_ID": os.environ.get("FASTCOMMENTS_TENANT_ID", "demo"),
}

Inserisci il widget in qualsiasi template:

{% load fastcomments %}

{% fastcomments url_id="my-page" %}

Per passare l'utente autenticato al widget automaticamente, i tag leggono l'utente corrente dalla request. Assicurati che il tuo progetto abbia entrambi (sono attivi per impostazione predefinita in un progetto Django standard):

• django.template.context_processors.request in TEMPLATES["OPTIONS"]["context_processors"]
• django.contrib.auth.middleware.AuthenticationMiddleware in MIDDLEWARE

Senza una request nel contesto del template, i widget vengono renderizzati per un visitatore anonimo. Puoi sempre passare un utente esplicitamente: {% fastcomments user=some_user %}.

Ogni widget ha il proprio tag. Tutti accettano argomenti chiave **extra, che vengono fusi nella configurazione del widget così com'è (usa chiavi camelCase) per tutto ciò che non è coperto dagli argomenti nominati di seguito.

Gli argomenti nominati corrispondono alle chiavi di configurazione camelCase del widget:

Esempi:

{% load fastcomments %}

{% fastcomments url_id="my-page" locale="en_us" default_sort_direction="MR" %}

{% fastcomments_live_chat url_id="room-1" %}

Comments: {% fastcomments_comment_count url_id="my-page" number_only=True %}

{# La chat collaborativa si collega a un elemento esistente nella pagina #}
<article id="post-body">...</article>
{% fastcomments_collab_chat target="#post-body" %}

{# Conteggi in blocco: posiziona i marker, poi un loader bulk li riempie tutti #}
{% for post in posts %}
    <a href="\{{ post.url }}">\{{ post.title }}</a>
    {% fastcomments_count_marker url_id=post.url_id %}
{% endfor %}
{% fastcomments_comment_count_bulk %}

Enable SSO e scegli una modalità in settings.py. Secure SSO firma l'utente lato server con HMAC‑SHA256 usando il tuo segreto API ed è raccomandato.

FASTCOMMENTS = {
    "TENANT_ID": os.environ["FASTCOMMENTS_TENANT_ID"],
    "API_KEY": os.environ["FASTCOMMENTS_API_KEY"],   # il tuo segreto API; firma Secure SSO
    "SSO": {
        "ENABLED": True,
        "MODE": "secure",                            # "secure" | "simple"
        # Mappa i campi FastComments al tuo modello utente. I valori possono essere un attributo
        # nome, un percorso puntato ("profile.avatar_url"), una callable(user), o None.
        "USER_MAP": {
            "id": "id",
            "email": "email",
            "username": "username",
            "avatar": None,
            "display_name": None,
            "website_url": None,
        },
        "IS_ADMIN": lambda user: user.is_staff,      # callable(user) -> bool, o percorso puntato
        "IS_MODERATOR": None,
        "GROUP_IDS": None,                           # callable(user) -> list, o percorso puntato
    },
}

Scegli deliberatamente l'id SSO. L'id di FastComments è l'identificatore permanente per la cronologia dei commenti di un utente. Il USER_MAP predefinito lo mappa alla tua chiave primaria Django per comodità zero‑config, ma le PK intere sequenziali sono enumerabili e difficili da modificare in seguito (cambiare l'id di un utente divide la sua cronologia in un nuovo account). Per qualsiasi uso oltre una demo, mappa l'id a un valore stabile e opaco scelto in anticipo (un UUID o un ID pubblico dedicato), e non inserire mai dati privati al suo interno. L'app di esempio utilizza un id basato sul nome utente per questo motivo.

SSO viene inserito automaticamente in {% fastcomments %}, {% fastcomments_live_chat %}, {% fastcomments_collab_chat %}, {% fastcomments_image_chat %} e {% fastcomments_user_activity %} per l'utente corrente.

Gli URL di login/logout mostrati ai visitatori non autenticati sono per impostazione predefinita reverse("login") / reverse("logout"); sovrascrivili con SSO["LOGIN_URL"] / SSO["LOGOUT_URL"].

Mappatura personalizzata

Due opzioni con precedenza più alta hanno la precedenza su USER_MAP:

• Un metodo sul tuo modello utente (l'analogo Pythonico di un'interfaccia):

  class User(AbstractUser):
      def to_fastcomments_user_data(self):
          return {"id": self.pk, "email": self.email, "username": self.get_username()}

• Un mapper globale, un percorso puntato a callable(user) -> dict:

  FASTCOMMENTS = {"SSO": {"USER_MAPPER": "myapp.sso.map_user"}}

La precedenza è USER_MAPPER > to_fastcomments_user_data() > USER_MAP.

Con l'extra [api] installato, chiama l'API REST di FastComments tramite l'SDK, pre‑configurato con la tua chiave API e la regione:

from fastcomments_django import admin, public_api, get_manager

admin().get_comments("YOUR_TENANT_ID", ...)     # authenticated (DefaultApi)
public_api().get_comments_public(...)            # public (PublicApi)

# Generate an SSO token for API calls or client hand-off:
token = get_manager().sso().token_for(request.user)

Imposta REGION per indirizzare i widget e l'API verso l'UE:

FASTCOMMENTS = {"TENANT_ID": "...", "REGION": "eu"}

Sovrascrivi fastcomments/widget.html posizionando la tua copia più in alto nel percorso di ricerca dei template (un progetto templates/fastcomments/widget.html). Questo è l'analogo Django di vendor:publish --tag=fastcomments-views di Laravel.

Una demo eseguibile si trova in example/: un'app a colonna laterale sinistra + stage principale con una pagina per widget e una pagina di accesso che elenca gli utenti demo pre‑caricati.
Accedi con uno qualsiasi di loro e i widget di commento e chat live autenticano quell’identità tramite Secure SSO. Da quella directory:

python manage.py migrate
# Use your own tenant to see Secure SSO in action (an API secret enables it):
FASTCOMMENTS_TENANT_ID=... FASTCOMMENTS_API_KEY=... python manage.py runserver

Senza una chiave API segreta, ricade sul tenant pubblico demo (anonimo).
example/browser_smoke.py è un test end‑to‑end Playwright che carica la pagina in un browser reale e pubblica un commento come utente Secure‑SSO.