Diane, poznámka do spisu. Co si comment box bere a co s tím dělá.

Návod.

Vložení widgetu vyžaduje dva řádky HTML. Vše za první sekcí je nepovinné: nastavení pro případy, kdy výchozí chování vašemu webu nevyhovuje.

• Nastavení
• Který web, která stránka
• Atributy
• Weby s vlastním routováním
• Vzhled
• Jazyk
• Limity
• Moderace
• Co se ukládá
• Content Security Policy
• Když se nic neukáže
• Co Diane nedělá

Nastavení

1. Přihlaste se na admin.diane.to pomocí účtu Google.
2. Přidejte doménu. Jeden záznam na jeden hostname: www.example.com a example.com představují stejný web, subdomény jako blog.example.com musíte registrovat zvlášť.
3. Vložte do stránky tyto dva řádky:

<script async defer src="https://diane.to/w.js"></script>
<to-diane></to-diane>

Skript můžete umístit do hlavičky nebo na konec těla. Vlastní element vložte tam, kde se má widget vykreslit.

Kód neobsahuje žádný klíč, ID webu ani identifikátor stránky. Web určuje hlavička Origin a stránku její URL, takže se do HTML nevkládá nic dalšího a není co udržovat v souladu.

Který web, která stránka

Web identifikuje hlavička Origin. Prohlížeč ji přidává ke každému cross-origin požadavku a JavaScript na stránce ji nedokáže podvrhnout. Hodnota se porovnává přesně s registrovanou doménou, pouze se odřízne jedno úvodní www.. Všechny ostatní subdomény vyžadují vlastní registraci.

Stránka se určuje ze tří míst, v tomto pořadí:

1. atribut post-slug na elementu,
2. cesta z <link rel="canonical">,
3. aktuální location.pathname.

Výsledný identifikátor čistí widget i server stejně. Odstraní se query string, fragment, zdvojená a koncová lomítka. Adresy /post, /post/ a /post?utm_source=rss proto vedou na stejné vlákno. Identifikátor nesmí přesáhnout 200 znaků; delší post-slug widget ignoruje a použije kanonický odkaz, případně location.pathname.

Dva elementy s odlišným atributem post-slug na jedné stránce vytvoří dvě samostatná vlákna. Kanonický odkaz mířící jinam sdruží přetištěné kopie článku do jednoho sdíleného vlákna.

Atributy

<to-diane post-slug="/blog/twin-peaks"></to-diane>

Oba atributy jsou nepovinné. Žádné další neexistují.

Weby s vlastním routováním

Widget rozpozná změnu adresy sám. Poslouchá událost popstate, využívá Navigation API a jinak kontroluje location.href jednou za sekundu. Standardní single-page aplikace nevyžaduje žádné další nastavení.

Pokud vlákno neurčuje adresa, aktualizujte atribut při změně route:

document.querySelector("to-diane").setAttribute("post-slug", nextSlug)

Odpověď serveru, která dorazí po přechodu čtenáře na jinou stránku, se zahodí. Rozepsaný komentář se při navigaci smaže.

Vzhled

Widget odvozuje paletu z barvy textu vaší stránky. prefers-color-scheme nebere v úvahu. Díky tomu ladí se stránkou, do které je vložený, a nikoliv s operačním systémem návštěvníka. Většina webů proto nepotřebuje žádné úpravy vzhledu.

Pro přizpůsobení nastavte na elementu CSS custom properties:

to-diane {
  --td-font: Georgia, serif;
  --td-radius: 4px;
  --td-gap: 24px;

  /* A solid brand button instead of the default tinted one */
  --td-button-bg: #7c2d12;
  --td-button-fg: #fff;
  --td-button-border: transparent;
}

Pro stylování jsou vystaveny tři části. Selektor ::part(root) cílí na celý kontejner, ::part(heading) na nadpis s počtem komentářů a ::part(powered) na popisek „Powered by Diane.to“ pod formulářem. Popisek můžete přebarvit, nebo skrýt:

to-diane::part(powered) {
  display: none;
}

Na žádný jiný vnitřní prvek nelze ze stránky zacílit. Element používá display: block, velikost omezte pomocí max-width.

Jazyk

Widget přebírá jazyk z atributu <html lang> vaší stránky. Atribut na elementu tuto hodnotu přepíše:

<to-diane lang="cs"></to-diane>

Podporována je angličtina a čeština. U nepodporovaného jazyka se použijí anglické popisky, zatímco formát data se řídí locale stránky. O přidání jazyka napište na hello@diane.to.

Limity

Bezplatný účet umožňuje sto živých komentářů na jeden web. Po překročení limitu server odmítne nové příspěvky a widget ohlásí plnou kapacitu. Napsané komentáře zůstávají viditelné. Smazané komentáře se do limitu nepočítají a smazání lze vrátit.

Jméno je omezeno na 80 znaků a komentář na 4000.

Komentáře prochází kontrolou proti spamu bez použití CAPTCHA. U odmítnutého komentáře se zobrazí zpráva v jazyce návštěvníka s dalšími kroky. Pokud dochází k blokování legitimních komentářů, napište na hello@diane.to.

Moderace

Moderování probíhá v konzoli na admin.diane.to. Najdete zde jednu schránku se všemi komentáři seřazenými od nejnovějšího a pohled na konkrétní web rozdělený podle vláken. Komentáře můžete mazat a obnovovat, zobrazit smazané, přejmenovat web a celý web umlčet — umlčení skryje widget na dané doméně, aniž by návštěvníkům ukázalo chybu.

Nový web drží komentáře, dokud je neschválíte — v konzoli je najdete ve frontě označené waiting a tlačítkem Approve je pustíte na stránku. Zamítnout komentář znamená smazat ho; je to stejné tlačítko a jde vzít zpět, komentář se pak vrátí do fronty. Než ho schválíte, vidí ho na stránce jen ten, kdo ho napsal, a to zašedlý s poznámkou, že čeká. V nastavení webu se to dá přepnout na Publish immediately a komentáře se pak zobrazují ihned po odeslání.

Přepnutí režimu nesahá na to, co už je napsané: čekající komentáře čekají dál, dokud je neschválíte, a zveřejněné zůstávají zveřejněné. Komentáře, které čekají, se nezapočítávají do limitu sta zveřejněných — fronta má vlastní strop, taky sto. Když se naplní, web další komentáře odmítá, dokud něco neschválíte nebo nesmažete.

Odpovídat můžete přímo z konzole. Odpověď se ve vlákně objeví jako poslední komentář, označený jako autor, aby bylo poznat, že mluví majitel webu. Podepisuje se jménem z políčka Reply as na stránce webu — to se vyplní vaším jménem už při registraci webu a můžete ho kdykoliv změnit. Změna se propíše i do odpovědí, které jste už poslali: je to pořád jeden člověk, ne dva. Odpověď se počítá do limitu jako každý jiný komentář a smazat ji lze stejným tlačítkem.

Co se ukládá

Diane ukládá jméno zadané návštěvníkem, text komentáře, časové razítko a nesolený otisk SHA-256 jeho IP adresy. Otisk se porovnává pouze na shodu v rámci kontroly proti spamu a žádný endpoint jej nevrací. Widget na vašem webu nenastavuje cookies a nenačítá zdroje třetích stran.

Dokud komentář někoho čeká na schválení, drží si widget jeho identifikátor v localStorage na vaší vlastní doméně, pod klíčem to-diane:pending — jen identifikátor a stránku, kde byl napsán, nikdy text. Díky tomu člověk stránku znovu načte a svůj komentář tam pořád vidí. Přečte to jen váš web, k nám se to nedostane a po zveřejnění nebo smazání komentáře to zmizí.

Komentáře se ukládají v odeslané podobě a vykreslují jako prostý text. Neuplatní se HTML, Markdown ani automatické odkazy. Další podrobnosti najdete na stránce Soukromí.

Content Security Policy

Pokud váš web odesílá Content Security Policy, widgetu se týkají tři direktivy:

script-src   https://diane.to
connect-src  https://diane.to
style-src    'unsafe-inline'

Direktiva script-src povoluje skript, connect-src požadavky na API a style-src vlastní styly widgetu. Ty tvoří element <style> uvnitř shadow rootu, kam se nonce nedostane. Widget nenačítá fonty, obrázky ani zdroje třetích stran.

Když se nic neukáže

Widget návštěvníkům nikdy nezobrazuje chyby konfigurace. Nevykreslí nic a do konzole prohlížeče zapíše zprávu s předponou [to-diane]. Nejdříve proto otevřete konzoli.

• „… is not registered“ — hlavička Origin neodpovídá žádné registrované doméně. Zkontrolujte subdomény: blog. je jiný web než holá doména, www. nikoliv.
• V konzoli nic a na stránce nic — skript se nenačetl. Hledejte porušení CSP nebo blokovač reklam.
• Na produkci funguje, na vašem počítači ne — Diane obsluhuje jen https a jen zaregistrované domény. localhost ani 127.0.0.1 nefungují; zkoušejte na doméně, kterou máte zaregistrovanou.
• Váš vlastní testovací komentář je odmítnut — přečtěte si zprávu ve widgetu a postupujte podle ní.
• Špatné vlákno v single-page aplikaci — adresa se mění způsobem, který widget nevidí. Při změně route nastavte post-slug.

Co Diane nedělá

Widget nenabízí vlákna odpovědí, hlasování, úpravy po odeslání, Markdown, avatary, účty pro čtenáře ani nic, co by dalo vědět návštěvníkovi — nikdo se nedozví, že mu někdo odpověděl. Vy se to dozvíte: konzole umí nový komentář poslat na vaše zařízení. Pokud některá z těchto funkcí rozhoduje o tom, zda Diane použijete, napište na hello@diane.to.