Diane, poznámka do spisu. Všechno, co se schránce dá říct.

Návod.

Dva řádky HTML — a pak asi tucet věcí, které se hodí vědět, když má schránka dělat něco trochu jinak. Kromě první sekce je všechno tady nepovinné.

Nastavení

  1. Přihlaste se na admin.diane.to Googlem.
  2. Přidejte doménu. Jeden řádek na jeden hostname: www.example.com a example.com jsou jeden web, blog.example.com se registruje zvlášť.
  3. Vložte do stránky tyhle dva řádky:
<script async defer src="https://diane.to/w.js"></script>
<to-diane></to-diane>

Skript může být v hlavičce i na konci stránky — je async defer, takže vykreslování nezdrží ani v jednom případě. Element patří přesně tam, kde má schránka být.

V tom kódu není žádný klíč, žádné id webu a žádné nastavení pro jednotlivou stránku. Je to záměr: nic ve veřejném HTML není tajné, takže id by bylo směrování vydávané za bezpečnost. Web se pozná podle hlavičky Origin, stránka podle své adresy.

Který web, která stránka

Web se pozná z hlavičky Origin, kterou prohlížeč připojí ke každému požadavku mimo vlastní doménu a kterou JavaScript na stránce nepodvrhne. Porovnává se přesně s tím, co máte zaregistrované; jediná výjimka je jedno úvodní www., které se odřízne. Každá další subdoména je samostatný web s vlastní registrací.

Stránku hledá widget na třech místech, v tomto pořadí:

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

Výsledek se na obou stranách upravuje stejným kódem: pryč jde query string, fragment, zdvojená i koncová lomítka, a delší než 200 znaků se odmítne. /post, /post/ a /post?utm_source=rss jsou proto jedno vlákno.

Z toho plyne obojí, co občas potřebujete: dva elementy na jedné stránce s různým post-slug drží dvě samostatná vlákna, a kanonický odkaz mířící jinam slije přetištěné kopie článku do jednoho vlákna, aniž byste museli cokoliv nastavovat.

Atributy

AtributK čemu je
post-slugIdentifikátor vlákna, když nemá být odvozený z adresy. Libovolný řetězec do 200 znaků.
langJazyk popisků, když nemá být převzatý z <html lang>.
<to-diane post-slug="/blog/twin-peaks"></to-diane>

Oba jsou nepovinné a žádné další nejsou.

Weby s vlastním routováním

Změnu adresy si widget hlídá sám: poslouchá popstate, používá Navigation API, a kde ho prohlížeč nemá, jednou za sekundu porovná location.href. history.pushState záměrně nepřepisuje — dělají to měřicí skripty, funguje to, ale sahat do cizí stránky je přesně to, co tenhle widget slibuje nedělat.

Běžná single-page aplikace tedy nepotřebuje nic. Pokud se ale vlákno neurčuje adresou, nastavte při změně route atribut:

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

Odpověď, která dorazí až po odchodu na jiný článek, se zahodí, takže rychlé proklikání nenechá na obrazovce komentáře z předchozí stránky. Rozepsaný komentář se při přechodu smaže: patřil k článku, pod kterým vznikl.

Vzhled

Widget si z vaší stránky vezme jedinou barvu — barvu textu — a zbytek si z ní namíchá. prefers-color-scheme záměrně ignoruje: vložená schránka má ladit se stránkou, ve které sedí, ne s operačním systémem návštěvníka, jinak by světlý web vypadal rozbitě každému, kdo má počítač přepnutý do tmavého režimu. Na většině webů se proto nenastavuje nic.

Když přece, nastavte na elementu 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;
}
VlastnostVýchozíCo ovlivní
--td-fontsystémový bezpatkový fontpísmo celé schránky
--td-gap16pxrozestupy
--td-radius8pxrohy polí a tlačítka
--td-bubble-radius14pxrohy bublin s komentáři
--td-surface11 % barvy textupozadí komentáře
--td-border24 % barvy texturámečky polí a tlačítka
--td-muted62 % barvy textujména, data, vedlejší text
--td-button-bg13 % barvy textupozadí tlačítka
--td-button-bg-hover20 % barvy textutlačítko pod myší
--td-button-fgbarva textu stránkytext tlačítka
--td-danger#e5484dchybové hlášky

Ven jsou vystavené dvě části: ::part(root) je celý blok a ::part(powered) podpis „Powered by diane.to“ pod formulářem. Podpis dědí tlumenou barvu, dá se přebarvit, nebo schovat:

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

Všechno ostatní je uvnitř shadow rootu a ze stránky se na to nedosáhne — právě proto vypadá widget stejně na každém webu, kde je vložený. Velikost na stránce je vaše: element je display: block, takže mu klidně dejte max-width.

Jazyk

Popisky se berou z <html lang> vaší stránky, stejně jako barva. Atribut na elementu to přebije:

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

Dnes umí widget anglicky a česky. Neznámý jazyk dostane anglické popisky, ale data zůstanou v locale stránky, takže německý web má německá data a anglické popisky, ne obojí špatně. Počty procházejí přes Intl.PluralRules, aby čeština dostala tři tvary tam, kde angličtina potřebuje dva. Chybí vám jazyk? Napište na hello@diane.to, je to jedna položka v tabulce.

Proč komentář neprojde

Žádná CAPTCHA. Místo ní čtyři laciné vrstvy — a každá se pozná podle toho, co uvidíte:

Chybové hlášky se návštěvníkovi ukazují v jazyce widgetu.

Sto komentářů

Bezplatný účet unese sto živých komentářů na jeden web. Nad limit server další komentáře odmítne a schránka řekne, že je plná — čtení běží dál, protože plný limit není důvod schovávat, co už je napsané.

Smazané komentáře se do limitu nepočítají, takže moderováním se místo zase uvolní. A protože mazání je vratné, není to rozhodnutí na jednu stranu. Ve vlákně se zobrazí nejvýš 500 komentářů.

Moderace

Všechno je v konzoli na admin.diane.to: společná schránka se všemi komentáři od nejnovějšího, detail webu rozpadlý po vláknech, přepínač pro zobrazení smazaných, mazání a obnovení, přejmenování webu a vypínač, kterým celý web umlčíte — widget pak na té doméně nevykreslí nic a návštěvník žádnou chybu neuvidí.

Schvalovací fronta neexistuje. Komentář se objeví hned, jak ho někdo odešle, a moderuje se až potom.

Co se ukládá

Jméno, které návštěvník napsal, text, čas a nesolený otisk SHA-256 jeho IP adresy. Otisk se jen porovnává na shodu kvůli omezení počtu a nevrací ho žádný endpoint. Widget na vašem webu nenastaví ani nepřečte jedinou cookie a nenačte nic z třetí strany.

Komentáře se ukládají přesně tak, jak přišly, a vykreslují se jako text, ne jako HTML: žádný Markdown, žádné automatické odkazy — a a < b zůstane a < b. Podrobnosti jsou na stránce Soukromí.

Content Security Policy

Pokud váš web posílá CSP, týkají se widgetu tři direktivy:

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

script-src kvůli souboru, connect-src kvůli volání API. style-src proto, že styly widgetu jsou element <style> uvnitř jeho shadow rootu, kam se nonce nedostane. Nic dalšího se povolovat nemusí: widget nenačítá fonty, obrázky ani nic cizího.

Když se nic neukáže

Chybu v nastavení widget návštěvníkovi nikdy neukáže — nevykreslí nic a napíše do konzole prohlížeče hlášku s předponou [to-diane]. Takže první krok je otevřít konzoli.

Co Diane nedělá

Nemá vlákna odpovědí, hlasování, úpravu odeslaného komentáře, schvalovací frontu, notifikace, Markdown, avatary ani účty pro čtenáře. Každá z těch věcí by byla víc kódu než všechno ostatní dohromady, a widget má 24 kB. Jestli je zrovna jedna z nich rozdíl mezi „použiju“ a „nepoužiju“, napište na hello@diane.to — dobré vědět, i když odpověď bude ne.