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}`.
---