Specyfikacja szablonów

# Specyfikacja szablonów GoBiz — dla projektantów i agentów AI **Wersja:** 4.3 — 19 listopada 2026 **Zakres:** paczka szablonu (ZIP), instalacja przez panel i przez MCP, budowa nawigacji i treści serwisu publicznego. Wersja 4.0 zastępuje 3.16. Opisuje stan faktyczny kodu renderującego, a nie zamierzenia — to, czego system nie robi, jest wymienione w rozdziale 15. **Zmiany w 4.3:** logo firmy przez MCP (rozdz. 5.3), mega menu z podpozycji i pasek aktualności opisane jako zalecane (rozdz. 11.3, 12.1), linki paska do domeny firmy źródłowej, nowe pułapki CSS: limit wysokości logo, centrowanie mega menu, tło otwartego menu mobilnego (rozdz. 9.2), animacje SVG a ograniczony ruch (rozdz. 9.6), `select` w `Find_*` (rozdz. 13.1). Nowe przykłady: `szablon-structum-siv`, `szablon-gobiz-2027`. **Najważniejsze zmiany względem 3.16** | Było (3.16) | Jest (4.0) | |---|---| | „120 bloków” — 120 wymaganych plików `blocks/*.html` | Jest 31 typów bloków; szablon dostarcza pliki dla 19 z nich (rozdz. 8). Dawne „120 bloków” to warianty pola `variantType` — nie mają własnych plików. | | Wszystko wymagane („szablon odrzucany”) | Twarde wymagania importera to 4 rzeczy (rozdz. 2.2). Reszta to zalecenia sprawdzane przez walidator jako ostrzeżenia. | | Import tylko z panelu | Także przez MCP: `szablon_strony_waliduj`, `szablon_strony_importuj`, `szablon_strony_przypisz`, `szablon_strony_get` (rozdz. 13). | | Paczka po instalacji przepadała | Archiwum paczek i przenoszenie dev → produkcja (rozdz. 13.2, od 4.1). | | `navigation.json` — jedno menu, same adresy | Wiele menu w jednym pliku, pozycje wskazujące strony po slugu (rozdz. 11). | | Strony z paczki bez tytułów i SEO | Metadane stron w `template.json → pages` (rozdz. 3.4). | | Własne menu mobilne, akordeon i wyszukiwarka w `global.js` | Obsługuje je system; `global.js` zawiera tylko logikę własną szablonu (rozdz. 10). | | Limit pola 1 000 000 znaków | 500 000 znaków. | | `template.headerType`, `template.heroTypeRel`, sekcja `blocks` w `template.json`, `assets/*` | Nieużywane — usuń z paczki. | --- ## 1. Jak powstaje serwis Serwis publiczny firmy (tenanta) to trzy rzeczy: **szablon** (wygląd), **nawigacja** (menu) i **treść** (strony, wpisy, usługi, produkty…). Agent AI wykonuje całość narzędziami MCP: 1. **Rozpoznanie** — `whoami`, `tenants_lista` (ID firmy), `tenant_get` (dane firmy trafiają do placeholderów `{phone}`, `{companyName}` itd.), `describe_collection` (pola kolekcji i bloków — nie zgaduj nazw pól). 2. **Projekt szablonu** — pliki z rozdziału 2, spakowane tak, by `template.json` leżał w korzeniu ZIP. 3. **Walidacja** — `szablon_strony_waliduj {zipBase64, tenant}`: błędy, ostrzeżenia i plan importu, bez zapisu. 4. **Instalacja** — `szablon_strony_importuj {zipBase64, tenant, ustawDomyslny: true}`. 5. **Treść** — `media_upload`, `Create_pages` (bloki w polu `layout`), `Create_wpisy`, `Create_services`, `Create_tags`, a dla sklepu `Create_products` i `kategoria_utworz`. 6. **Nawigacja** — `navigation.json` w paczce + `importujNawigacje: true` (wiele menu naraz) albo `Create_navigation` pozycja po pozycji. 7. **Strona startowa** — `stronaStartowa` przy imporcie albo `szablon_strony_przypisz {tenant, stronaStartowa}`. 8. **Sprawdzenie** — otwórz serwis w przeglądarce (desktop i telefon). Poprawki szablonu: ponowny import tej samej paczki aktualizuje szablon po slugu. Adres serwisu firmy bez własnej domeny: `/<ścieżka>?tenant=<slug firmy>`. Z domeną wpisaną w polu „Domeny (hosty)” firmy — zwykłe adresy. Wzorcowa, działająca paczka: szablon `infobiz` — źródła zwraca `szablon_strony_get {szablon: "infobiz", pliki: true}`. --- ## 2. Paczka ZIP ### 2.1. Struktura ``` szablon.zip ├── template.json konfiguracja (WYMAGANY) ├── header.html nagłówek ├── footer.html stopka ├── header.css style nagłówka i nawigacji ├── footer.css style stopki ├── global.css style treści, bloków, klas pomocniczych ├── global.js logika własna szablonu ├── preview.png podgląd 800×600 px (opcjonalny) ├── navigation.json menu (opcjonalny) ├── demo-page.html strona pokazowa (opcjonalna) → slug demo-<slug szablonu> ├── layouts/ │ ├── bare.html WYMAGANY │ ├── single-column.html WYMAGANY │ └── full-page.html opcjonalny ├── blocks/ szablony bloków — rozdz. 8 │ └── <blockType>.html └── pages/ strony treści (opcjonalne) → slug = nazwa pliku └── <slug>.html ``` Kodowanie UTF‑8, końce linii LF. Wielkość liter w nazwach ma znaczenie. Plików spoza tej listy importer nie używa (walidator je wypisze); katalog `assets/` jest ignorowany — obrazy wgraj przez `media_upload` i wstaw ich adresy, albo użyj inline SVG. ### 2.2. Wymagania twarde (bez nich import jest odrzucany) 1. `template.json` w korzeniu archiwum, poprawny JSON z sekcją `template`; 2. `template.name` oraz `template.slug` zgodny z `[a-z0-9-]+`; 3. `layouts/bare.html` i `layouts/single-column.html`, oba z `{page:content}`; 4. pliki CSS bez znacznika `<style>` (to czysty CSS — system sam go opakowuje). Odrzucane są też: `layout.slug` równy nazwie układu wbudowanego (`simple`, `two-row`, `ecommerce`, `minimal`, `automotive`, `city`, `zefe`), pole CSS/HTML/JS dłuższe niż 500 000 znaków, niepoprawny JSON w `navigation.json`, `preview.png` niebędący plikiem PNG, nazwa pliku w `pages/` niezgodna z `[a-z0-9-]+`. ### 2.3. Limity | Co | Limit | |---|---| | Plik ZIP | 20 MB | | Paczka po rozpakowaniu | 60 MB, 2000 plików | | `global.css` + `header.css` | 500 000 znaków łącznie | | `global.css` + `footer.css` | 500 000 znaków łącznie | | `header.html`, `footer.html`, `global.js` | po 500 000 znaków | Importer skleja `global.css` z `header.css` i osobno z `footer.css`; oba wyniki trafiają na stronę, więc **`global.css` jest w dokumencie dwa razy**. Trzymaj go zwięźle; nie umieszczaj w nim reguł, które zmieniają znaczenie przy drugim wczytaniu (np. liczników CSS). Realny szablon to 20–35 tys. znaków `global.css`. ### 2.4. Pakowanie Pliki muszą leżeć w korzeniu archiwum: ```bash cd szablon && zip -r ../szablon.zip . -x '.*' ``` (Jeśli spakujesz katalog, importer zdejmie jeden poziom — ale tylko wtedy, gdy archiwum zawiera dokładnie jeden katalog nadrzędny.) --- ## 3. `template.json` ```json { "template": { "name": "InfoBiz Server", "slug": "infobiz", "description": "Krótki opis widoczny w panelu", "pageWidth": "boxed", "showBreadcrumbs": true, "cssClasses": "theme-infobiz", "availableBlocks": "", "colors": { "primary": "#0B1F3A", "primaryLight": "#1B3B6B", "accent": "#0A7F5E", "bg": "#FFFFFF", "text": "#142033", "bodyBg": "#FFFFFF", "sectionAlt": "#F2F6FA", "headerBg": "#FFFFFF", "headerNavLink": "#142033", "topBarBg": "#0B1F3A", "topBarLink": "#D7E3F4", "footerBg": "#081527", "heroBg": "#0B1F3A", "buttonBg": "#0A7F5E", "buttonText": "#FFFFFF" } }, "layout": { "type": "custom", "name": "InfoBiz Server — układ", "slug": "infobiz" }, "layouts": { "single-column": "layouts/single-column.html", "full-page": "layouts/full-page.html", "bare": "layouts/bare.html" }, "pages": { "kontakt": { "title": "Kontakt", "metaTitle": "Kontakt — InfoBiz Server", "metaDescription": "…", "hideTitle": false } }, "tenantAssignment": { "tenantSlug": "infobiz", "setAsDefault": false, "homepage": "start" } } ``` ### 3.1. Sekcja `template` | Pole | Wymagane | Opis | |---|---|---| | `name` | tak | Nazwa szablonu | | `slug` | tak | Identyfikator `[a-z0-9-]+`. **Import o istniejącym slugu aktualizuje szablon.** | | `description` | zalecane | Opis w panelu | | `pageWidth` | nie | `boxed` (1200 px, domyślnie) / `wide` (1600 px) / `full` (100%) | | `showBreadcrumbs` | nie | Domyślnie `true` | | `cssClasses` | nie | Klasy dodawane do opakowania strony | | `availableBlocks` | nie | **Zostaw puste** = wszystkie bloki. Lista (po przecinku) bez `archive` i `form` ukrywa bloki `archive` i `formBlock`. | | `colors` | zalecane | 15 kolorów — rozdz. 6 | ### 3.2. Sekcja `layout` Zawsze `"type": "custom"` z własnym `name` i `slug`. `slug` wskazuje rekord nagłówka/stopki (HTML, CSS, JS, układy, bloki) — **musi być unikalny w całym systemie**; najprościej równy `template.slug`. Bez sekcji `layout`, ale z `header.html`/`footer.html` w paczce, system przyjmie `type: custom` i `slug = template.slug`. `"type": "builtin"` + `builtinSlug` podpina szablon pod układ wbudowany systemu i **ignoruje wszystkie pliki HTML/CSS/JS z paczki** — nie używaj. Import odmawia nadpisania: - układu wbudowanego systemu (`BUILTIN_TYPE_PROTECTED`), - układu używanego także przez inne szablony (`LAYOUT_SHARED`), - szablonu używanego przez firmy spoza zakresu klucza (`TEMPLATE_USED_BY_OTHER_TENANT`). Rozwiązanie we wszystkich trzech przypadkach: własny, nowy `slug`. ### 3.3. Sekcja `layouts` Obiekt `nazwa układu → ścieżka pliku`. Liczą się klucze; pierwszy jest oznaczany w panelu jako domyślny. Faktyczny wybór układu opisuje rozdz. 7. ### 3.4. Sekcja `pages` (opcjonalna) Metadane stron importowanych z `pages/<slug>.html` (klucz = slug; dla `demo-page.html` klucz `demo-page`): | Pole | Opis | |---|---| | `title` | Tytuł strony (bez niego powstaje z nazwy pliku) | | `metaTitle`, `metaDescription` | SEO | | `layoutPreference` | `single-column` / `full-page` / `bare` | | `pageWidth` | `boxed` / `wide` / `full` | | `hideTitle`, `hideBreadcrumbs` | Ukrycie tytułu / okruszków | | `published` | Nadpisuje opcję publikacji importu dla tej strony | Plik `pages/<slug>.html` trafia do pola `contentHtml` strony. Strony z blokami twórz przez `Create_pages` (rozdz. 12). ### 3.5. Sekcja `tenantAssignment` (opcjonalna) `tenantSlug` — firma docelowa dla stron i menu z paczki; `setAsDefault: true` — ustaw szablon jako domyślny firmy; `homepage` — slug strony startowej. **Import przez MCP nie stosuje tej sekcji po cichu**: firmę i opcje podaje się argumentami narzędzia (rozdz. 13). Sekcja działa przy imporcie z panelu. --- ## 4. Jak system składa stronę Znajomość tych opakowań oszczędza większość błędów w CSS. ```html <div class="tenant-<slug firmy> <cssClasses>" data-tenant-slug="…" style="--tenant-primary:…; --tenant-accent:…; --st-page-max-width:…"> <style>…global.css + header.css…</style> <div style="position:relative;z-index:200"> <header> ← element systemu; tu trafia klasa .nav-open …header.html… </header> </div> <div style="padding:3rem 0"> ← kontener strony <div style="max-width:<pageWidth>;margin:0 auto;padding:0 1rem"> <h1 style="…">Tytuł strony</h1> ← inline; ukryjesz polem hideTitle <div class="html-content">…contentHtml…</div> <div class="my-8">…blok…</div> ← każdy blok osobno </div> </div> <style>…global.css + footer.css…</style> <footer style="background:<footerBg>;color:#cbd5e0;position:relative"><div> …footer.html… </div></footer> </div> ``` Wnioski: - **Nie zaczynaj `header.html` od `<header>` ani `footer.html` od `<footer>`** — powstałby element zagnieżdżony w takim samym. Użyj `<div class="st-header">` / `<div class="st-footer">`. - Treść strony zawsze siedzi w kontenerze o szerokości `pageWidth`. Sekcję na pełną szerokość okna robi się wzorcem z rozdz. 9.3. - Tytuł `<h1>` strony ma style inline (kolor `primary`, pasek akcentu). Na stronach z własnym hero ustaw `hideTitle: true`. - Zmienne CSS dostępne na opakowaniu: `--tenant-primary`, `--tenant-primary-light`, `--tenant-accent`, `--tenant-text`, `--tenant-body-bg`, `--tenant-button-bg`, `--tenant-button-text`, `--st-page-max-width`. - Baner cookies, panel wyszukiwania, przycisk „do góry”, formularze i okruszki mają style inline — szablon ich nie rysuje. - Ikony **Phosphor** są ładowane globalnie: `<i class="ph ph-phone"></i>`. --- ## 5. Nagłówek i stopka ### 5.1. Wzorzec `header.html` ```html <div class="st-header"> <div class="st-topbar"> {if:phone}<a class="st-topbar-link" href="tel:{phone:attr}">{phone}</a>{/if:phone} {if:experienceMessage}<span class="st-experience">{doswiadczenie}</span>{/if:experienceMessage} </div> <div class="st-header-main"> <div class="st-logo">{logo}</div> <button class="st-hamburger" type="button" aria-label="Menu" aria-expanded="false"> <span class="st-hamburger-bar"></span><span class="st-hamburger-bar"></span><span class="st-hamburger-bar"></span> </button> <nav class="st-header-nav" aria-label="Nawigacja główna">{nav:structured}</nav> <div class="st-header-actions">{search}{authLinks}{cart}</div> </div> </div> ``` Wymagane elementy: - **`<nav class="st-header-nav">`** wokół menu — systemowy skrypt menu mobilnego ukrywa i pokazuje elementy `<nav>` wewnątrz nagłówka; - **`<button class="st-hamburger">`** — bez niego nie ma menu na telefonie; - **`{authLinks}`** — bez niego nie ma linku logowania; - `{logo}` wstawiany bezpośrednio (to już jest link — nie opakowuj go w `<a>`). ### 5.2. Placeholdery — co działa gdzie | Placeholder | Nagłówek | Stopka | Treść i bloki | |---|:-:|:-:|:-:| | Dane firmy: `{fullName}` `{companyName}` `{shortName}` `{nip}` `{vatUe}` `{regon}` `{krs}` `{bdo}` `{pkd}` `{bankAccount}` `{street}` `{postalCode}` `{city}` `{country}` `{phone}` `{email}` `{tagline}` `{year}` `{lang}` `{lata}` `{doswiadczenie}` | ✔ | ✔ | ✔ | | Warianty do atrybutów: `{fullName:attr}` `{shortName:attr}` `{phone:attr}` `{email:attr}` `{tagline:attr}` `{street:attr}` `{postalCode:attr}` `{city:attr}` `{country:attr}` `{copyright:attr}` | ✔ | ✔ | ✔ | | `{tenantSlug}`, `{tenantQuery}` (`tenant=slug`), `{iod.email}`, `{iod.name}` | ✔ | ✔ | ✔ | | Adresy: `{homepageUrl}` `{basePath}` (pusty) `{privacyPolicyUrl}` `{regulaminUrl}` `{cookiePolicyUrl}` `{rodoUrl}` | ✔ | ✔ | ✔ | | Kolory `{c:nazwa}`, `{c:nazwa||#fallback}` | ✔ | ✔ | ✔ (zestaw okrojony — rozdz. 6) | | `{logo}` | ✔ link z logo | ✔ | sam obraz | | `{nav}`, `{nav:structured}`, `{nav:NAZWA}` | ✔ | ✔ | ✘ | | `{search}`, `{cart}` | ✔ | ✔ | ✘ | | `{authLinks}` | ✔ (tylko pierwsze wystąpienie na stronie) | — | — | | Warunki `{if:klucz}…{/if:klucz}`, `{ifnot:klucz}…{/ifnot:klucz}` (zagnieżdżalne), `{if:tenant:id=3}`, `{if:tenant:include=1,3}`, `{if:tenant:exclude=1,3}` | ✔ | ✔ | ✔ | | `{tenants:list…}`, `{doc:kolekcja:id[:pole][:template=slug]}` | ✘ | ✔ | ✔ | | Widżety `{konwerter_slownie}` `{kalkulator_biurowy}` `{kalkulator_naukowy}` `{dokumentacja}` | ✔ | ✔ | ✔ | Uwagi: - **`{copyright}` i `{heroText}` nie pochodzą z danych firmy**, tylko ze stałej konfiguracji systemu — nowa firma dostanie tam cudzy tekst. W stopce pisz `© {year} {companyName}`. - `{tagline}` ma wartość zastępczą systemu, gdy firma nie ma własnego sloganu — ustaw slogan firmy (`tenant_edytuj`). - `{if:klucz}` działa dla każdego klucza danych firmy (`{if:nip}`, `{if:krs}`, `{if:street}`…). Dla klucza, którego system nie zna, `{if:…}` **pokazuje** treść. - `{nav:NAZWA}`: nazwa menu może zawierać litery, cyfry i `_` (bez myślnika). Menu puste albo nieistniejące daje pustą listę. - `{if:experienceMessage}`: komunikat o doświadczeniu włącza się w ustawieniach firmy. Jeśli `header.html` go nie obsługuje, system sam doda pasek `.st-experience-bar` nad nagłówkiem. Do 1024 px komunikat pokazuje zawsze system: pasek `.st-experience-mobile` nad nagłówkiem (kolory `topBarBg`/`topBarLink`, tekst zawijany, przewija się ze stroną), a `.st-experience` i `.st-experience-bar` są wtedy ukryte — szablon nie musi (i nie powinien) stylować komunikatu na wąskim ekranie. Wyjątek: firma oznaczona w ustawieniach jako „Firma matka” paska nie dostaje i na wąskim ekranie obowiązuje CSS szablonu. - `{doc:…}` obsługuje kolekcje: pages, services, projects, products, teksty, tags, categories, baza, webdesign (nie: wpisy). ### 5.3. HTML generowany przez komponenty **`{logo}`** — `<a href="{homepageUrl}" class="flex items-center gap-2 no-underline"><img class="st-logo-img" …></a>`; gdy firma nie ma logo: `<a …><span class="st-logo-structum">{shortName}</span></a>`. Ostyluj oba warianty. **`{nav:structured}`** (zalecany) i `{nav:NAZWA}`: ```html <ul class="st-nav-main"> <li><a href="/start" style="color:<headerNavLink>">Start</a></li> <li class="st-has-dropdown"> <a href="/oferta" style="color:…">Oferta <svg…/></a> ← strzałka to SVG w kodzie <ul class="st-dropdown"> <li><a href="/oferta/a">A</a></li> <li class="st-has-submenu"><a…>B</a><ul class="st-submenu">…</ul></li> </ul> </li> </ul> ``` Linki najwyższego poziomu w nagłówku mają kolor inline (`headerNavLink`) — kolor hover wymaga `!important`. Mega menu (włączane na pozycji w panelu) generuje `<div class="st-dropdown st-mega-menu st-mega-cols-N">` z elementami `.st-mega-blocks`, `.st-mega-grid`, `a.st-mega-link`, `.st-mega-text`, `h4.st-mega-heading`, `.st-mega-html`. Mega menu zbudowane z podpozycji (rozdz. 11.3) używa klas `.st-mega-nav`, `.st-mega-groups`, `.st-mega-group`, `.st-mega-group-title`, `a.st-mega-item`, `.st-mega-item-title`, `.st-mega-item-desc`, `.st-mega-foot`. **`{nav}`** (starszy wariant) — `div.nav-item` / `a.nav-link` / `div.dropdown-wrapper`; bez pozycji menu wstawia linki przykładowe. Używaj `{nav:structured}`. Logo firmy ustawia się przez MCP: `media_upload {tenant}` → `tenant_edytuj {id, dane: {logo: <ID pliku>}}` (od MCP 2.7.10; SVG dozwolone). Logo z hasłem albo o ciemnych barwach wymaga jasnego nagłówka — sprawdź je na tle `headerBg`. **`{search}`** — `<button id="search-toggle-btn" style="…color:<headerNavLink>">` z ikoną SVG i `<span class="search-label">Szukaj</span>`. Panel wyników rysuje system. **`{cart}`** — `<a class="template-cart" style="color:…">` z `<svg class="cart-icon">` i `<span class="cart-text">` (licznik). **`{authLinks}`** — `<div data-auth-links style="display:inline-flex;…">`, wypełniany skryptem: gość dostaje jeden link „Zaloguj się” (`<span class="auth-label">`), zalogowany — link do konta i `a[data-action="logout"]`. Linki nie mają koloru inline: nadaj go w CSS. Stopka: `{nav:footer}` i inne menu nazwane dają tę samą listę `ul.st-nav-main` (bez koloru inline). System ma dla `.st-footer .st-nav-main` własne reguły (układ pionowy) — patrz rozdz. 9.2. --- ## 6. Kolory `template.colors` — 15 pól zapisywanych w szablonie: `primary`, `primaryLight`, `accent`, `bg`, `text`, `bodyBg`, `sectionAlt`, `headerBg`, `headerNavLink`, `topBarBg`, `topBarLink`, `footerBg`, `heroBg`, `buttonBg`, `buttonText`. Dziewięciu pozostałych szablon nie ustawia — mają wartości zastępcze, które firma może nadpisać w panelu: | Kolor | Wartość zastępcza | |---|---| | `accentLight`, `headerNavLinkHover` | `accent` | | `buttonHoverBg` | `primaryLight` | | `footerText` | `#94a3b8` | | `footerLink` | `#cbd5e1` | | `heroText` | `#fff` | | `border` | `#e2e8f0` | | `muted` | `#64748b` | | `cardBg` | `#fff` | Priorytet: kolory firmy (panel) → szablon → wartości systemu. Przypisanie szablonu firmie (`ustawDomyslny`, `szablon_strony_przypisz`) **czyści 24 nadpisania kolorów firmy** i jej preferencję układu. Kontrast automatyczny: dla każdego koloru istnieje `{c:nazwaText}` (np. `{c:primaryText}`, `{c:accentText}`, `{c:footerBgText}`) — biały albo ciemny, zależnie od jasności tła. W treści stron i w blokach nie ma kolorów `accentLight`, `headerNavLinkHover`, `footerText`, `footerLink`, `heroText`, `buttonHoverBg` — używaj tam `{c:nazwa||#fallback}`. Kolory stosuj wyłącznie przez `{c:…}`; nie wpisuj wartości hex na sztywno (wyjątek: neutralne biele, czernie i przezroczystości). Stopka zwykle jest ciemna: nagłówkom i linkom w stopce nadaj jawny kolor (nie `{c:primary}` i nie `{c:muted}`), z kontrastem co najmniej 4,5:1. --- ## 7. Układy (`layouts/*.html`) | Plik | Znaczenie | |---|---| | `single-column.html` | Układ domyślny każdej strony | | `bare.html` | Strona bez nagłówka i stopki | | `full-page.html` | Układ do wyboru na stronie (opcjonalny) | Układ wybiera pole `layoutPreference` (`single-column` / `full-page` / `bare` / `two-column-left`) — kolejno: strony, domyślnych ustawień kolekcji, firmy. Gdy wskazanego pliku nie ma w paczce, obowiązuje `single-column`. Placeholdery układu: | Placeholder | Działanie | |---|---| | `{page:content}` | Tytuł `<h1>` + obraz nagłówkowy + `contentHtml` + bloki strony (wymagany) | | `{page:breadcrumbs}` | Okruszki (linki `.st-breadcrumb-link`, `.st-breadcrumb-current`, `.st-breadcrumb-sep`) | | `{page:title}` | Sam tekst tytułu | | `{layout:header}`, `{layout:footer}` | Znaczniki: „ta strona ma nagłówek / stopkę”. Sam nagłówek i stopkę system rysuje poza układem. | | `{pageMaxWidth}`, `{cssClasses}`, `{c:…}` | Szerokość strony, klasy szablonu, kolory | Wzorzec: ```html {layout:header} <main class="moj-main"> <nav class="moj-okruszki" aria-label="Okruszki">{page:breadcrumbs}</nav> {page:content} </main> {layout:footer} ``` Ograniczenia: - HTML układu jest używany **tylko dla stron (`pages`)** i tylko wtedy, gdy każdy blok strony ma szablon w `blocks/`. Strona z blokiem dynamicznym (lista wpisów, produktów, formularz…) albo z blokiem `content` jest rysowana trybem standardowym: ten sam nagłówek i stopka, okruszki i tytuł systemu, bez Twojego `<main>`. **Nie opieraj wyglądu na elementach z pliku układu** — to dodatek, nie fundament. - Strona główna, usługi, wpisy, produkty, sklep, tagi, projekty i referencje nie używają plików układu. - Układ jest wstawiany do kontenera strony o szerokości `pageWidth` — `full-page` nie wyjdzie poza niego (zob. rozdz. 9.3). - W plikach układu nie działają placeholdery firmy ani `{nav}`, `{logo}`, `{search}` — ich miejsce jest w `header.html` / `footer.html`. - `{page:sidebar}` nie jest obsługiwany (zostaje jako tekst) — nie twórz układu dwukolumnowego opartego na nim. - `bare` bez `{layout:header}`/`{layout:footer}` nie ładuje CSS ani JS szablonu. --- ## 8. Bloki treści (`blocks/*.html`) ### 8.1. Zasada Strona ma pole `layout` — listę bloków. Każdy blok ma typ (`blockType`). Jeśli paczka zawiera `blocks/<blockType>.html`, system rysuje blok tym szablonem; jeśli nie — komponentem wbudowanym. Nazwa pliku musi być **dokładnie** równa `blockType` (wielkość liter!). Dawna lista „120 bloków” (`pitchDeck`, `priceTable`, `timeline`…) to wartości pola `variantType` w blokach `contentBlock`, `customBlock`, `dataBlock`, `itemsBlock`, `collectionBlock` — nie mają osobnych plików; wariant odczytasz w szablonie jako `{block:contentBlock:variantType}`. ### 8.2. Bloki, dla których warto dostarczyć szablon (19) | `blockType` | Pola (✱ = wymagane) | Pętla `items` | |---|---|---| | `hero` | `type` (none / highImpact / mediumImpact / lowImpact), `richText`, `subtitle`, `leadText`, `links[]`, `media`, `decorationPreset`, `decorationAnimation` | `links` → `{item:url}` `{item:label}` `{item:appearance}` | | `heroSplit` | `eyebrow`, `heading`✱, `lead`, `primaryCtaLabel`, `primaryCtaUrl`, `secondaryCtaLabel`, `secondaryCtaUrl`, `media`, `imageAlt`, `statValue`, `statSuffix`, `statLabel` | — | | `cta` | `richText`, `subtitle`, `links[]` | `links` | | `mediaBlock` | `media` | — | | `mediaText` | `image`✱, `reverse`, `eyebrow`, `title`, `content` (HTML) | — | | `marquee` | `fullWidth`, `title`, `institutions[]`✱ | `institutions` → `{item:name}` | | `howItWorks` | `title`, `subtitle`, `image`, `items[]` | `items` → `{item:title}` `{item:description}` | | `areasOfExpertise` | `eyebrow`, `heading`, `areas[]`✱ | `areas` → `{item:number}` `{item:title}` `{item:description}` `{item:icon}` `{item:link}` `{item:linkText}` | | `textIconList` | `eyebrow`, `heading`, `text`, `items[]`✱ | `items` → `{item:icon}` `{item:label}` | | `faq` | `introContent`, `faqItems[]`✱ | `faqItems` → `{item:question}` `{item:answer}` | | `team` | `introContent`, `teamMembers[]` | `teamMembers` → `{item:name}` `{item:position}` `{item:bio}` `{item:photo}` | | `cardGrid` | `introContent`, `subtitle`, `columns` (2/3/4), `cards[]`✱ | `cards` → `{item:title}` `{item:subtitle}` `{item:description}` `{item:icon}` `{item:image}` `{item:link}` `{item:linkLabel}` | | `stats` | `introContent`, `stats[]`✱ | `stats` → `{item:prefix}` `{item:value}` `{item:suffix}` `{item:label}` | | `testimonials` | `introContent`, `testimonials[]` | `testimonials` → `{item:quote}` `{item:author}` `{item:position}` `{item:organization}` `{item:photo}` | | `partners` | `introContent`, `partners[]` | `partners` → `{item:name}` `{item:logo}` `{item:website}` | | `contentBlock` | `variantType`, `title`, `subtitle`, `image`, `content` (HTML), `linkUrl`, `linkText` | — | | `customBlock`, `dataBlock` | `variantType`, `title`, `content`, `image`, `linkUrl`, `linkText` | — | | `itemsBlock` | `variantType`, `title`, `content`, `items[]` | `items` → `{item:label}` `{item:value}` `{item:icon}` `{item:image}` `{item:link}` | Ikony: w `areasOfExpertise` i `textIconList` pole `icon` to klasa Phosphor (`ph ph-robot`) → `<i class="{item:icon:attr}"></i>`; w `cardGrid` i `itemsBlock` to tekst lub emoji. Aktualne pola zawsze potwierdzisz przez `describe_collection {collection: "pages"}`. ### 8.3. Bloki, którym NIE dostarcza się szablonu | Blok | Powód | |---|---| | `archive`, `formBlock`, `collectionBlock`, `productBlock`, `bazaBlock`, `tbProductBlock`, `wpisyBlock`, `tbToc`, `bazaToc`, `productToc` | **Bloki dynamiczne** — pobierają dane (wpisy, produkty, formularz). Plik HTML zastąpiłby komponent martwym kodem. | | `content` | Tekst sformatowany (nagłówki, listy, linki). Szablon dostałby sam czysty tekst — zostaw komponent systemu. | | `anchor` | Kotwica; nie wymaga szablonu. | Bloki dynamiczne mają własny znacznik i style inline. Możesz wyrównać ich nagłówki i karty regułami na selektorach systemu (np. `.archive-items`, `.archive-item`, `.archive-link`), nie własnym HTML. ### 8.4. Składnia szablonu bloku **Pola** — `{block:TYP:pole}`, z wartością zastępczą `{block:TYP:pole||tekst}`. `TYP` musi być równy nazwie pliku. Wartości są zabezpieczane przed HTML, z wyjątkiem pola `content`, które jest wstawiane jako HTML. Aliasy: | Zapis | Zwraca | |---|---| | `title`, `content` | pole o tej nazwie; gdy blok ma `richText` lub `introContent` — **czysty tekst** z tego pola | | `subtitle` | pole `subtitle` | | `lead`, `leadText` | `leadText` albo `lead` | | `image`, `src` | adres obrazu z pola `image` lub `media` | | `imageAlt`, `alt` | tekst alternatywny obrazu | | `ctaText`, `buttonText`, `buttonLabel` | etykieta pierwszego linku z `links[]` | | `ctaLink`, `buttonLink`, `link` | adres pierwszego linku | **Pętla** — zawsze pod nazwą `items`, niezależnie od nazwy pola w bloku: ```html {block:faq:items} <details><summary>{item:question}</summary><div>{item:answer}</div></details> {/block:faq:items} ``` W pętli: `{item:pole}`, `{item:pole:attr}` (do atrybutów), `{item:index}` (od 1), `{item:first}`, `{item:last}`. Pole z obrazem zwraca adres URL. **Warunki** — `{if:block:TYP:pole}…{/if:block:TYP:pole}`, `{ifnot:block:TYP:pole}…{/ifnot:block:TYP:pole}`; w pętli `{if:item:pole}…{/if:item:pole}`, `{ifnot:item:pole}…{/ifnot:item:pole}`. Fałsz: brak wartości, pusty tekst, `false`, `0`, `no`, `off`, pusta lista. **Kolory i dane firmy** — `{c:…}`, `{pageMaxWidth}`, `{phone}`, `{email}` itd. działają w blokach na stronach i na stronie głównej. W blokach usług, projektów i dokumentów `webdesign` dane firmy nie są podstawiane. ### 8.5. Pułapki silnika (sprawdzone w praktyce) 1. **Nie zagnieżdżaj `{if}` w `{if}` tego samego poziomu.** Warunki są przetwarzane jednym przebiegiem — wewnętrzny zostanie na stronie jako tekst. Warunek blokowy wokół pętli albo wokół warunków `item` jest w porządku. 2. **Nie używaj `{else}`.** Działa tylko w najprostszym przypadku i psuje sąsiednie warunki. Pisz parę: ```html {if:item:photo}<img src="{item:photo}" alt="">{/if:item:photo}{ifnot:item:photo}<div class="brak-zdjecia"></div>{/ifnot:item:photo} ``` 3. Tekst zastępczy linku bez drugiego warunku: `<a class="wiecej" href="{item:link}">{item:linkText}</a>` + CSS `.wiecej:empty::before{content:'Zobacz więcej'}`. 4. **Nie używaj warunków danych firmy w blokach** (`{if:phone}`) — warunek jest oceniany na danych bloku i zawsze usunie treść. 5. Blok `hero`: dekoracje wybierane w panelu (`decorationPreset`) system dokleja do elementu z atrybutem dokładnie `class="st-hero"`. Dodatkowe klasy nadaj atrybutem `data-…` albo elementem wewnętrznym. Style dekoracji (`.hero-deco*`) dostarcza system. 6. Każdy blok jest opakowany w `<div class="my-8">` (margines 2 rem). Dla sekcji stykających się ze sobą: `.my-8:has(> .moja-sekcja){margin:0}`. ### 8.6. Przykład: `blocks/cardGrid.html` ```html <section class="ib-band ib-cards"> <div class="ib-wrap"> <div class="ib-head">{if:block:cardGrid:title}<h2>{block:cardGrid:title}</h2>{/if:block:cardGrid:title}{if:block:cardGrid:subtitle}<p>{block:cardGrid:subtitle}</p>{/if:block:cardGrid:subtitle}</div> <div class="ib-grid ib-grid-{block:cardGrid:columns||3}"> {block:cardGrid:items}<article class="ib-card"> {if:item:image}<img src="{item:image}" alt="{item:title:attr}" loading="lazy">{/if:item:image} {if:item:icon}<div class="ib-card-emoji" aria-hidden="true">{item:icon}</div>{/if:item:icon} <h3>{item:title}</h3> {if:item:description}<p>{item:description}</p>{/if:item:description} {if:item:link}<a class="ib-more" href="{item:link}">{item:linkLabel}</a>{/if:item:link} </article>{/block:cardGrid:items} </div> </div> </section> ``` --- ## 9. CSS ### 9.1. Podział plików - `header.css` — nagłówek, nawigacja, akcje (wyszukiwarka, logowanie, koszyk), menu mobilne; - `footer.css` — stopka; - `global.css` — typografia, elementy HTML, klasy własne bloków, klasy pomocnicze, animacje. Na początku `global.css` wolno umieścić `@import url(…)` z fontami. Kolory przez `{c:…}`, stałe wymiary i cienie w zmiennych `:root`. ### 9.2. Co ostylować **Nagłówek:** `.st-header`, `.st-topbar`, `.st-topbar-link`, `.st-experience` (+ `.st-experience a:not([class])`), `.st-experience-bar`, `.st-header-main`, `.st-logo`, `.st-logo-img`, `.st-logo-structum`, `.st-header-nav`, `.st-nav-main` i `> li > a`, `.st-has-dropdown`, `.st-dropdown`, `.st-has-submenu`, `.st-submenu`, `.st-mega-menu`, `.st-mega-heading`, `.st-mega-text`, `.st-header-actions`, `#search-toggle-btn`, `.search-label`, `[data-auth-links] a`, `.auth-label`, `a[data-action="logout"]`, `.template-cart`, `.cart-icon`, `.cart-text`, `.st-hamburger`. **Stopka:** własny znacznik oraz `.st-footer .st-nav-main > li > a`. **Treść:** `body`, `h1`–`h6`, `p`, `a`, `a:not([class])`, listy, `blockquote`, `code`, `pre`, `table`/`th`/`td`, `img`, `figure`, `hr`, `mark`, pola formularzy i ich `:focus`, `::selection`; `.html-content`, `.entry-header-image`, `.st-breadcrumb-link`, `.st-breadcrumb-current`, `.st-breadcrumb-sep`, `.st-dokumentacja-list`, `.placeholder-tenant-link`, `.legal-page-content`; klasy własne z `blocks/*.html`. **Reguły systemu, które wygrywają z szablonem** (mają `!important` w arkuszu globalnym): | Reguła systemu | Skutek | Co zrobić | |---|---|---| | `.st-dropdown`, `.st-submenu` — białe tło | Ciemne rozwijane menu wymaga selektora o wyższej specyficzności i `!important` | Przyjmij jasne menu rozwijane albo nadpisz świadomie | | `.st-nav-main .st-dropdown a` — kolor `#334155`, odstępy, rozmiar | Linki w menu rozwijanym mają wygląd systemu | Kolor hover: `.st-nav-main .st-dropdown a:hover{color:…!important}` | | `.st-has-dropdown > a::after { display:none }` | Własna strzałka przez `::after` nie zadziała | Strzałką jest SVG w kodzie menu | | `header { z-index:100; isolation:isolate }` | `z-index` na `.st-header` nic nie zmienia | Nie walcz z kolejnością warstw nagłówka | | `.st-hamburger` — `position:absolute; top:8px; right:8px; 44×44 px`, kolory z `--tenant-primary` | Przycisk ma stałe miejsce w prawym górnym rogu najbliższego przodka z `position` | Daj `.st-header-main{position:relative}` i odsuń akcje: `padding-right:64px` na telefonie | | `@media (min-width:769px)`: `.st-dropdown` wymuszone `display:block; position:absolute` | W zakresie 769–1024 px reguły mobilne szablonu przegrywają, dopóki menu nie jest otwarte | Projektuj menu mobilne pod stan otwarty (`header.nav-open …`) | | `.st-footer .st-nav-main` — układ pionowy, bez wypunktowania | Menu w stopce jest zawsze listą pionową | Stylizuj tylko linki | | `* { margin:0; padding:0 }` | Reset globalny | Nadaj marginesy elementom treści | | `.st-logo-img { max-height:48px }` | Logo nie urośnie ponad 48 px mimo `height` w szablonie | Dodaj `max-height:none` obok własnej wysokości | | Mega menu z kierunkiem „center”: `left:50%; transform:translateX(-50%)` (styl inline) | Pole panelu sprzed przesunięcia wystaje poza okno i daje **poziome przewijanie strony** przy 1025–1260 px | Zakotwicz panel w kontenerze nagłówka: `li:has(> .st-mega-menu){position:static}`, `.st-header-nav{position:static!important}`, a na panelu `left:1.5rem!important; right:1.5rem!important; margin-inline:auto!important; max-width:calc(100% - 3rem)!important; transform:none!important` (wzór: `szablon-structum-siv/paczka/header.css`) | | Otwarte menu mobilne (`header.nav-open .st-header-nav`) nie ma tła | Treść strony prześwituje przez panel menu | `header.nav-open .st-header-nav{background:{c:headerBg}!important}` | | `.st-nav-main .st-dropdown a { color:#334155 !important }` | Kolor nadany stylem inline linkom w `megaMenuHtml` przegrywa | W HTML mega menu dopisz `!important` do koloru albo buduj mega menu z podpozycji (rozdz. 11.3) | Poza menu rozwijanym nie nadużywaj `!important`. ### 9.3. Sekcja na pełną szerokość okna ```css .sekcja{width:100vw;margin-left:calc(50% - 50vw);padding:4.5rem 0} .sekcja > .srodek{max-width:var(--st-page-max-width,1200px);margin:0 auto;padding:0 1.25rem} html{overflow-x:clip} @supports not (overflow-x:clip){html{overflow-x:hidden}} .my-8:has(> .sekcja){margin-top:0;margin-bottom:0} ``` ### 9.4. Menu mobilne Obsługuje je system (próg **1024 px**): klik w `.st-hamburger` dodaje klasę `nav-open` na **zewnętrznym elemencie `<header>` systemu**, pokazuje `<nav>` jako panel na całą szerokość i przełącza `.st-open` na `.st-has-dropdown` / `.st-has-submenu` (akordeon). Przycisk dostaje `.is-open` i `aria-expanded`. ```css @media (max-width:1024px){ .st-hamburger{display:flex!important} /* system pokazuje go sam dopiero od 768 px */ .st-header-nav{display:none} .st-nav-main{flex-direction:column;align-items:stretch} .st-dropdown,.st-submenu{position:static;box-shadow:none;opacity:1;visibility:visible;transform:none;display:none} .st-has-dropdown.st-open > .st-dropdown,.st-has-submenu.st-open > .st-submenu{display:block} header.nav-open .st-nav-main > li > a{padding:1rem .25rem!important} /* NIE: header.st-header.nav-open */ } ``` Zasady: - poza `@media` nie ustawiaj `display:none` na `.st-dropdown` (dropdown desktopowy przestanie działać) ani `overflow` na jego przodkach (zostanie ucięty); - nie pisz własnej obsługi kliknięcia hamburgera; - poniżej 480 px system ukrywa etykiety `.search-label` i `.auth-label`. ### 9.5. Sklep i karta produktu Listę produktów, kategorie i kartę produktu rysuje **system**, taki sam znacznik w każdym sklepie — szablon ich nie dostarcza. Wygląd pochodzi ze zmiennych firmy: `--tenant-primary` buduje strukturę (pas tytułowy sklepu, górna krawędź tabliczki zakupu, nazwa producenta), a `--tenant-accent` / `--tenant-button-bg` są zarezerwowane dla działania (cena, „Do koszyka”, zaznaczona kategoria). Dzięki temu jeden szablon obsługuje wiele sklepów różniących się kolorami. Szablon może nadpisać dowolną regułę tych widoków; zwykle wystarcza krój nagłówków: ```css .gbp-title,.gbp-section > h2,.gbs-hero h1,.gbs-headline h1,.gbs-main-head h2,.gbs-cats h2{font-family:var(--moj-kroj-naglowkow)} ``` | Widok | Klasy | |---|---| | Karta produktu | `.gbp` (zmienne `--gbp-ink`, `--gbp-primary`, `--gbp-accent`, `--gbp-steel`, `--gbp-line`, `--gbp-muted`), `.gbp-crumbs`, `.gbp-head`, `.gbp-maker`, `.gbp-title`, `.gbp-motto`, `.gbp-top`, `.gbp-gallery`, `.gbp-photo`, `.gbp-plate` (tabliczka zakupu), `.gbp-price`, `.gbp-stock`, `.gbp-facts`, `.gbp-buy`, `.gbp-ask`, `.gbp-lead`, `.gbp-tags`, `.gbp-toc`, `.gbp-section` (+ `.gbp-section-spec`, `.gbp-s-<id>`), `.gbp-section-body`, `.gbp-files`, `.gbp-fold`, `.gbp-related` | | Lista sklepu | `.gbs` (zmienne `--gbs-*`), `.gbs-hero`, `.gbs-btn`, `.gbs-headline`, `.gbs-layout`, `.gbs-cats`, `.gbs-main`, `.gbs-grid`, `.gbs-card` (`-photo`, `-maker`, `-title`, `-meta`, `-price`), `.gbs-list`, `.gbs-row`, `.gbs-more`, `.gbs-empty` | Kolejność sekcji karty produktu wybiera firma (Ustawienia firmy → Strona sklepu → „Układ karty produktu”): sprzedażowy albo techniczny. Sekcje bez treści nie są rysowane. ### 9.6. Dostępność i ruch Animacje SVG `animateMotion` / `animate` (SMIL) nie reagują na `prefers-reduced-motion` w CSS — wyłącz je w `global.js` (wzór: `szablon-gobiz-2027`). Kontrast tekstu min. 4,5:1; widoczny `:focus-visible`; `@media (prefers-reduced-motion: reduce)` wyłącza animacje. Treść ukrywana do animacji wejścia musi być widoczna bez JavaScriptu — ukrywaj ją dopiero pod klasą dodawaną przez `global.js`: ```css .js .reveal{opacity:0;transform:translateY(18px);transition:opacity .6s,transform .6s} .js .reveal.in{opacity:1;transform:none} ``` --- ## 10. `global.js` Skrypt jest wstrzykiwany **po załadowaniu strony** — uruchamiaj kod od razu; nasłuch `DOMContentLoaded` nigdy się nie wykona. ```js (function () { 'use strict'; document.documentElement.classList.add('js'); // logika własna szablonu: animacje wejścia, liczniki, płynne przewijanie… })(); ``` Nie implementuj: menu mobilnego, akordeonu menu, wyszukiwarki, koszyka, logowania, banera cookies, przycisku „do góry”, kalkulatorów — robi to system. `bare` bez nagłówka i stopki nie ładuje `global.js`. --- ## 11. Nawigacja ### 11.1. `navigation.json` Jedno menu: ```json { "menu": "main", "items": [ { "label": "Start", "page": "start" }, { "label": "Sklep", "url": "/shop" } ] } ``` Wiele menu: ```json { "menus": [ { "menu": "main", "items": [ { "label": "Start", "page": "start" }, { "label": "Oferta", "page": "oferta", "children": [ { "label": "Wdrożenia", "page": "wdrozenia" }, { "label": "Szkolenia", "url": "/uslugi/szkolenia" } ] } ] }, { "menu": "footer", "items": [ { "label": "Kontakt", "page": "kontakt" } ] } ] } ``` | Pole pozycji | Opis | |---|---| | `label` | Tekst w menu | | `page` | Slug strony firmy → pozycja typu „strona” (adres podąża za stroną). Gdy strony nie ma, powstaje adres `/<slug>` i ostrzeżenie. | | `url` | Własny adres (ścieżka lub pełny URL); `{templateSlug}` zamienia się na slug szablonu | | `children` | Podmenu; szablon rysuje trzy poziomy: menu, menu rozwijane, podmenu | | `order`, `enabled` | Kolejność i widoczność (opcjonalne) | **Import menu usuwa dotychczasowe pozycje menu o tej samej nazwie w firmie docelowej.** Menu o innych nazwach zostają. ### 11.2. Nazwy menu `main` — menu nagłówka (`{nav:structured}`), `footer` — menu stopki (`{nav:footer}`). Pozostałe nazwy są dowolne (litery, cyfry, `_`) i pojawiają się tam, gdzie szablon ma `{nav:NAZWA}` — np. `{nav:topbar}`, `{nav:footer_info}`. W dokumentacji swojego szablonu wypisz menu, których używa. ### 11.3. Pozycje przez MCP i mega menu `Create_navigation {data: {tenant, menu, label, type, page | product | url, order, parent, enabled}}` — `type`: `page` / `product` / `custom`. Pola mega menu: `megaMenuEnabled`, `dropdownDirection`, `dropdownWidth`, `dropdownColumns` (1–4), `collectionSource` (pages / products / services / categories — lista dynamiczna), `collectionLimit`, `megaMenuHtml`, `megaMenuBlocks[]`. `type` ma też trzy wartości **bez linku**: `heading` (nagłówek grupy), `separator` (linia), `text` (zdanie). Pole `description` to druga, mniejsza linia pod nazwą pozycji. **Mega menu z podpozycji (zalecane zamiast `megaMenuHtml`).** Pozycja z `megaMenuEnabled`, bez `megaMenuHtml`, bloków i listy dynamicznej, której co najmniej jedna podpozycja jest grupą, buduje mega menu sama: | Podpozycja pozycji mega | Co powstaje | |---|---| | `heading` albo link z własnymi podpozycjami | grupa: nagłówek (`div` albo `a.st-mega-group-title`) i pod nim jej podpozycje | | link w grupie | `a.st-mega-item` z `.st-mega-item-title` i — gdy jest `description` — `.st-mega-item-desc`; grupa bez opisów dostaje `.st-mega-group-compact` | | `separator` / `text` w grupie | `hr.st-mega-sep` / `span.st-mega-note` | | `text` albo link bez podpozycji, na pierwszym poziomie | dolny pasek `.st-mega-foot` (`.st-mega-foot-text`, `a.st-mega-foot-link`) | Całość siedzi w `<div class="st-mega-html st-mega-nav">` › `.st-mega-groups` › `.st-mega-group`. `dropdownColumns` = 1 układa tyle kolumn, ile grup się zmieści (min. 200 px); większa liczba daje dokładnie tyle kolumn i grupy mogą stać jedna pod drugą (`.st-mega-groups-flow`, zmienna `--st-mega-cols`). Nagłówek bez linku ma kolor `--st-mega-accent` (kolor `accent` firmy). Do 1024 px wszystko jest w jednej kolumnie. Bez grup zostaje dotychczasowa siatka linków `a.st-mega-link`. W zwykłym menu rozwijanym pozycje bez linku dają `li.st-nav-heading > span`, `li.st-nav-text > span` i `li.st-nav-separator`; podpozycje nagłówka wyświetlają się pod nim na tym samym poziomie. W `navigation.json` te same możliwości dają pola pozycji: `type` (`heading` / `separator` / `text`), `description`, `megaMenu: true`, `megaColumns`, `megaWidth`, `megaDirection`. --- ## 12. Treść serwisu ### 12.1. Strony (`pages`) | Pole | Opis | |---|---| | `title`✱, `slug`✱, `tenant`✱ | Tytuł, adres, firma | | `contentHtml` | Treść HTML (działają placeholdery firmy, klasy z `global.css`) | | `layout` | Lista bloków (rozdz. 8) | | `layoutOnTop` | Bloki przed `contentHtml` | | `hideTitle`, `hideBreadcrumbs` | Ukrycie tytułu `<h1>` / okruszków | | `layoutPreference`, `pageWidth`, `template` | Układ, szerokość i szablon tylko dla tej strony | | `hideSearch`, `hideLogin`, `hideCart` | Ukrycie akcji nagłówka na tej stronie | | `wpisImage`, `headerImageDecoration` | Obraz nagłówkowy i jego dekoracja | | `form`, `formOnTop` | Formularz na stronie | | `tags` | Tagi | | `meta.title`, `meta.description`, `meta.image` | SEO | | `published` | `Create_*` tworzy szkic; publikuj przez `published: true` albo `publish_pages` | | `displayMode` | `superBare` = sam `contentHtml` pod `/raw/<slug>` | Przykład strony z blokami: ```json { "data": { "tenant": 64, "title": "Oferta", "slug": "oferta", "published": true, "hideTitle": true, "meta": { "title": "Oferta — Firma", "description": "…" }, "layout": [ { "blockType": "heroSplit", "heading": "Nagłówek", "lead": "Wprowadzenie", "primaryCtaLabel": "Kontakt", "primaryCtaUrl": "/kontakt" }, { "blockType": "cardGrid", "columns": "3", "cards": [ { "title": "A", "description": "…", "link": "/a", "linkLabel": "Więcej" } ] }, { "blockType": "faq", "faqItems": [ { "question": "Pytanie?", "answer": "Odpowiedź." } ] }, { "blockType": "wpisyBlock", "variantType": "grid", "title": "Aktualności", "limit": 3, "columns": 3 } ] } } ``` Blok `wpisyBlock` ma też tryb `"variantType": "ticker"` — **pasek aktualności**: jedna linia wolno przesuwających się tytułów z terminem zakończenia, pulsujący znacznik, licznik wpisów i opcjonalny przycisk (`tickerLinkLabel`, `tickerLinkUrl`). Bierze wpisy z tych samych filtrów co lista (`wpisType`, `statusFilter`, `sortBy`…), bez tych, których termin minął. Pole `sourceTenant` (ID firmy) każe blokowi — w każdym trybie — pokazać opublikowane wpisy innej firmy niż ta, do której należy strona. Pozycje paska z `sourceTenant` prowadzą na domenę firmy źródłowej, jeśli ją ma (linki zwrotne do serwisu właściciela treści); bez domeny zostają adresy względne. Pasek jest na całą szerokość okna; wygląd: klasy `.st-ticker`, `.st-ticker-label`, `.st-ticker-dot`, `.st-ticker-count`, `a.st-ticker-item`, `.st-ticker-date`, `a.st-ticker-cta` i zmienne `--st-ticker-ink`, `--st-ticker-accent`, `--st-ticker-live` (domyślnie kolory `primary` i `accent` firmy). Przesuw staje po najechaniu i przy fokusie, a przy wyłączonych animacjach w systemie zostaje zwykła lista. Pola `richText` / `introContent` (bloki `hero`, `cta`, `content`, nagłówki `faq`, `cardGrid`, `stats`…) przyjmują strukturę edytora: ```json { "root": { "type": "root", "direction": "ltr", "format": "", "indent": 0, "version": 1, "children": [ { "type": "heading", "tag": "h2", "direction": "ltr", "format": "", "indent": 0, "version": 1, "children": [ { "type": "text", "text": "Nagłówek sekcji", "version": 1, "detail": 0, "format": 0, "mode": "normal", "style": "" } ] } ] } } ``` Linki w `links[]`: `{ "link": { "type": "custom", "url": "/kontakt", "label": "Kontakt", "appearance": "default" } }` (`appearance`: `default` / `outline`). Obrazy: najpierw `media_upload {base64, filename, mimeType, alt, tenant}` (także SVG), potem ID pliku w polu bloku (`image`, `media`). ### 12.2. Strona startowa Adres `/` firmy pokazuje stronę wskazaną w polu „Obiekt startowy” (ustawiasz: `stronaStartowa`); bez niej — stronę o slugu `home`; bez niej — planszę z nazwą firmy. Działa tylko dla stron (`pages`). Na stronie startowej nie jest używany HTML układu; ustaw jej `hideTitle` i `hideBreadcrumbs`, jeśli zaczyna się od hero. Administrator może globalnie (Ustawienia systemu → Strona startowa) albo dla firmy dodać HTML przed i po treści strony startowej — jeśli na dole strony widzisz treść spoza szablonu, to jej źródło. ### 12.3. Adresy publiczne | Treść | Adres | |---|---| | Strona | `/<slug>` | | Wpis (aktualność, poradnik, nabór…) | `/<slug>` — listę buduje blok `wpisyBlock` | | Usługa | `/uslugi/<slug>` — listę buduje blok `archive` lub `cardGrid` | | Realizacje, referencje | `/projekty`, `/projekty/<slug>`, `/referencje`, `/referencje/<slug>` | | Tag | `/tag/<slug>` | | Sklep | `/shop`, `/shop/products/<slug>`, `/shop/checkout`, `/shop/account` (segmenty konfigurowalne w firmie) | | Strony prawne | `/polityka-prywatnosci`, `/regulamin`, `/polityka-cookies`, `/rodo` | | Logowanie i konto | `/login`, `/register`, `/forgot-password` | `/<slug>` szuka kolejno: strony, usługi, produkty, teksty, baza, wpisy, webdesign, strony prawne — **nie powtarzaj sluga między kolekcjami**. ### 12.4. Inne kolekcje - **Wpisy** (`wpisy`): `title`, `slug`, `type` (typ wpisu: wiedza, poradnik, nabór, produkt…), `intro`, `contentHtml`, `tags`, `wpisImage`, `published`. Wygląd wpisu pochodzi z typu wpisu, nie z szablonu serwisu. - **Usługi** (`services`): `title`, `slug`, `shortDescription`, `icon`, `order`, `description`, `layout`, `published`. - **Realizacje i referencje** (`projects`, `testimonials`), **tagi** (`tags`), **teksty** (`teksty`), **baza wiedzy** (`baza`). - **Sklep**: `products`, kategorie (`kategorie_drzewo`, `kategoria_utworz`, `produkty_przypisz_kategorie`). - **Formularze** (`forms`): `formularz_utworz {tenant, title, fields: [{blockType, name, label, width, required, options}], submitButtonLabel, confirmationMessage, emails: [{subject, message, replyTo: "{{email}}"}], strona: "kontakt"}` tworzy formularz i podpina go do strony (pole `form`); `formularz_edytuj {id, tenant, …}` zmienia wskazane pola. Typy pól: `text`, `textarea`, `email`, `number`, `select`, `checkbox`, `message`. Szablon stylizuje formularz selektorem `form:has([data-field])`. --- ## 13. Instalacja szablonu ### 13.1. Przez MCP Uprawnienie roli klucza: `mcp.szablony_stron`; zakresy klucza: `templates.read`, `templates.write`. Uwaga do `Find_*`: wynik z parametrem `select` **nie zawiera `id`** — gdy potrzebujesz ID (np. strony do pozycji menu), nie zawężaj pól. **`szablon_strony_waliduj {zipBase64 | url, tenant?}`** — nic nie zapisuje. Zwraca `valid`, `errors[]` (blokują import), `warnings[]` (odstępstwa od tej specyfikacji), `summary` (pliki, bloki, rozmiary pól) i `plan` (co powstanie, co zostanie nadpisane, `conflicts[]`). **`szablon_strony_importuj`** | Argument | Domyślnie | Działanie | |---|---|---| | `zipBase64` \| `url` \| `paczka` | — | Paczka: base64, publiczny adres albo suma SHA-256 paczki z archiwum (rozdz. 13.4) | | `tenant` | — | ID firmy docelowej; wymagane dla opcji poniżej | | `ustawDomyslny` | `false` | Szablon staje się domyślnym szablonem firmy i jej kolekcji; czyści nadpisania kolorów firmy | | `importujStrony` | `false` | `demo-page.html` i `pages/*.html` → strony firmy; **strona o tym samym slugu zostanie nadpisana** | | `publikujStrony` | `false` | Publikuje importowane strony (inaczej nowe są szkicami, istniejące zachowują status) | | `importujNawigacje` | `false` | `navigation.json` → menu firmy; **zastępuje menu o tych samych nazwach** | | `stronaStartowa` | — | Slug strony (z paczki lub istniejącej) jako strona startowa firmy | | `dryRun` | `false` | Tylko plan | | `confirm`, `reason` | — | Wymagane na produkcji | Bez opcji firmy narzędzie instaluje **sam szablon** — niczego w firmach nie zmienia. Ponowny import tego samego `slug` aktualizuje szablon u wszystkich firm, które go używają. **`szablon_strony_przypisz {tenant, szablon?, stronaStartowa?, wyczyscKolory?, kolekcje?}`** — przypisuje firmie istniejący szablon i/lub stronę startową, bez paczki. Jeden szablon dla wielu firm różniących się kolorami: przypisuj z `wyczyscKolory: false`, inaczej firma straci kolory ustawione w panelu. **`szablon_strony_get {szablon, pliki?, bloki?}`** — ustawienia szablonu, lista bloków, firmy, które go używają; z `pliki: true` także źródła (CSS w bazie to `global.css` sklejony z `header.css` / `footer.css`). **Produkcja:** `szablon_strony_importuj` i `szablon_strony_przypisz` nie zapisują od razu — tworzą zmianę do zatwierdzenia (`pendingApproval: true`, `zmianaId`), którą administrator akceptuje w panelu. Szablon buduj i sprawdzaj na środowisku dev. ### 13.2. Archiwum paczek i przenoszenie między środowiskami Każda zainstalowana paczka zostaje w archiwum środowiska pod swoją sumą SHA-256, z historią: kto, kiedy, dla której firmy. Dzięki temu na produkcję trafia **dokładnie ten plik**, który sprawdzono na dev, a do wcześniejszej wersji szablonu można wrócić. | Narzędzie | Zakres klucza | Działanie | |---|---|---| | `szablon_strony_paczki_lista {szablon?}` | `templates.read` | Paczki w archiwum z historią | | `szablon_strony_paczka_link {paczka}` | `templates.transfer` | Podpisany link do paczki, ważny 60 min | | `szablon_strony_paczka_pobierz {sourceUrl}` | `templates.transfer` | Pobiera paczkę z archiwum innego środowiska do archiwum lokalnego — **nie instaluje** | | `szablon_strony_importuj {paczka: "<sha256>", …}` | `templates.write` | Instaluje paczkę z archiwum | Przeniesienie szablonu z dev na produkcję: 1. dev: `szablon_strony_paczki_lista {szablon: "moj-szablon"}` → `sha256` sprawdzonej paczki; 2. dev: `szablon_strony_paczka_link {paczka: "<sha256>"}` → `sourceUrl`; 3. produkcja: `szablon_strony_paczka_pobierz {sourceUrl}` — system porówna sumę kontrolną i zwaliduje paczkę; 4. produkcja: `szablon_strony_importuj {paczka: "<sha256>", tenant, ustawDomyslny, importujNawigacje, …, confirm: true, reason}` — zmiana czeka na zatwierdzenie przez administratora. Produkcja przyjmuje paczki tylko z dev. Treści serwisu (strony z blokami, wpisy, media) paczka szablonu nie przenosi — do tego służą paczki treści (`content_transfer_*`). W panelu to samo robi sekcja „Archiwum paczek” na `/admin/import-template`: „Link do przeniesienia” na źródle, pole „Pobierz paczkę z innego środowiska” i przycisk „Zainstaluj” na celu. ### 13.3. Przez panel `/admin/import-template` — przeciągnij ZIP albo zainstaluj paczkę z archiwum. Wymaga uprawnienia „Szablony stron — tworzenie”. Panel stosuje sekcję `tenantAssignment` z paczki; treść bez wskazanej firmy trafia do firmy `designer`. ### 13.4. Po instalacji Zmiany są widoczne od razu (system odświeża pamięć podręczną). Sprawdź w przeglądarce: stronę startową, stronę z blokami, stronę z samym `contentHtml`, wpis, usługę, stronę tagu, sklep (jeśli firma go ma), logowanie — na szerokościach 1440, 1024, 768 i 390 px, z otwartym menu mobilnym i rozwiniętym menu rozwijanym. --- ## 14. Lista kontrolna **Paczka** - [ ] `template.json` w korzeniu ZIP; `name`, `slug`; `layout.type = "custom"` z własnym, unikalnym `slug` - [ ] `layouts/bare.html`, `layouts/single-column.html` z `{page:content}` - [ ] `availableBlocks` puste; 15 kolorów w `colors` - [ ] brak `<style>` w plikach CSS; brak `DOMContentLoaded` w `global.js` - [ ] `szablon_strony_waliduj` bez błędów; każde ostrzeżenie przeczytane **Nagłówek i stopka** - [ ] `header.html` zaczyna się od `<div class="st-header">`, nie od `<header>` - [ ] `{logo}`, `<nav class="st-header-nav">{nav:structured}</nav>`, `.st-hamburger`, `{search}{authLinks}{cart}` - [ ] ostylowane oba warianty logo (`.st-logo-img`, `.st-logo-structum`) - [ ] stopka: `© {year} {companyName}` zamiast `{copyright}`; linki do stron prawnych; puste dane firmy ukryte przez `{if:…}` - [ ] selektory menu mobilnego w postaci `header.nav-open …` **Bloki** - [ ] nazwy plików = `blockType`; brak plików bloków dynamicznych oraz `content` - [ ] brak `{else}` i zagnieżdżonych `{if}`; pętle przez `{block:TYP:items}` - [ ] blok `hero` z elementem `class="st-hero"` **Wygląd** - [ ] kolory wyłącznie przez `{c:…}`; kontrast ≥ 4,5:1, także w stopce - [ ] strona bez poziomego przewijania przy 390 px; treść widoczna bez JavaScriptu - [ ] `prefers-reduced-motion` wyłącza animacje **Serwis** - [ ] slogan i dane firmy uzupełnione (`tenant_edytuj`) - [ ] strona startowa ustawiona, z `hideTitle`, jeśli zaczyna się od hero - [ ] menu `main` i `footer` (oraz inne używane przez szablon) wypełnione - [ ] każda strona ma `meta.title` i `meta.description`; treść opublikowana - [ ] slugi nie powtarzają się między stronami, wpisami i usługami --- ## 15. Znane ograniczenia - HTML układu (`layouts/*.html`) działa tylko dla stron bez bloków dynamicznych i bez bloku `content` (rozdz. 7). - `{page:sidebar}` i menu boczne (`.st-nav-vertical`) nie są obsługiwane. - `{copyright}` i `{heroText}` nie pochodzą z danych firmy. - `availableBlocks` rozpoznaje tylko kilka kluczy i potrafi ukryć bloki `archive` i `formBlock` — zostaw puste. - Szablon nie ustawia 9 kolorów dodatkowych (rozdz. 6) — firma ustawia je w panelu. - Wygląd wpisu pochodzi z typu wpisu; bloki dynamiczne mają własne style inline. - Formularze tworzy się narzędziem `formularz_utworz` (rozdz. 12.4), nie generycznym `Create_forms`; powiadomienia e-mail mogą iść tylko na adresy w domenach firmy. - Nagłówek nie może być przyklejony (`position: sticky`) — jest w opakowaniu systemu o własnej wysokości. - `assets/*` z paczki nie są importowane. --- ## Załącznik A. Placeholdery szablonów wyświetlania dokumentów (DisplayTemplates) > Treść przeniesiona z wersji 3.16. Szablony wyświetlania działają dla stron (`pages`) oraz w `{doc:kolekcja:id:template=slug}`. Gdy używasz `{doc:pages:171:template=karta}` lub DisplayTemplate w kolekcji DisplayTemplates, szablon HTML ma dostęp do następujących placeholderów dokumentu: #### Podstawowe (17) | Znacznik | Opis | |----------|------| | `{title}` | Tytuł dokumentu | | `{title:linked}` | Tytuł jako link do strony | | `{icon}` | Ikona (emoji) | | `{intro}` | Pole intro | | `{contentHtml}` | Pełna treść HTML | | `{description}` | Opis (krótki) | | `{breadcrumbs}` | Breadcrumbs HTML | | `{tags}` | Tagi jako linki | | `{metaTitle}` | Meta tytuł | | `{metaDescription}` | Meta opis | | `{updatedAt}` | Data aktualizacji | | `{createdAt}` | Data utworzenia | | `{readMore}` | Link "Czytaj więcej" | | `{readMore:label=Szczegóły}` | Customowy tekst linku | | `{image}` | Główny obraz (`<img>`) | | `{price}` | Cena netto | | `{layout}` | Bloki layout builder | #### Dane handlowe / VAT (5) | Znacznik | Opis | |----------|------| | `{priceGross}` | Cena brutto (z VAT) | | `{vatRate}` | Stawka VAT (np. 0.23) | | `{vatRatePercent}` | Stawka VAT % (np. 23) | | `{vatAmount}` | Kwota VAT | | `{inventory}` | Stan magazynowy | #### Pola produktu (22) | Znacznik | Opis | |----------|------| | `{motto}` | Motto produktu | | `{manufacturer}` | Producent | | `{symbol}` | Symbol handlowy | | `{unit}` | Jednostka miary | | `{packaging}` | Opakowanie | | `{minOrder}` | Minimalne zamówienie | | `{wholesaleThreshold}` | Próg hurtowy | | `{orderMultiple}` | Krotność zamówienia | | `{shortDescription}` | Krótki opis | | `{specialization}` | Specjalizacja | | `{applications}` | Zastosowania | | `{solvedProblems}` | Rozwiązywane problemy | | `{features}` | Cechy | | `{installationInstructions}` | Instrukcje instalacji | | `{technicalSpecs}` | Specyfikacja techniczna | | `{certificates}` | Certyfikaty | | `{usageNorms}` | Normy użytkowania | | `{safetyInfo}` | Informacje BHP | | `{warrantyInfo}` | Gwarancja | | `{storageInfo}` | Przechowywanie | | `{wholesaleDiscount}` | Rabat hurtowy | | `{notes}` | Uwagi | #### Kompozytowe | Znacznik | Opis | |----------|------| | `{commercialRow}` | Wiersz danych handlowych (cena + VAT + jednostka) | | `{extraHtml}` | Dodatkowy HTML z pól produktu | ## Załącznik B. Placeholdery typów wpisów > Wygląd wpisu określa pole „szablon HTML” **typu wpisu** (`wpis-types`), nie DisplayTemplate. Poza poniższymi dostępne są: `{status}`, `{wpisImage}`, `{wpisIllustration}`, `{productGroup}`. Szablon typu wpisu ma dostęp do dodatkowych placeholderów (oprócz podstawowych z Załącznika A): #### Pola naboru / ogłoszenia (5) | Znacznik | Opis | |----------|------| | `{dataRozpoczecia}` | Data rozpoczęcia naboru (format: DD miesiąc RRRR) | | `{dataZakonczenia}` | Data zakończenia naboru | | `{instytucjaNazwa}` | Nazwa instytucji ogłaszającej nabór | | `{kwota}` | Kwota dofinansowania | | `{waluta}` | Waluta (PLN / EUR / USD) | #### Link zewnętrzny (2) | Znacznik | Opis | |----------|------| | `{linkZewnetrzny}` | URL linku zewnętrznego | | `{linkZewnetrznyLabel}` | Etykieta linku | #### Kontakt (3) | Znacznik | Opis | |----------|------| | `{kontaktOsoba}` | Osoba kontaktowa | | `{kontaktEmail}` | Email kontaktowy | | `{kontaktTelefon}` | Telefon kontaktowy | #### Typ wpisu (3) | Znacznik | Opis | |----------|------| | `{typeIcon}` | Ikona rodzaju wpisu (np. 📢) | | `{typeName}` | Nazwa rodzaju wpisu (np. "Nabór wniosku") | | `{c:typeAccent}` | Kolor akcentu rodzaju wpisu (kod hex) | #### Pola produktowe — dla wpisów typu "Produkt" (17) Te same placeholdery co w Załączniku A (Pola produktu): `{motto}`, `{manufacturer}`, `{symbol}`, `{unit}`, `{packaging}`, `{shortDescription}`, `{specialization}`, `{applications}`, `{solvedProblems}`, `{features}`, `{installationInstructions}`, `{technicalSpecs}`, `{certificates}`, `{usageNorms}`, `{safetyInfo}`, `{warrantyInfo}`, `{storageInfo}` — oraz `{commercialRow}`. ---