Doplněk Stamp v1.0.3

Vít Petira 6 minuty, 33 sekundy 179 doplňky upgrade 1.7

Po několika měsících je tu doplněk Stamp v1.0.3, který nabízí možnost výběru formátu jména (na výběr je plné jméno uživatele nebo jeho uživatelské jméno) uživatele (autora, resp. editora), které se uloží do hlavičky stránky a následně se může zobrazit v záhlaví článku (nebo jakéhokoliv typu stránky).

Přes víkend krásně pršelo, což se přímo nabízelo k dodělání restů, a tak jsem to využil k úpravám nové verze doplňku Stamp, který je ode dneška dostupný ve verzi 1.0.3 v repozitáři, resp. připraven k přímé instalaci přes Admin Panel.

Původně jsem chtěl, aby v této verzi byla zakomponována taxonomie a možnost přidání více autorů, na níž jsem začal pracovat po vydání verze 1.0.1. Mezitím však v lednu 2021 vyšel Grav v1.7 (a Admin v1.10), který má odlišné API, což se projevilo i na náhlé (ne)funkčnosti rozpracovaného doplňku, který byl vyvíjen ještě ve verzi 1.6.

V lednu 2021 přestal vzhledem k předchozímu na Gravu v1.7 fungovat tehdy aktuální Stamp v1.0.1, což vedlo k mimořádnému vydání verze 1.0.2, která problém s API řešila, nicméně zůstala stejná funkcionalita jako ve verzi 1.0.1.

Jelikož nastal čas na vydání nové verze doplňku, rozhodl jsem se taxonomii (a s ní spojené přínosy) přesunout až do další verze a místo ní zakomponovat jiné zásadní vylepšení, které spočívá v možnosti výběru formátu jména uživatele (autora, resp. editora), které se uloží do hlavičky stránky a následně se může zobrazit v záhlaví článku (nebo jakéhokoliv typu stránky). Na výběr je plné jméno uživatele (Joe Doe) nebo jeho uživatelské jméno (doe).

Již při vývoji první verze jsem měl dilema, které z uvedených mám použít, a přestože jsem osobně preferoval uživatelské jméno pro jeho nespočetné výhody, zejména unikátnost a možnost dalšího zpracování včetně navázání na další prvky (viz níže), nakonec zvítězilo použití plného jména uživatele, především z důvodu kompatibility se „sesterským“ doplňkem Auto Author. Časem se pochopitelně ukázalo, že to byla slepá ulička. Doplněk Stamp je na doplňku Auto Author nejen zcela nezávislý, ale de facto jej plně nahrazuje (zásadní rozdíl spočívá pouze v okamžiku, kdy dochází k vytvoření autora, tj. buď již při vytvoření stránky, nebo až při jejím uložení), resp. přináší mnohem více možností.

Bylo tedy otázkou času, kdy dojde k přepracování. Určitým impulsem byl podnět od jiného uživatele doplňku, nicméně uvedené ve mně zrálo zcela nezávisle již nějakou dobu, kdy jsem na ostrých webech vnímal omezení, která to přináší. Nakonec jsem ponechal na výběr obě možnosti, přičemž plné jméno uživatele je ponecháno z důvodu zpětné kompatibility jako výchozí možnost. Koneckonců někomu, kdo potřebuje zobrazit pouze lidsky čitelnou podobu jména, aniž by ji dále zpracovával, tato možnost může vyhovovat více.

Pro ostatní je k dispozici druhá možnost v seznamu, a to uživatelské jméno. Osobně doporučuji tuto možnost vybrat v okamžiku nové instalace doplňku Stamp, ale nic nebrání ani tomu, vybrat tuto možnost i na funkčním webu, kde Stamp již nějakou dobu běží. Jediné co je třeba mít na vědomí je, že všechny stránky uložené před změnou formátu jména budou uloženy s plným jménem a stránky uložené následovně (včetně již existujících) již s uživatelským jménem. Pokud víte, že to nezpůsobí žádné komplikace (vše lze případně ošetřit v šablonách), tak rozhodně neprodleně změňte.

V čem tedy spočívá ta výhoda, o které tady pořád píšu? Zatím jsme docílili pouze toho, že jsme z pěkného a lidsky čitelného jména vytvořili cosi, co na svých stránkách rozhodně nechceme zobrazovat. Existuje však několik možností, jak z uživatelského jména (které je na rozdíl od plného jména jedinečné), vytvořit nejen plné uživatelské jméno, ale též vytěžit i další informace, které se uživatele týkají.

Jednou z možností je vytvořit úložiště autorů na úrovni stránek, tj. vytvořit např. stránku /author, která bude obsahovat podstránky jednotlivých autorů. Autor Joe Doe s uživatelským jménem doe bude prezentován např. na stránce https://www.grav.cz/author/doe, která bude mít nadpis Joe Doe a popř. bude obsahovat i další proměnné v hlavičce stránky (info, e-mail, web atd.), a tato stránka bude mít navíc přiřazenou šablonu (např. author.twig.html), která zajistí zobrazení všech příspěvků od tohoto autora, ale třeba i komplexní informace o něm. Pomocí jedinečného uživatelského jména uloženého v proměnné author v hlavičce stránky pak můžeme Twig kódem v šabloně zajistit, že v záhlaví článku (nebo třeba v postranním panelu, podle toho, kde bude kód umístěn) zobrazíme např. následující:

Autor: Joe Doe, Zveřejněno: 30. 8. 2021 12:34:56

(Pozn.: Jedná se pouze o demonstrativní příklad, odkaz není funkční.)

Twig kód zajistí to, že vezme uživatelské jméno (v tomto případě doe), zkusí vyhledat stránku s tímto slugem (jedinečná část URI pro konkrétní stránku, v tomto případě doe) ve složce /author, a pokud existuje, vrátí nadpis stránky (v tomto případě plné jméno autora), který zabalí do odkazu směrujícího na stránku (v tomto případě v relativním tvaru /author/doe). Nic nebrání tomu, aby se stejným způsobem získaly (a zobrazily) i další informace o autorovi, jako e-mail nebo bližší popis aktivit autora (uložený v proměnné about nebo subtitle, dle naší volby). Pravděpodobně je to však zbytečné, neboť tyto informace lze zobrazit v záhlaví autorovy stránky, na kterou se proklikneme přes odkaz (viz výše).

Pokud Twig kód stránku nenalezne (tato stránka prostě z pochopitelných důvodů neexistuje), pak zobrazí pouze jméno (ať již plné nebo uživatelské). To nastane samozřejmě tehdy, kdy je použito historicky plné jméno uživatele a v tomto případě se jedná přímo o ideální alternativu (zobrazí se alespoň lidsky čitelná podoba). V případě uživatelských jmen bychom se toho ale měli vyvarovat a vždy vytvořit stránku autora s kompletními informacemi. Určitě nechceme, aby se nám zobrazovalo uživatelské jméno, popř. aby se nám vrátily nesmyslné (nebo prázdné) hodnoty.

Pro komplexnost uvádím, že se můžeme pochopitelně prostřednictvím Twig filtru hyphenize pokusit převést původní plné jméno na nové uživatelské jméno (např. Joe Doe => joe-doe, Administrator => administrator), což ale nemusí vždy přinést kýžené ovoce. Co když má uživatel Joe Doe uživatelské jméno doe nebo uživatel Administrator uživatelské jméno admin? Pak ani v jednom případě nezískáme správný odkaz na stránku. Uvedené lze samozřejmě řešit aliasy, žádné meze se nekladou, spíše záleží na konkrétním stavu webu a počtu dotčených uživatelů.

Stejným způsobem se můžeme pokusit alespoň simulovat převod z uživatelského jména na plné jméno prostřednictvím Twig filtru humanize. Určitě je lepší, pokud se zobrazí Joe Doe místo joe-doe nebo Admin místo admin.

Ale vraťme se k možnostem, kterak získávat komplexní informace o autorovi na základě uživatelského jména. Tentokrát již pouze telegraficky, protože to je nad rámec tohoto článku (který se týká především doplňku Stamp).

Druhou z možností je získat data uložená v některém Flex Objektu, v našem případě například z contacts. Tato varianta, stejně jako první, má tu výhodu, že může obsahovat autory, kteří nemusí být nutně registrováni jako uživatelé. To po pravdě mírně koliduje s filozofií doplňku Stamp, jehož účelem je vyplnit jméno (plné nebo uživatelské) autora/editora na základě údajů právě přihlášeného uživatele, nicméně se počítá s možností s ruční editace. Jde spíše o to si uvědomit, že tu tato možnost získání dat existuje.

Třetí možností je „hacknout“ složku /user/accounts (resp. indexovaná flex data v souboru /user/data/flex/indexes/accounts.yaml), která obsahuje všechny registrované uživatele s údaji, které byly zadány při registraci. Uživatelské účty byly v rámci verze 1.7 zkonvertovány rovněž na Flex Objekty, avšak jejich přímé použití je možné pouze v Admin Panelu.

U těchto dvou způsobů je nutno počítat s tím, že obsahují pouze omezené informace, dané jejich vstupními formuláři. Není opět samozřejmě problém je rozšířit, ale je třeba si dát pozor, aby to nemělo dopad na funkcionalitu. V každém případě si tyto dvě možnosti zaslouží v budoucnu podrobnější popis (viz závěrečný odstavec).

Čtvrtou možností je použití databáze s komplexními údaji o autorech, v případě Gravu pak SQLite, ale to už je spíše extrém a nepřináší proti prvnímu způsobu prakticky žádné výhody.

Podrobné informace k doplňku Stamp v1.0.3 včetně Twig kódu pro úložiště na bázi stránek jsou v souboru README.md. Další možnosti zveřejním následně, jak v souboru README.md, tak pravděpodobně v rámci kompletních šablon stamp-*.twig.html přímo v doplňku (až je odladím do co největší komplexnosti a univerzálnosti), a v neposlední řadě pochopitelně i na webu Grav.cz.

Předchozí příspěvek Následující příspěvek