Přeskočit obsah
V
Pro vývojáře
Architektura, konvence, jádro systému a bezpečnost
Vzhled a témata / Témata frontendu

Témata frontendu#

Téma je celý vizuální celek webu — rozvržení, šablony, SCSS a JavaScript pohromadě. www/themes/, jádro výběru app/Core/Theme/.

Dvě navazující kapitoly rozvádějí jeho části: Struktura SCSS a Design systém a tokeny.

Struktura#

www/themes/
  admin/default/desktop/          administrace
  frontend/template1/desktop/     jedna z devíti front šablon (template1–template9)
      layouts/                    rozvržení a jejich části
      assets/{scss,css,js,dist,imgs}
      ui-demo/                    katalog komponent
      webpack.config.js
  frontend/template2/desktop/     další šablona, přepíná se z administrace

Téma má varianty podle zařízení: DefaultThemeResolver vybere mobile, tablet nebo desktop podle DeviceDetector — a když varianta v tématu neexistuje, spadne zpátky na desktop.

Které téma je aktivní#

Téma se nevybírá v kódu, ale nastavením v databázi: theme.frontend (název) a theme.frontend.path (relativní cesta, dopočítaná). Ručně se dnes needituje — administrátor je vybírá naráz se skinem v Nastavení → Vzhled webu (ThemeSettingPresenter), viz Vzhled webu. Šablon je dnes devět, template1–template9.

Přepnutí tématu v nastavení zapne totéž i na produkci

Dev a produkce sdílejí jednu databázi a tabulka nastavení nemá sloupec pro prostředí. Změna theme.frontend.path by na ostrém webu spadla nejen na jiné barvy — produkce nemá soubory nové šablony, takže by jí přestaly fungovat všechny frontové stránky kvůli chybějícím layoutům. Tohle riziko platí i pro obrazovku „Vzhled webu“ — je to jen jiné rozhraní nad týmiž klíči nastavení.

Lokálně se téma přepíná proměnnou prostředí, ne nastavením

CMS_THEME_OVERRIDE=template2 php -S 127.0.0.1:8099 -t www
Bez proměnné je to no-op — produkce ji nikdy nenastaví. Neexistující adresář se ignoruje, aby překlep neshodil web.

Cesty do tématu v šablonách#

Šablona se nesmí vázat na jméno tématu. K dispozici jsou dvě funkce (fungují i jako filtry) a jeden test:

Zápis Co udělá
{=themeAsset('assets/dist/bundle.js')} cesta k souboru uvnitř aktivního tématu
{=themeUrl('…')} absolutní URL do aktivního tématu
{if $x is isTheme('template2')} větvení podle tématu

Registruje je app/Core/Latte/Extensions/ThemeLatteExtension.php.

Cesta napsaná natvrdo přestane fungovat při přepnutí tématu

A nikdo to nezjistí, dokud se téma nepřepne — tedy typicky až u zákazníka s vlastní šablonou. V template1 je themeAsset() použitý na 30 místech.

Za asset patří ?v= s časovým razítkem

Prohlížeč jinak drží starý soubor v mezipaměti a změna se „neprojeví“.

Postup: upravuji vzhled běžícího frontendu#

  1. Ověř, kterou větev sestavení používá. V themes/ je hodně mrtvých větví — desktop_bck, scss-backup, scss_2, js2, ui-demo_old. Editace mrtvé větve je nejčastější ztráta času v téhle části systému.
  2. SCSS patří do template1/desktop/assets/scss/, sestavení:
sass assets/scss/style.scss assets/css/style.css --style=compressed
  1. JavaScript do assets/js/{components,behaviors,pages}/, sestavení:
npx webpack --config webpack.config.js
  1. Prohlédni výsledek v katalogu komponent (ui-demo/) — je to jediné místo, kde je vidět většina prvků najednou.
  2. Prokliknij i mobilní variantu, pokud ji téma má.

npx sass NENÍ totéž co sass

Je to jiná verze překladače a vyrobí jiný výstup. Používej sass.

Bez sestavení se změna SCSS neprojeví — ani po tvrdém obnovení

Aplikace čte css/style.css, ne scss/. K tomu ještě prohlížeč drží starou verzi v mezipaměti.

Postup: zakládám nové téma#

  1. Zkopíruj celý základ existujícího tématu; rozdíly drž ve vlastní vrstvě (custom/), ne rozsypané po celém stromu.
  2. Ověř to diff -r proti zdrojovému tématu — mělo by ukázat jen tvoji vrstvu, katalog komponent a výstupy sestavení. Cokoli navíc je nechtěná odchylka, která se při další opravě zdrojového tématu rozejde.
  3. Nezapínej ho v nastavení, dokud nejsou soubory nasazené všude (viz varování výš). Na vývoj používej CMS_THEME_OVERRIDE.
  4. Projdi varianty zařízení — chybějící mobile spadne na desktop, což je v pořádku jen tehdy, když je desktopové rozvržení responzivní.

Jak přidat šablonu#

Nová šablona je adresář www/themes/frontend/<název>/ se stejnou strukturou jako ostatní (desktop/, případně mobile//tablet/). Vedle něj patří manifest theme.json:

{
    "label": "Přírodní kosmetika",
    "description": "Jemný e-shop s přírodní kosmetikou",
    "color": "#c9785a",
    "order": 80,
    "group": "eshop"
}
Klíč Význam
label název v nabídce šablon
description krátký popis pod názvem
color barva kolečka / náhradní plochy, když chybí printscreen
order pořadí v rámci skupiny
group slug skupiny, viz níž

group je slug ze slovníku App\Core\Theme\ThemeCatalog::GROUPS (eshop, classifieds, company, magazine, other), ne volný text. Název skupiny, který se zobrazí v administraci, je text CMS a musí být přeložený do cs/sk/en — volný text z manifestu by se do překladů nedostal. Neznámý nebo chybějící slug spadne do other, takže překlep v manifestu nikdy nezpůsobí pád obrazovky.

Náhledy pro administraci#

Obrazovka Vzhled webu potřebuje ke každé šabloně a jejímu skinu printscreen hlavní strany. Generuje je:

php bin/theme-previews.php              # všechny šablony
php bin/theme-previews.php template5    # jen jedna šablona

Skript vyfotí headless Chromem hlavní stranu běžícího dev serveru (127.0.0.1:8000) a uloží:

  • <šablona>/preview.webp — základní barva,
  • <šablona>/previews/<skin>.webp — každá další barevná varianta.

Formát je WebP, ne PNG — táž sada náhledů měla v PNG 9,2 MB, ve WebP 1,4 MB.

Generátor nespouštěj, když se zrovna na webu pracuje

Vyfotí web přesně v tom stavu, v jakém zrovna je — rozpracované úpravy souborů nebo přepnuté téma v administraci se tak dostanou přímo do náhledu. Chyba se přitom nepozná automaticky: skript hlídá jen to, že Chrome doběhl a soubor vznikl, ne že snímek nezachytil chybovou stránku. Stalo se to a poznalo se to až okem.

Po předělání šablony náhledy přegeneruj

Negenerují se samy při buildu ani při deploy. Bez ručního spuštění skriptu administrace ukazuje starý vzhled.

Chybějící náhled není chyba — karta šablony nebo skinu se v administraci vykreslí i bez obrázku, místo něj barevná plocha z color v manifestu.

Přístupnost#

Rozbalovací prvky dělej přes <details>, kde to jde

Funguje to bez JavaScriptu, čtečky si s tím poradí a nepotřebuje to žádné ARIA atributy navíc.

Skills pro práci se šablonami#

Skill Pro co
cs-template-layout rozvržení
cs-template-subpage podstránka
cs-template-from-image šablona podle obrázku
cs-template-from-sample šablona podle ukázky
cs-ui-audit kontrola hotového vzhledu

Kam sáhnout#

Chci Kde
výběr tématu a varianty app/Core/Theme/DefaultThemeResolver.php
funkce themeAsset / themeUrl app/Core/Latte/Extensions/ThemeLatteExtension.php
aktivní front téma www/themes/frontend/template1/desktop/
katalog komponent www/themes/frontend/template1/desktop/ui-demo/
téma administrace www/themes/admin/default/desktop/

Navazující kapitoly: Struktura SCSS · Design systém a tokeny · Šablony Latte · Komponenty