Balíček pluginu

Tahle kapitola je jako jediná pro jiného čtenáře než zbytek návodu. Všechno ostatní tady píšeme pro autora šablony, který jen vykresluje obsah z patra; tahle je pro toho, kdo pluginu píše kód. Pokud stavíte web, můžete ji přeskočit.

Plugin se do patra dostane jako jeden soubor: JSON s manifestem a kódem. Nahraje ho provozovatel patra ve skladu pluginů a od té chvíle si ho jednotlivé weby můžou zapnout. Žádný obchod, žádné cizí autory — nahrávat smí jeden člověk.

Tvar souboru

{
  "manifest": { "slug": "muj-plugin", "version": "1.0.0", "…": "…" },
  "code": "export default { hooks: { … } };"
}

Dva klíče a oba povinné.

manifest je smlouva o tom, co plugin smí — schopnosti, adresy, na které smí ven, kolekce úložiště, háčky, úlohy, vlastní routy a bloky. Musí jít přečíst bez spuštění kódu: podle něj se teprve staví pískoviště, ve kterém plugin poběží, a vlastník webu podle něj odklikává souhlas. Číst ho z běžícího pluginu by znamenalo pustit cizí kód dřív, než se ví, co smí.

code je hotový JavaScript, ne TypeScript a ne modul k sestavení. Není to zjednodušení: isolate, ve kterém plugin běží, žádný build krok nemá — kód se do něj předává jako text. Kdo píše plugin v TypeScriptu, přeloží si ho čímkoli a do balíčku dá výsledek.

Proč jeden soubor a ne dva vedle sebe (plugin.js + manifest.json)? Protože z dvou souborů se dá nahrát půlka. A proč ne .zip? Protože ho prostředí, ve kterém patro běží, neumí rozbalit samo a knihovna kvůli formátu za to nestojí.

Meze, na které se dá narazit

co	mez
délka kódu	512 KiB
jméno pluginu (name)	120 znaků
slug	strojový klíč (malá písmena, číslice, pomlčky)
version	číslo verze, na kterém stojí adresa balíčku

Strop kódu není platformní limit, je náš. Kód se drží v paměti a jde po drátě při nahrávání; půl megabajtu je na plugin, který se v pískovišti jen zavěsí na háčky, řádově víc než dost. Cokoli většího bývá omylem přibalený balík závislostí.

slug a version dohromady skládají adresu balíčku v úložišti, takže na obou běží kontrola abecedy — z prefixu svého pluginu se vyskočit nedá.

Blok na stránce

Plugin může do palety editoru přidat vlastní blok. Deklaruje se v manifestu a kód pluginu se kvůli němu nespouští — vykreslení stránky se pluginu na nic neptá, jinak by z každé stránky webu bylo síťové kolo do patra.

"blocks": [
  {
    "name": "vizitka",
    "label": "Vizitka",
    "description": "Kontaktní údaje pobočky.",
    "fields": {
      "nadpis":  { "kind": "string", "label": "Nadpis", "description": null, "default": null, "multiline": false },
      "telo":    { "kind": "string", "label": "Text", "description": null, "default": "Máme otevřeno do {do} hodin.", "multiline": true },
      "web":     { "kind": "url", "label": "Web", "description": null, "default": null },
      "posta":   { "kind": "email", "label": "E-mail", "description": null, "default": null }
    }
  }
]

name je strojový klíč; v datech stránky se blok jmenuje <slug pluginu>:<name>, takže se s blokem jiného pluginu ani s blokem patra srazit nemůže. label je popisek v paletě, fields jsou pole, která redaktor vyplní.

Pole se popisují týmž slovníkem jako nastavení — string, number, select, url, email. Je to celá abeceda polí, kterou má plugin — druhy polí u typů obsahu (kapitola o položkách) jsou jiný a širší seznam.

Co z toho patro vykreslí

Podobu bloku určuje pořadí a druh polí, nic jiného:

pole	jak se vykreslí
první jednořádkový string	nadpis bloku
string s multiline: true	odstavec, i se zalomeními, která redaktor napsal
url	odkaz
email	odkaz mailto:
cokoli dalšího (i další jednořádkové texty)	dvojice popisek a hodnota

Nadpis se pozná podle pořadí a druhu, ne podle jména klíče — pole nemusí být title. Roli nadpisu sebere první jednořádkový text kdekoli v pořadí; víceřádkový text ji nespotřebuje, takže kdo nadpis nechce, nesmí mít v bloku žádné jednořádkové pole druhu string.

Tři jména polí manifest odmítne a balíček s nimi nenahrajete: pluginSettings a pluginFields (těmi jmény do bloku vstupuje nastavení a popis polí, takže by se vaše hodnota při vykreslení zahodila) a id, což je klíč, ve kterém si editor drží identitu vloženého bloku.

Pole, které redaktor nevyplní, na stránce není vůbec — nezůstane po něm ani prázdný popisek. Blok, jehož pole jsou všechna prázdná, se nevykreslí celý.

Vlastní značkování plugin nedostane

To je vědomá mez, ne chybějící funkce. Manifest popisuje pole, ne HTML: plugin nedodá šablonu, třídu ani atribut, a hodnota pole se na stránku dostane vždy jako text. Adresa navíc projde kontrolou protokolu, takže javascript: v poli druhu url skončí jako text, ne jako odkaz, na který jde kliknout.

Důvod je jednoduchý: kód pluginu běží v pískovišti, ale HTML by běželo přímo na stránce klientova webu, tedy mimo cokoli, co pískoviště hlídá.

Hodnoty z nastavení se do textu dosazují zástupkou

Když má věta obsahovat hodnotu z nastavení pluginu, napíše se do ní {klíč}:

"default": "Máme otevřeno do {do} hodin."

Patro dosadí hodnotu, kterou má u toho webu vlastník uložený v nastavení pluginu. Skládat větu z kousků v kódu nejde a nemá — celé znění i s ohýbáním patří pluginu, aby šel použít i na webu v jiném jazyce.

Dvě věci, které to má:

• Blok dostane jen ty klíče nastavení, na které se odkazuje ve výchozích hodnotách svých polí. Zástupka, kterou si redaktor dopíše navíc, se nedosadí — vypadá to stejně jako překlep v názvu, a je to totéž.
• Věta se zástupkou bez hodnoty se celá vynechá. Vypsat ji se syrovým {klíč} uprostřed by vypadalo jako rozbitá stránka.

Pole se nesmí jmenovat pluginSettings ani pluginFields — těmi jmény do bloku vstupuje nastavení a popis polí, takže by se hodnota při vykreslení zahodila. Balíček s takovým polem se nenahraje.

Verze

Verze se do skladu bere z manifestu. Podle ní se balíček ukládá a podle ní si vlastník webu potvrzuje, co plugin smí — když se zvedne, administrace mu řekne, že si má znovu projít, co plugin dělá.

Táž verze podruhé neprojde. Není to technická překážka, kterou by šlo obejít: sklad drží každou nahranou verzi zvlášť, takže „opravím kód a nahraju to znovu pod stejným číslem“ by znamenalo, že dva různé kusy kódu nesou totéž jméno. Zvedněte verzi, nebo tu starou nejdřív smažte.

Balicí skript

V repozitáři patra je skript, který balíček vyrobí a zkontroluje:

pnpm plugin:pack cesta/ke/slozce/pluginu

Ve složce čeká tři soubory:

soubor	co v něm je
manifest.json	manifest
plugin.js	hotový JavaScript
package.json	jen kvůli verzi

Skript ověří, že verze v manifestu a v package.json sedí, prožene balíček toutéž kontrolou, jakou má sklad na druhé straně, a položí vedle výsledek <slug>-<verze>.json. Vadný balíček se tím pádem nedá ani vyrobit — ne až odmítnout formulářem.

Kontrola je záměrně tatáž funkce, kterou má server. Kdyby tu byla druhá sada pravidel, vznikl by balíček, který projde balením a neprojde nahráním (nebo naopak) — a mez, která vypadá jako kontrola a není, je horší než žádná.

Co se stane po nahrání

Balíček leží ve skladu a je vidět všem webům, ale sám o sobě nikde neběží. Vlastník každého webu si ho musí zapnout a přitom odkliknout, co plugin smí. Dokud to neudělá, plugin ten web nevidí.

Nová verze se nespustí sama

Zapnutím se plugin u toho webu připne na verzi, kterou vlastník viděl a odklikl. Od té chvíle na něm běží pořád ta — a nahrání novější verze do skladu na tom nic nezmění, ani kdyby to byla oprava na jeden řádek.

Je to celý smysl souhlasu: v novém manifestu si plugin může říct o schopnost, kterou dřív neměl, o další háček, o vlastní routu. Kdyby se spouštěl automaticky, znamenal by odklik jednou provždy něco, co se nedá vzít zpátky. Takhle vlastník webu uvidí v administraci ceduli „plugin se od zapnutí změnil“, projde si nový seznam schopností a potvrzením verzi přepne. Potvrzení je tentýž krok jako zapnutí, takže neexistuje druhá cesta, jak souhlas dát.

Praktické důsledky, které je lepší vědět dopředu:

• Dva weby smí běžet na dvou různých verzích téhož pluginu. Ve skladu je u každé verze vidět, kolik jich na ní visí.
• Nabízená verze je ta naposledy nahraná — ne ta s nejvyšším číslem. Kdo po 2.0.0 nahraje opravný 1.0.1, bude od té chvíle nabízet 1.0.1. Ve skladu je označená.
• Smazání verze, na které někdo visí, tomu webu plugin zastaví. Nechytne se na jinou; kdyby se chytal, byla by to přesně ta automatická výměna kódu, které se celý tenhle mechanismus vyhýbá. Administrace proto před smazáním řekne, kolika webům to udělá — a nahráním téhož balíčku zpátky se to spraví, protože verze i její obsah jsou pořád tytéž.