[Intum Pomoc](https://intum.pl/pomoc.md) / [API](https://intum.pl/pomoc/cms/api.md) # [Witryny, strony i szablony](https://intum.pl/pomoc/cms/api/witryny-i-strony.md) Dokumentacja API do tworzenia stron CMS przez HTTP. **Autoryzacja:** Wszystkie requesty wymagają `Authorization: Bearer TOKEN` **Ważne:** Zamiast `*_id` można używać `*_code` (np. `site_code` zamiast `site_id`) **Zobacz też:** - [Wytyczne tworzenia stron (responsywność, menu mobilne)](https://app.intum.pl/noe/prompt/cms_site_tips.md) - [Wielojęzyczność CMS — strategie, locale chain, per-domain locale](https://intum.intum.pl/kb/intum-kb/cms/api/wielojezycznosc) - [Paragrafy — rodzaje, szablony prezentacji, zdjęcia, boxy](https://intum.intum.pl/kb/intum-kb/cms/api/paragrafy) --- ## API Endpoints ### Layouts (Szablony) | Metoda | Ścieżka | Opis | |--------|---------|------| | GET | `/cms/layouts.json` | Lista szablonów | | GET | `/cms/layouts/:code.json` | Szczegóły (po code lub id) | | POST | `/cms/layouts.json` | Utworzenie | | PATCH | `/cms/layouts/:code.json` | Aktualizacja | | PATCH | `/cms/layouts/:code/set_field.json` | Zapis jednego klucza `fields` szablonu (parametry jak w `set_field` strony, tylko wartości tekstowe) — wartość wspólna dla wszystkich stron z tym szablonem, w treści `{{ layout.klucz }}` | | DELETE | `/cms/layouts/:code.json` | Usunięcie | ### Sites (Strony WWW) | Metoda | Ścieżka | Opis | |--------|---------|------| | GET | `/cms/sites.json` | Lista site'ów | | GET | `/cms/sites/:code.json` | Szczegóły | | POST | `/cms/sites.json` | Utworzenie | | PATCH | `/cms/sites/:code.json` | Aktualizacja | ### Pages (Strony) | Metoda | Ścieżka | Opis | |--------|---------|------| | GET | `/cms/pages.json` | Lista stron | | GET | `/cms/pages/:code.json` | Szczegóły | | POST | `/cms/pages.json` | Utworzenie | | PATCH | `/cms/pages/:code.json` | Aktualizacja | | GET | `/cms/pages/:code/env.json` | Dane strony (env) | | PATCH | `/cms/pages/:code/set_field.json` | Zapis jednego klucza `fields` (`key`, `value`, opcjonalnie `locale`; albo `values: { "": domyślna, "en": ... }` - kilka wersji językowych naraz; pusta wartość usuwa klucz). **Tylko wartości tekstowe** - `value` zapisuje się jako string, więc tablicy/obiektu (menu, cennik, FAQ) tak nie zmienisz, patrz "Edycja tablic w fields" | ### Paragraphs (Paragrafy) | Metoda | Ścieżka | Opis | |--------|---------|------| | GET | `/cms/paragraphs.json` | Lista paragrafów | | GET | `/cms/paragraphs/:code.json` | Szczegóły | | POST | `/cms/paragraphs.json` | Utworzenie | | PATCH | `/cms/paragraphs/:code.json` | Aktualizacja | | PATCH | `/cms/paragraphs/reorder.json` | Nowa kolejność paragrafów w boxie — `{"ids": [12, 7, 30]}`, zapisuje `priority` 1..N | ### Assets (Pliki) | Metoda | Ścieżka | Opis | |--------|---------|------| | GET | `/cms/assets.json` | Lista assetów | | GET | `/cms/assets/:id.json` | Szczegóły | | POST | `/cms/assets.json` | Utworzenie (obsługuje ZIP) | | PATCH | `/cms/assets/:id.json` | Aktualizacja | | DELETE | `/cms/assets/:id.json` | Usunięcie | Adres pliku jest stały: `https:////cms/assets/` - podmiana pliku pod tą samą nazwą nie zmienia URL-a (zmienia go zmiana `name` albo folderu, bo nazwa folderu wchodzi do `name`). Pole `fields.cors` włącza pobieranie pliku z innych domen (nagłówek `Access-Control-Allow-Origin`, potrzebny np. dla `.wasm` ładowanego przez aplikację); ustawić je może wyłącznie administrator systemu - innym użytkownikom API wycina ten klucz z `fields`. ### Articles (Artykuły) | Metoda | Ścieżka | Opis | |--------|---------|------| | GET | `/cms/articles.json` | Lista artykułów | | GET | `/cms/articles/:id.json` | Szczegóły | | POST | `/cms/articles.json` | Utworzenie | | PATCH | `/cms/articles/:id.json` | Aktualizacja | | DELETE | `/cms/articles/:id.json` | Usunięcie | ### Categories (Kategorie artykułów) | Metoda | Ścieżka | Opis | |--------|---------|------| | GET | `/cms/categories.json` | Lista kategorii (filtry: `site_id`, `page_id`, `query`) | | GET | `/cms/categories/:id.json` | Szczegóły | | POST | `/cms/categories.json` | Utworzenie | | PATCH | `/cms/categories/:id.json` | Aktualizacja | | DELETE | `/cms/categories/:id.json` | Usunięcie (422, gdy kategoria jest główną jakiegoś artykułu) | ### Authors (Autorzy artykułów) | Metoda | Ścieżka | Opis | |--------|---------|------| | GET | `/cms/authors.json` | Lista autorów (filtr `query` po nazwie i opisie; `user_id`) | | GET | `/cms/authors/:id.json` | Szczegóły | | POST | `/cms/authors.json` | Utworzenie (zwykle niepotrzebne - nowa nazwa w `author` artykułu zakłada autora sama) | | PATCH | `/cms/authors/:id.json` | Aktualizacja (opis, zdjęcie, strona, podpięcie pod użytkownika) | | DELETE | `/cms/authors/:id.json` | Usunięcie - artykuły zostają, tracą tylko powiązanie (`author_id`), nazwa w `author` zostaje | ### Preview (Podgląd) | Metoda | Ścieżka | Opis | |--------|---------|------| | GET | `/w/:site_code` | Podgląd strony głównej | | GET | `/w/:site_code/:path` | Podgląd strony | --- ## Pola modeli ### Layout | Pole | Typ | Wymagane | Opis | |------|-----|----------|------| | `code` | string | tak | Unikalny kod (zalecany format: `{site_code}-layout`) | | `name` | string | tak | Nazwa | | `kind` | string | tak | `page` | | `content` | string | tak | Szablon HTML z `{{ content }}` | | `site_id` | integer | tak | ID site'a (zawsze podawaj przy tworzeniu layoutu) | | `example_content` | string | nie | Przykładowa treść do podglądu layoutu | ### Site | Pole | Typ | Wymagane | Opis | |------|-----|----------|------| | `code` | string | tak | Unikalny kod | | `name` | string | tak | Nazwa | | `kind` | string | tak | `www` lub `kb` | | `layout_code` | string | nie | Code layoutu | | `locale` | string | nie | Domyślny locale dla wszystkich stron site'a (np. `pl`, `en`, `de`, `fr`, `es`, `cs`, `sk`, `uk`). Ostatni fallback w chain — używany gdy strona nie ma własnego `page.locale` ani `?lang=` ani locale domeny. Steruje którym wariantem językowym renderują się pola z locale-keyed `fields` (Page, Paragraph, Layout) | | `multilang` | boolean | nie | Włącza tryb SEO multilang — dodaje zmienne Liquid `{{ html_lang }}`, `{{ canonical_url }}`, `{{ seo_alternates }}`, `{{ seo_head }}` dostępne w layoucie, oraz 301 redirect path↔locale (patrz [CMS Wielojęzyczność](https://intum.intum.pl/kb/intum-kb/cms/api/wielojezycznosc)) | ### Page | Pole | Typ | Wymagane | Opis | |------|-----|----------|------| | `code` | string | nie | Unikalny kod (zalecany format: `{site_code}-{path}`) | | `name` | string | tak | Nazwa | | `kind` | string | tak | `text` | | `path` | string | tak | URL path (np. "" dla głównej, "about") | | `site_code` | string | tak | Code site'a | | `layout_code` | string | nie | Code layoutu | | `no_layout` | boolean | nie | Strona bez szablonu — renderuje samą swoją treść, bez własnego layoutu i bez domyślnego layoutu witryny (dla stron z własnym pełnym HTML) | | `content` | string | nie | Treść strony (Liquid) | | `paragraph_codes` | array | nie | Lista kodów paragrafów | | `priority` | decimal | nie | Priorytet sortowania | | `in_menu` | boolean | nie | Czy strona widoczna w menu (domyślnie: true) | | `menu_code` | string | nie | Kod grupy menu (np. "top_menu", "footer_menu") | | `redirect_to` | string | nie | URL przekierowania | | `in_sitemap` | boolean | nie | Czy strona ma być w sitemap.xml (domyślnie: true). Auto-ustawiane na `false` gdy ustawisz `redirect_to`, i z powrotem na `true` gdy `redirect_to` zostanie wyczyszczone. Można ręcznie nadpisać po stronie API jeśli potrzeba | | `locale` | string | nie | Własny locale strony (np. `pl`, `en`). **Wygrywa nad `?lang=`, `domain.locale` i `site.locale`** — gdy ustawiony, strona zawsze renderuje się w tym języku. Decyduje którym wariantem językowym renderują się pola strony, paragrafów i layoutu z locale-keyed `fields`. Dla strony bez `page.locale` używane jest `?lang=` z URL, potem `domain.locale`, potem `site.locale` (patrz "Wielojęzyczne pola") | ### Paragraph | Pole | Typ | Wymagane | Opis | |------|-----|----------|------| | `code` | string | tak | Unikalny kod (zalecany format: `{site_code}-{nazwa}`) | | `name` | string | tak | Nazwa | | `kind` | string | tak | `text` (treść) lub `articles` (lista artykułów) | | `name` | string | nie | Tytuł paragrafu (opcjonalny). `text`: pokazuje się jako `

` nad treścią (gdy paragraf nie ma layoutu). `articles`: nagłówek `

` nad listą | | `content` | string | nie | Treść (tylko `kind: text`) | | `markup` | string | nie | Format treści: `html` lub `markdown` (auto-detect jeśli puste; tylko `kind: text`) | | `site_code` | string | nie | Code site'a | | `page_code` | string | nie | Code strony (podłącza paragraf do strony) | | `box_code` | string | nie | Kod boxa (do grupowania paragrafów, np. "sidebar", "footer") | | `page_id` | integer | nie | ID strony, do której paragraf należy. Puste = paragraf wspólny dla całej witryny (pokazuje się w swoim boxie na każdej stronie) | | `priority` | decimal | nie | Priorytet sortowania. Nowy paragraf bez jawnego `priority` trafia na koniec swojego boxa | | `system_template` | string | nie | Klucz gotowego szablonu prezentacji (nazwa analogiczna do Cms::Layout). `text`: `framed`/`highlight`/`hero`; `articles`: `default`/`cards`/`compact`. Nieznany/pusty nie jest zapisywany — prezentacja domyślna | | `template_content` | string | nie | Własny markup Liquid prezentacji ("Dostosuj" w edytorze) — wygrywa z `system_template` i layoutem. Dla `articles` warianty w blokach `...` i `...`. Pusty lub identyczny z bazowym jest usuwany; błąd składni Liquid blokuje zapis (422) | | `layout_id` | integer | nie | Layout paragrafu (Cms::Layout kind `paragraph`) — wielokrotnego użytku szablon prezentacji, patrz sekcja "Szablony prezentacji paragrafów" | **`kind: articles` — lista artykułów.** Tytuł nad listą to pole `name` paragrafu (opcjonalne). Zamiast `content` paragraf ma konfigurację w `fields`: | Pole w `fields` | Typ | Wymagane | Opis | |-----------------|-----|----------|------| | `category_codes` | array | nie | Kody kategorii (`code` z `Cms::Category`), z których brane są artykuły - artykuł wchodzi, gdy ma którąś z nich. Puste = wszystkie kategorie | | `per_page` | integer | nie | Ile najnowszych artykułów pokazać. Niepodany nie jest zapisywany w `fields`, a lista pokazuje domyślne 15 | Paragraf renderuje nagłówek `

` z `name` i najnowsze opublikowane artykuły z podanych kategorii. Każdy szablon ma dwa warianty markupu (`Cms::Paragraph::ArticlesRenderer::TEMPLATES`): `list` (artykuł na liście) i `show` (szczegóły). Zmienne Liquid jak w ``. Gdy URL wskazuje artykuł (`/strona/artykuł`), pierwszy paragraf `articles` na stronie renderuje szczegóły artykułu wariantem `show` zamiast listy — strona z samym paragrafem (bez tagu ``) ma więc działający widok szczegółów. Szablon prezentacji (dla `text` i `articles`) wybiera się kolumnami `system_template` / `template_content` / `layout_id` — patrz sekcja "Szablony prezentacji paragrafów". ### Asset | Pole | Typ | Wymagane | Opis | |------|-----|----------|------| | `name` | string | tak | Nazwa pliku (unikalna w ramach konta) | | `kind` | string | nie | `image`, `css`, `js`, `zip` (auto-detect z rozszerzenia) | | `file` | file | nie | Plik do wgrania | | `folder_id` | integer | nie | ID folderu | | `site_id` | integer | nie | ID site'a | | `layout_id` | integer | nie | ID layoutu | **Import ZIP:** Wgranie pliku ZIP z `kind: "zip"` automatycznie rozpakuje archiwum zachowując strukturę folderów. **URL pliku:** Po wgraniu asset dostępny jest pod `s3_url` (bezpośredni link S3). W treści stron i artykułów używaj **stabilnego permalinku** `/cms/assets/ID/view` — NIE `s3_url` (może wygasnąć) i NIE `{{ asset 'nazwa' }}` (nie działa jako tag Liquid). ### Article | Pole | Typ | Wymagane | Opis | |------|-----|----------|------| | `title` | string | tak | Tytuł artykułu | | `path` | string | auto | Ścieżka URL (auto-generowana z tytułu jeśli pusta) | | `category_id` | integer | nie | ID **kategorii głównej** (kanonicznej) - decyduje o adresie kanonicznym artykułu. Można zdjąć (`null`). Artykuł **bez żadnej kategorii** pokazuje tylko strona z tagiem bez `category_code` (blog ogólny); gdy witryna takiej nie ma, artykuł publicznie daje 404, a podgląd w admince ostrzega i ma przycisk **Dodaj stronę /blog** (`POST /cms/articles/:id/ensure_listing_page`). Tekst zamiast liczby = nazwa nowej kategorii (tak działa opcja „Dodaj nową…" w formatce) - w API używaj `category_code` | | `category_code` | string | nie | Kod kategorii głównej - wygodniejszy zamiennik `category_id`. Kod, którego nie ma, **zakłada nową kategorię na witrynie artykułu** (nazwa = kod). W odpowiedzi: kod głównej | | `category_codes` | array | nie | Wszystkie kategorie artykułu (kody, główna pierwsza). W zapisie **zastępuje** zestaw; gdy artykuł nie ma jeszcze głównej, główną zostaje pierwsza z listy. Przyjmuje też string `"news,poradnik"` | | `category_ids` | array | nie | To samo po ID (formatka: checkboxy **Kategorie**) | | `locale` | string | nie | Język artykułu (`pl`, `en`, ...). Na witrynie z `multilang` lista pokazuje tylko język domeny i artykuły bez locale | | `fields` | object | nie | Własne pola artykułu | | `author` | string | nie | Nazwa autora. Nazwa, której **nie ma** w `/cms/authors.json`, **zakłada autora** przy zapisie (dopasowanie do istniejącego bez względu na wielkość liter - `"fakturownia"` trafia w `"Fakturownia"`). Puste = artykuł bez autora. W odpowiedzi także `author_id` (ID rekordu z `/cms/authors`). Opis, zdjęcie i stronę autora ustawiasz na jego rekordzie, nie na artykule | | `abstract` | text | nie | Streszczenie/lead - zajawka na liście, fallback meta description, opis w OG i JSON-LD | | `summary` | text | nie | „W skrócie" (answer-first) - box nad treścią artykułu. Puste = brak boxa. **Nie** trafia do meta description ani do domyślnej zajawki na liście (w szablonie `{{ summary }}` jest dostępne wszędzie) - patrz „Streszczenie, W skrócie i Opis HTML" | | `content` | text | nie | Pełna treść | | `markup` | string | nie | Format treści: `html` lub `markdown` (auto-detect jeśli puste) | | `image_url` | string | nie | URL obrazka głównego | | `published_at` | datetime | tak | Data publikacji (domyślnie: teraz) | | `publish_to` | datetime | nie | Data zakończenia publikacji | | `accepted` | boolean | nie | Zaakceptowany (domyślnie: true) | | `published` | boolean | nie | Opublikowany (domyślnie: true) | | `site_id` | integer | tak* | Witryna artykułu - jej strony go pokazują. *Gdy konto ma **dokładnie jedną** witrynę, można pominąć (dobiera się sama); przy kilku brak = 422 z błędem na `site_id`. Kategoria główna musi należeć do tej samej witryny | | `html_title` | string | nie | Tytuł HTML (meta title) | | `html_description` | text | nie | Opis HTML (meta description) | | `html_keywords` | string | nie | Słowa kluczowe (meta keywords) | **Streszczenie, W skrócie i Opis HTML:** Trzy pola opisowe, które łatwo pomylić. Każde ma jednego odbiorcę - nie powielaj tej samej treści: | Pole | Etykieta w formatce | Gdzie trafia | |------|---------------------|--------------| | `abstract` | Streszczenie | zajawka na liście artykułów, meta description (gdy `html_description` puste), OG/Twitter, `description` w JSON-LD BlogPosting | | `summary` | W skrócie | **tylko** box `
` nad treścią artykułu + `{{ summary }}` w szablonie; `description` w `llms.txt` (fallback na `abstract`, gdy puste); wyszukiwarka artykułów | | `html_description` | Opis HTML | meta description wprost - wygrywa z `abstract` | `summary` jest pisane pod odpowiedź (answer-first, dla wyszukiwarek i modeli), `abstract` pod kliknięcie. Świadomie nie idzie do meta ani na listę - inaczej box na górze artykułu byłby kopią meta opisu, a o to właśnie chodziło w rozdzieleniu tych pól. Renderuje się markdownem/HTML-em jak treść artykułu (zależnie od `markup`). Opcjonalność załatwia sama treść: puste pole = boxa nie ma, więc nie ma osobnego przełącznika „pokazuj/nie pokazuj". Szablon, który chce własny wygląd, bierze `{{ summary }}` i renderuje po swojemu. ``` PATCH /cms/articles/123.json { "article": { "summary": "Fakturę korygującą wystawisz w 3 krokach: ..." } } ``` **Kategorie i adresy (zadanie #1378):** Kategoria to rekord (`/cms/categories.json`), nie string. Artykuł ma **kilka kategorii** i co najwyżej jedną **główną** (`category_id`) - opcjonalną (artykuły można pisać przed ustawieniem stron witryny; bez kategorii pokazuje je tylko blog ogólny). Nie ma już osobnego „tematu" (`topic`, `fields.category`): dawny temat to dziś dodatkowa kategoria z `path`. | Wymiar | Pole | Co robi | |--------|------|---------| | kategoria główna | `category_id` / `category_code` | wyznacza **adres kanoniczny**: `///`. Gdy żadna strona witryny jej nie listuje, system **sam zakłada stronę `/blog`** z `` (albo dopisuje ten tag do istniejącego `/blog`) i podpina ją jako kanoniczną | | kategorie dodatkowe | `category_codes` / `category_ids` | artykuł pokazuje się na każdej stronie, której tag wymienia którąś z jego kategorii | | `path` kategorii | pole kategorii | segment w adresie artykułu i podstrona listująca `//` (chipy `{{ topics }}`, sitemapa). Kategoria bez `path` = artykuł wprost pod stroną | | język | `locale` | wersja językowa; filtrowana automatycznie na witrynie z `multilang` | Który segment wchodzi do adresu: `category_code` tagu strony tylko **filtruje**, które artykuły się pokazują - segment bierze się z kategorii **samego artykułu**: kategoria główna, gdy ma `path`, inaczej pierwsza dodatkowa z `path` w kolejności `priority` (mniejszy pierwszy), remis po `id`. Żadna kategoria artykułu nie ma `path` → adres wprost pod stroną. Dzięki temu jedna kategoria z `path` (np. `poradnik`) daje prefiks wszystkim swoim artykułom pod każdą stroną, bez wymieniania jej w tagu. Przykład: strona `/page1` z tagiem `category_code="news,poradnik"`, `news` ma `path: news`, `poradnik` ma `path: poradnik`: | Artykuł | Kategorie | Adres | |---------|-----------|-------| | a1 | `news` (główna) | `/page1/news/a1` | | a2 | `poradnik` (główna), `temat1` | `/page1/poradnik/a2` | | a3 | `temat1` (główna, ma `path`), nielistowana przez `/page1` | `/blog/temat1/a3` (blog ogólny, tag bez `category_code`) | | a4 | `blog` (główna, bez `path`) | `/blog/a4` | | a5 | `blog` (główna, bez `path`), `poradnik` | `/blog/poradnik/a5` - segment z dodatkowej, choć `/blog` nie wymienia `poradnik` | Adres z innym segmentem albo pod inną stroną listującą (np. `/blog/a1`) robi 301 na kanoniczny. `?topic=` na stronie listującej: kategoria z `path` → 301 na `//`, bez `path` → zawężenie listy w miejscu. Nie koduj języka w kodzie kategorii (`blog-en`) - każdy kod to osobna sekcja. ``` PATCH /cms/articles/123.json { "article": { "category_code": "blog", "category_codes": ["blog", "porady"], "locale": "pl" } } ``` Zgodność wstecz: `category_code` w JSON nadal jest (kod głównej), a stare `?category=` / `?topic=` w adresach witryny działają. Pole `topic` i `fields["category"]` zostały usunięte - migracja zrobiła z każdego tematu kategorię z `path` równym kodowi. **Logika publikacji:** - Artykuł jest widoczny gdy: `published = true` AND `published_at` jest w przeszłości AND (`publish_to` jest null LUB `publish_to` jest w przyszłości) - Gdy `accepted = false`, automatycznie ustawiane jest `published = false` **Konwencja nazewnictwa:** Aby uniknąć konfliktów między site'ami, używaj prefiksu `{site_code}-` w kodach: - Layout: `strona1-layout` - Page: `strona1-home`, `strona1-about` - Paragraph: `strona1-intro`, `strona1-footer` --- ### Category (kategoria artykułów) | Pole | Typ | Wymagane | Opis | |------|-----|----------|------| | `name` | string | tak | Nazwa pokazywana na witrynie (`{{ c.name }}` w menu i chipach) | | `code` | string | tak | Kod - unikalny w witrynie (ten sam kod może istnieć na dwu witrynach). Używany w `category_code` tagu i artykułu | | `path` | string | nie | Segment adresu: artykuły dostają `///`, a lista podstronę `//`. Unikalny w witrynie. Puste = kategoria nie zmienia adresów | | `priority` | decimal | nie | Kolejność kategorii (domyślnie 1, mniejszy pierwszy, remis po `id`): w `{{ categories }}`/`{{ topics }}`, w liście kategorii artykułu i przy wyborze segmentu adresu, gdy główna nie ma `path`, a kilka dodatkowych ma | | `site_id` | integer | tak* | Witryna - jej strony listują kategorię. *Gdy konto ma **dokładnie jedną** witrynę, można pominąć (dobiera się sama); przy kilku brak = 422 z błędem na `site_id`. Starsze kategorie mogą mieć puste `site_id` (sprzed wymagalności) - działają na każdej witrynie, ale ich edycja wymaga już wybrania witryny | | `page_id` | integer | nie | Strona kanoniczna - pod nią mają adres kanoniczny artykuły z tą kategorią główną. Musi listować kategorię (tag bez `category_code` albo z jej kodem); puste = pierwsza strona witryny listująca kategorię. Wypełnia się samo przy automatycznym `/blog` | | `description` | text | nie | Opis (`{{ c.description }}` w Liquid) | | `fields` | object | nie | Własne pola | JSON kategorii nie zawiera `account_id`. `DELETE` kategorii, która jest **główną** jakiegoś artykułu, zwraca 422 - najpierw zmień tym artykułom kategorię główną; powiązania dodatkowe kasują się same. ``` POST /cms/categories.json { "category": { "name": "Porady", "code": "porady", "path": "porady", "site_id": 5 } } ``` ### Author (autor artykułów) Centralna lista autorów konta (wspólna dla witryn). Nazwa jest unikalna w koncie bez względu na wielkość liter. Autor **nie musi** być użytkownikiem Intuma (gość, agencja, redakcja), ale **może** - wtedy puste `name`/`description`/`avatar_url` biorą się z profilu użytkownika, a wpisane wprost nadpisują profil. | Pole | Typ | Wymagane | Opis | |------|-----|----------|------| | `name` | string | tak | Nazwa - ta sama, którą wpisujesz w `author` artykułu. Unikalna w koncie (bez względu na wielkość liter) | | `description` | text | nie | Opis publiczny pod artykułem i w schema `Person` | | `avatar_url` | string | nie | URL zdjęcia (musi być http/https) | | `url` | string | nie | Strona autora - profil, blog, LinkedIn (http/https); trafia do `sameAs` w schema | | `user_id` | integer | nie | ID użytkownika Intuma - podpięcie pod profil (nazwa, opis, avatar z profilu, gdy własne puste) | | `fields` | object | nie | Własne pola | W odpowiedzi dodatkowo wyliczone `display_name`, `display_description`, `display_avatar_url` (wartość własna albo z profilu użytkownika). JSON nie zawiera `account_id`. **Nie zakładaj autora osobnym `POST`, gdy dodajesz artykuł** - wystarczy `author` w artykule, rekord powstanie sam. `POST /cms/authors.json` ma sens, gdy od razu chcesz nadać opis/zdjęcie, albo gdy autor ma być podpięty pod użytkownika: ``` POST /cms/authors.json { "author": { "name": "Jan Kowalski", "description": "Redaktor bloga", "user_id": 12 } } ``` Tak samo z kategoriami: `category_code` w artykule z kodem, którego nie ma, zakłada kategorię na witrynie artykułu (nazwa = kod z wielkiej litery). `POST /cms/categories.json` jest potrzebny, gdy kategoria ma mieć własny `path`, `page_id` lub opis albo ma powstać na innej witrynie. ## Liquid Templates Strony używają szablonów Liquid. Dostępne zmienne: | Zmienna | Opis | |---------|------| | `{{ name }}` | Nazwa strony | | `{{ path }}` | Ścieżka strony z `/` (np. `/`, `/about`) | | `{{ url }}` | Pełny URL strony | | `{{ content }}` | Treść (w layoucie - miejsce na content strony) | | `{{ paragraphs }}` | Lista paragrafów przypisanych do strony | | `{{ pages }}` | Lista wszystkich stron w site (do budowy menu) | | `{{ page }}` | Obiekt aktualnie wyświetlanej strony | | `{{ site }}` | Obiekt site'a (`site.name`, `site.code`, `site.description`, `site.url`) | | `{{ layout }}` | Obiekt layoutu (`layout.name`, `layout.code`, `layout.description`) | | `{{ categories }}` | Kategorie artykułów witryny z opublikowanymi artykułami, w kolejności `priority`, potem `id` - do menu bloga (`code`, `name`, `path`, `description`, `url`, `current`) | | `{{ topics }}` | Kategorie **z `path`** listowane przez tę stronę, w kolejności `priority`, potem `id` - do chipów nad listą (`code`, `name`, `path`, `url`, `current`) | | `{{ year }}` | Aktualny rok | | `{{ powered_by }}` | "Intum" | | `{{ preview_mode }}` | `true` jeśli strona jest w trybie podglądu | | `{{ base_path }}` | Prefiks do budowania linków (`{{ base_path }}/kontakt`): w preview `/w/`, na domenie klienta `path_prefix` witryny (zwykle pusty) | ### Właściwości obiektów **Page** (`page`, elementy `pages`): - `id` - ID strony - `name` - nazwa strony - `title` - tytuł strony (z fields lub name) - `path` - ścieżka (w preview: `/w/site/path`, normalnie: `/path`) - `raw_path` - surowa ścieżka z bazy, bez prefiksów (np. `rejestr-zmian`) - do porównań w Liquid ({% if page.raw_path == 'rejestr-zmian' %}) - `url` - pełny URL - `site_id` - ID site'a - `html_title` - tytuł HTML - `html_description` - opis HTML (meta description) - `html_keywords` - słowa kluczowe (meta keywords) - `html_script` - skrypt HTML **Site**: - `name` - nazwa site'a - `code` - kod site'a - `description` - opis - `url` - URL site'a **Layout**: - `name` - nazwa layoutu - `code` - kod layoutu - `description` - opis - `content` - treść szablonu ### Własne pola (fields) Każdy obiekt (Page, Site, Layout) może mieć własne pola w `fields`. Dostęp do nich w szablonach: ```liquid {{ page.owner }} → page.fields["owner"] {{ page.html.title }} → page.fields["html"]["title"] (zagnieżdżone) {{ owner }} → page.fields["owner"] (skrót - tylko dla page) {{ html.title }} → page.fields["html"]["title"] (skrót) {{ site.company }} → site.fields["company"] {{ layout.version }} → layout.fields["version"] ``` Nazwa pola w `content` musi być poprawną zmienną Liquida (`[A-Za-z_][\w-]*`). Tekst w klamrach (`{{ Nasz zespół }}`, całe zdanie) przy zapisie rekordu zamienia się na klucz z pierwszych słów (`{{ nasz_zespol }}`, w layoucie `{{ layout.nasz_zespol }}`), a tekst trafia do `fields[klucz]` jako wartość początkowa (istniejący klucz nie jest nadpisywany). Tworząc treść przez API pisz od razu `{{ klucz }}` + `fields`. **Przykład użycia w layoucie:** ```liquid {{ page.html.title }} - {{ site.name }}

{{ site.name }}

Wersja szablonu: {{ layout.version }}

{{ content }}
© {{ year }} {{ page.owner }}
``` **Ustawianie fields przez API:** ``` PATCH /cms/pages/strona1-home.jsonContent-Type: application/json { "page": { "fields": { "owner": "Jan Kowalski", "html": { "title": "Strona główna" } } } } ``` ### ANTYWZORZEC: cała strona w jednym polu (`content: "{{ body }}"`) **Nigdy nie wrzucaj całego HTML-a strony do jednego pola `fields`** i nie zostawiaj w `content` samego `{{ body }}`: ```json // ŹLE - cała strona (struktura + teksty + linki) siedzi w jednym polu, per język { "page": { "content": "{{ body }}", "fields": { "en": { "body": "

A tiling desktop

...5 kB HTML..." }, "pl": { "body": "

Kafelkowy pulpit

...5 kB HTML..." } } } } ``` Dlaczego to boli: - **Duplikacja markupu** - każdy język to osobna kopia całego HTML-a. Zmiana klasy CSS albo dołożenie przycisku to ta sama poprawka zrobiona N razy, a przy N+1 języku rozjazd jest kwestią czasu - **Edytor pola staje się edytorem HTML** - użytkownik, który chce poprawić jedno zdanie, dostaje kilka kilobajtów znaczników i łatwo zepsuje strukturę - **Nie da się zmienić układu bez ruszania tłumaczeń** (i odwrotnie) - **Nic nie jest adresowalne** - nie podmienisz przez API samego nagłówka czy adresu CTA, bo nie ma takiego klucza; trzeba przepisać całe pole **Dobrze: `content` to szablon (HTML + Liquid), `fields` to wszystkie teksty, linki i listy** - per język tylko to, co faktycznie się tłumaczy: ```json { "page": { "content": "
\n

{{ hero_title }}

\n

{{ hero_lead }}

\n {{ cta_demo }}\n {% for card in cards %}

{{ card.title }}

{{ card.text }}

{% endfor %}\n
", "fields": { "demo_url": "/run", "en": { "hero_title": "A tiling desktop, in a browser tab", "hero_lead": "Tiles split the screen instead of overlapping.", "cta_demo": "Try the live demo", "cards": [{ "title": "BSP tiling", "text": "Tiles divide the screen." }] }, "pl": { "hero_title": "Kafelkowy pulpit, w karcie przeglądarki", "hero_lead": "Kafelki dzielą ekran zamiast na siebie nachodzić.", "cta_demo": "Wypróbuj demo na żywo", "cards": [{ "title": "Układ BSP", "text": "Kafelki dzielą ekran." }] } } } } ``` Zasady podziału: - **W `content` tylko markup**: tagi, klasy, atrybuty, ikony SVG, `{% for %}`/`{% if %}`. Ani jednego zdania widocznego dla użytkownika - **W `fields` teksty, adresy i listy**: nagłówki, akapity, napisy przycisków, `href`-y, identyfikatory osadzanych formularzy, tablice kart/FAQ/cennika - **Wartość, która nie zależy od języka** (adres GitHuba, `/run`, kod formularza wspólny dla wszystkich wersji) idzie **top-level**, poza sub-hasze `pl`/`en` - działa wtedy jako fallback dla każdego locale i zapisujesz ją w jednym miejscu - Krótki fragment HTML **wewnątrz** zdania (``, ``, ``) zostaje w polu razem z tekstem - szyk zdania bywa inny w każdym języku, więc nie da się go rozbić na kawałki w szablonie - Nazwa klucza musi być poprawną zmienną Liquida i mówić o roli, nie o wyglądzie (`hero_lead`, `cta_demo`, `signup_form_id` - nie `text1`, `bold_blue`) Strony dziedziczące (`based_on_page_id`) korzystają z tego wprost: slave ma puste `content` i puste `fields`, a bierze szablon i teksty od mastera wg swojego `locale`. **Przerabianie istniejącej strony z `{{ body }}` na szablon + fields**: zrób kopię aktualnego `content` i `fields`, wytnij teksty do kluczy, wyślij `content` i `fields` jednym `PATCH`, a potem porównaj wyrenderowany HTML sprzed i po zmianie (pomijając białe znaki) - powinien wyjść identyczny. ### Tablice w fields (zalecane dla list i cenników) Dla dynamicznych treści jak cenniki, listy funkcji, FAQ - **zalecane jest używanie tablic w fields**. Ułatwia to edycję danych bez modyfikacji HTML. **Przykład: cennik z planami:** ``` PATCH /cms/pages/cennik.jsonContent-Type: application/json { "page": { "fields": { "plans": [ { "name": "Micro", "price": "0", "users": "1", "popular": false }, { "name": "Start", "price": "49", "users": "2", "popular": true }, { "name": "Pro", "price": "149", "users": "5", "popular": false } ], "faq": [ { "question": "Czy mogę zmienić plan?", "answer": "Tak, w dowolnym momencie." }, { "question": "Czy jest okres próbny?", "answer": "Tak, 14 dni za darmo." } ] }, "content": "... szablon Liquid używający plans i faq ..." } } ``` **Szablon Liquid (content):** ```liquid

Cennik

{% for plan in plans %}

{{ plan.name }}

{{ plan.price }} zł/mies.

{{ plan.users }} użytkowników

{% endfor %}

FAQ

{% for item in faq %}

{{ item.question }}

{{ item.answer }}

{% endfor %} ``` **Ważne:** Pola z `fields` są dostępne bezpośrednio w Liquid (np. `plans`, `faq`), **nie** przez `fields.plans`. **Zagnieżdżone tablice (np. features w planie):** ```json { "plans": [ { "name": "Pro", "features": ["CRM", "Fakturowanie", "API", "Priorytetowe wsparcie"] } ] } ``` ```liquid {% for plan in plans %}

{{ plan.name }}

    {% for feature in plan.features %}
  • {{ feature }}
    • {% endfor %}
{% endfor %} ``` **Warunki w pętli:** ```liquid {% for plan in plans %} {% if plan.popular %}
{{ plan.name }} - Popularny!
{% else %}
{{ plan.name }}
{% endif %} {% endfor %} ``` **Zalety używania tablic w fields:** - Łatwa edycja danych bez dotykania HTML - Możliwość zmiany cen, nazw, opisów przez API - Czytelna struktura danych - Możliwość dynamicznego dodawania/usuwania elementów **Edycja tablic w fields (dodanie pozycji menu, planu, pytania FAQ):** - **Nie używaj `set_field`** - zapisuje `value` jako tekst, tablica zamieni się w string i pętla `for` przestanie działać - Zrób GET rekordu, zmień tablicę lokalnie i wyślij **całe** `fields` przez zwykły PATCH: `PATCH /cms/pages/:code.json` z `{"page": {"fields": {...}}}` albo `PATCH /cms/layouts/:code.json` z `{"layout": {"fields": {...}}}` - PATCH z `fields` **podmienia cały jsonb** - odeślij wszystkie klucze i wszystkie sub-hashe językowe (`pl`, `en`, ...), nie tylko ten zmieniany. Po zapisie porównaj `fields` z odpowiedzi z tym, co wysłałeś - Na witrynie wielojęzycznej tablica zwykle jest osobno w każdym locale (`fields.pl.nav_items`, `fields.en.nav_items`) - zmieniaj tylko wersje językowe, w których dodawana strona istnieje ### Szablony paragrafów Paragrafy mogą używać Liquid do dynamicznej treści. Dostępne zmienne: | Zmienna | Opis | |---------|------| | `{{ name }}` | Nazwa paragrafu (z pola `name`, fallback do `fields["name"]`) | | `{{ description }}` | Opis paragrafu (z pola `description`, fallback do `fields["description"]`) | | `{{ dowolne_pole }}` | Wartość z `fields["dowolne_pole"]` | **Przykład paragrafu z fields:** ``` POST /cms/paragraphs.json { "paragraph": { "code": "strona1-team-jan", "name": "Jan Kowalski", "kind": "text", "content": "

{{ name }}

{{ position }}

", "site_code": "strona1", "box_code": "team", "fields": { "position": "Senior Developer" } } } ``` ### Szablony prezentacji paragrafów (system_template / template_content) Prezentację paragrafu wybiera się i dostosowuje przez kolumny `system_template` (klucz gotowego szablonu, nazwa analogiczna do Cms::Layout), `template_content` (własny markup) i `layout_id` (layout wielokrotnego użytku) — to działa tak samo z API, jak z edytora WYSIWYG (zakładka Szablon). Pełny opis systemu paragrafów: [CMS Paragrafy](https://intum.intum.pl/kb/intum-kb/cms/api/paragrafy). **Hierarchia nadpisań** (silniejszy wygrywa): `template_content` (własny markup) > `layout_id` (layout) > `system_template` (gotowy szablon) > prezentacja domyślna. **Paragraf `text`** — treść można opakować gotowym szablonem albo własnym markupem Liquid: | Pole | Opis | |------|------| | `system_template` | `framed` (ramka), `highlight` (wyróżnienie z paskiem), `hero` (baner, wyśrodkowany). Brak/nieznany = domyślna prezentacja: opcjonalny `

` z `name` + treść + zdjęcie | | `template_content` | Własny markup Liquid — wygrywa z `system_template` i layoutem | | `fields.image_url` | Załącznik (zdjęcie) paragrafu — publiczny URL. Domyślna prezentacja i gotowe szablony renderują go pod treścią (`{% if image_url != blank %}`). Upload pliku: `POST /cms/assets.json` (multipart, `asset[kind]=image`) → do `fields.image_url` wpisz `s3_url` z odpowiedzi; formatka CRUD ma też pole `paragraph[image]` (plik), które robi to samo | Szablon dostaje zmienne: `{{ content }}` (wyrenderowana treść paragrafu — po Liquid i konwersji markdown), `{{ name }}`, `{{ description }}`, `{{ image_url }}` oraz własne pola z `fields`. Markupy gotowych szablonów: `Cms::Paragraph::ParagraphRenderer::TEMPLATES`. ``` POST /cms/paragraphs.json { "paragraph": { "code": "strona1-promo", "name": "Promocja", "kind": "text", "content": "Do końca miesiąca **-20%** na wszystko.", "markup": "markdown", "site_code": "strona1", "box_code": "main", "system_template": "highlight" } } ``` Własny szablon (odpowiednik przycisku "Dostosuj"): ``` PATCH /cms/paragraphs/123.json { "paragraph": { "template_content": "" } } ``` **Paragraf `articles`** — szablon ma dwa warianty: `list` (artykuł na liście) i `show` (widok szczegółów po kliknięciu): | Pole | Opis | |------|------| | `system_template` | `default`, `cards` (z obrazkiem `image_url`), `compact` (data + link) | | `template_content` | Własny markup Liquid z wariantami w blokach `...` i `...` (markup bez bloków = sam wariant listy) — wygrywa z `system_template` i layoutem | Zmienne w obu wariantach (podzbiór ``): `{{ id }}`, `{{ title }}`, `{{ path }}` (link do artykułu), `{{ author }}`, `{{ category_code }}`, `{{ abstract }}`, `{{ summary }}` („w skrócie"), `{{ content }}`, `{{ image_url }}`, `{{ published_at }}`, `{{ published_at_date }}`, `{{ published_at_iso }}`, `{{ updated_at_iso }}`, `{{ back_url }}` (powrót na stronę z listą), `{{ fields }}` (własne pola artykułu) oraz pozycja wpisu na liście: `{{ index }}` (od zera), `{{ position }}` (od jedynki), `{{ total }}`, `{{ first }}`, `{{ last }}`. Markupy gotowych szablonów: `Cms::Paragraph::ArticlesRenderer::TEMPLATES`. ``` POST /cms/paragraphs.json { "paragraph": { "code": "strona1-aktualnosci", "name": "Aktualności", "kind": "articles", "site_code": "strona1", "page_code": "strona1-home", "box_code": "news", "system_template": "cards", "template_content": "\n
{{ title }}
\n", "fields": { "category_codes": ["aktualnosci"], "per_page": 5 } } } ``` **Layout paragrafu jako szablon prezentacji.** Zamiast gotowego szablonu paragraf może wskazywać `layout_id` (Cms::Layout kind `paragraph`) — wielokrotnego użytku, wspólny dla wielu paragrafów: - `text`: treść layoutu to pełny szablon — dostaje `{{ content }}` (wyrenderowaną treść paragrafu) i pola paragrafu; `system_template` wtedy nie gra, - `articles`: layout może definiować warianty w blokach `...` i `...` — wygrywa z `system_template`, przegrywa z `template_content`, - formatka `/cms/layouts` przy kind `paragraph` ma przyciski wstawiające markup gotowych szablonów; w edytorze WYSIWYG layouty są w tym samym selekcie co gotowe szablony. **Zasady wspólne (normalizacja przy zapisie):** - Pusty lub **identyczny z bazowym** własny markup (`template_content`) jest usuwany — zamrożona kopia nie dostawałaby przyszłych poprawek gotowego szablonu. Chcąc wrócić do gotowego szablonu, wyślij `"template_content": null` - Nieznany klucz `system_template` jest usuwany — renderuje się domyślna prezentacja - **Błąd składni Liquid we własnym szablonie blokuje zapis** (422, komunikat w `errors.template_content`). Na żywej stronie błąd Liquid degraduje do pustej treści, więc walidacja łapie go wcześniej - Stare klucze `fields.template`/`fields.template_content` są przy zapisie przenoszone do kolumn, a `fields.template_list`/`template_show` usuwane - Uwaga na cały jsonb: `PATCH` z `fields` **podmienia całość** — modyfikując jeden klucz (np. `category_codes`), odeślij też pozostałe (najpierw GET) ### Wielojęzyczne pola Pola `fields` w **Page**, **Paragraph** i **Layout** wspierają zagnieżdżone hashe z kluczem locale (`pl`, `en`, ...). Site i Domain mają własne pole `locale` które wpływa na fallback chain. **Pełna dokumentacja wielojęzyczności (strategie, chain fallback, per-domain locale, page inheritance):** [CMS Wielojęzyczność](https://intum.intum.pl/kb/intum-kb/cms/api/wielojezycznosc) ### Iteracja po paragrafach ```liquid {% for p in paragraphs %}

{{ p.name }}

{{ p.content }}

{% endfor %} ``` ### Menu nawigacyjne z podświetleniem aktualnej strony ```liquid ``` **Uwaga:** W trybie podglądu (`/w/...`) linki automatycznie prowadzą do podglądu, a pod własną domeną - do normalnych ścieżek. ### Menu z grupami (menu_code) Strony można przypisać do grup menu przez pole `menu_code`. Filtrowanie w Liquid wymaga użycia `assign` przed pętlą `for`: ```liquid {% assign top_menu = pages | where: "menu_code", "top_menu" %} ``` **Przykład layoutu z wieloma menu:** ```liquid
{% assign main_menu = pages | where: "menu_code", "main" %} {% for p in main_menu %} {{ p.name }} {% endfor %}
{{ content }}
{% assign footer_menu = pages | where: "menu_code", "footer" %} {% for p in footer_menu %} {{ p.name }} {% endfor %}
``` **Uwaga:** Zmienna `pages` zawiera tylko strony z `in_menu = true`. Strony z `in_menu = false` nie pojawiają się w menu. ### Menu z tablicy w fields szablonu Menu nie musi pochodzić z `pages` - wiele szablonów trzyma linki jako tablice w `fields` layoutu (np. `nav_items`, `product_dropdown_items`, `footer_product_items`), per język: ```liquid {% for p in layout.nav_items %} {{ p.name }} {% endfor %} ``` **Zanim dodasz stronę do menu, sprawdź w `content` layoutu, skąd menu bierze linki:** - pętla po `pages` → ustaw na stronie `in_menu` / `menu_code` - pętla po `layout.` → dopisz pozycję (`{"name": "...", "path": "/..."}`, plus pola, których używa pętla, np. `sub`) do tablicy w `fields` layoutu - jak w "Edycja tablic w fields". Samo `in_menu` na stronie nic wtedy nie zmieni Ta sama tablica bywa użyta w kilku miejscach (menu desktopowe, mobilne, stopka) - dopisanie pozycji zmienia je wszystkie, więc przejrzyj każde użycie klucza w layoucie. ### Menu kategorii i chipy kategorii z `path` `{{ categories }}` (kategorie artykułów witryny) i `{{ topics }}` (kategorie z `path`, które ta strona listuje) zawierają tylko pozycje z opublikowanymi artykułami w języku domeny - żaden link nie prowadzi na pustą listę. Każda pozycja ma `code`, `name`, `path`, `url` i `current`: | Pole | Opis | |------|------| | `code` | Kod kategorii | | `name` | Nazwa kategorii (pole **Nazwa** w `/cms/categories`) | | `path` | Segment adresu kategorii (puste, gdy kategoria go nie ma) | | `description` | Opis kategorii (tylko `categories`) | | `url` | `categories`: adres listingu - strona, która listuje kategorię, plus `/` gdy go ma (puste, gdy żadna strona jej nie listuje). `topics`: podstrona kategorii pod tą stroną (`//`) | | `current` | `true` gdy to właśnie ta kategoria jest wyświetlana (z tagu strony albo z adresu) | ```liquid
{% for t in topics %} {{ t.name | escape }} {% endfor %}
``` **Uwaga:** `name` i `description` to surowe wartości z bazy - przy wypisywaniu używaj filtra `escape`. ### Tag CMS box - renderowanie paragrafów z boxa Tag `` wstawia paragrafy z danego site'a, które mają `box_code = X`. Paragrafy są sortowane po `priority` rosnąco (niższy = wyżej), przy równych priorytetach po `id`. **Składnia:** ```html ``` | Atrybut | Opis | |---------|------| | `type` | Typ tagu (obecnie: `box`) | | `id` | Wartość `box_code` paragrafów do wstawienia | | `max` | Opcjonalnie: maksymalna liczba paragrafów (np. `max="1"` dla bannera). Pełny box nie pokazuje w trybie edycji przycisku dodania treści | | `scope` | `page` (domyślnie) albo `site` — patrz niżej | **`scope` — zasięg boxa** Paragraf ma pole `page_id`: albo należy do konkretnej strony, albo jest wspólny dla całej witryny (`page_id` puste). - `scope="page"` (domyślnie) — box pokazuje paragrafy **tej strony** (`page_id` = ta strona) oraz **wspólne** (`page_id` puste). Paragraf dodany w tym boxie w trybie edycji WYSIWYG dostaje `page_id` bieżącej strony, więc box o tym samym kodzie na innej stronie go nie pokaże. - `scope="site"` — box wspólny dla całej witryny (stopka, nagłówek, belka cookies). Pokazuje **tylko** paragrafy bez `page_id`, i takie też zakłada w trybie edycji. Ten sam paragraf pojawia się wtedy na każdej stronie używającej tego boxa. Boxy w layoucie, które mają wyglądać identycznie na wszystkich stronach, powinny mieć `scope="site"`. **Przykład layoutu z sidebar i footer:** ```html {{ name }}
{{ content }}
``` **Tworzenie paragrafów z box_code przez API:** ``` POST /cms/paragraphs.json { "paragraph": { "code": "strona1-sidebar-promo", "name": "Promocja", "kind": "text", "content": "
Sprawdź naszą ofertę!
", "site_code": "strona1", "box_code": "sidebar", "priority": 10 } } ``` ### Tagi CMS changelog - metryczka i rejestr zmian (BIP) ```html ``` Oba tagi wymagają włączonego rejestru zmian witryny (`Cms::Site#change_log`) — bez niego znikają bez śladu. Działają w treści strony i w layoucie. **`changelog_page` — metryczka BIP strony.** Podsumowanie z rejestru zmian (`Cms::ChangeLog`) strony i jej paragrafów: data wytworzenia, autor, data publikacji i osoba udostępniająca (pierwszy wpis rejestru), data ostatniej modyfikacji i osoba modyfikująca (ostatni wpis). Fallback do atrybutów strony, gdy rejestr włączono później. Markup: `section.cms-changelog-page`. **`changelog_site` — pełny rejestr zmian witryny.** Publiczna tabela wpisów (`publicly_visible`): data, zdarzenie, tytuł, ścieżka, osoba; najnowsze pierwsze. Atrybut `per_page` (domyślnie 50, max 200). Markup: `section.cms-changelog-site`. **Własny markup (inner template, Liquid — jak w ``, ale bez podziału ``/``):** ```html
{{ created_at }} — {{ event }}: {{ title }} ({{ user_name }})

Autor: {{ author }}, ostatnia zmiana: {{ updated_at }} ({{ updated_by }})

 ``` Szablon systemowy `bip_prosty_1` ma `changelog_page` pod `{{ content }}`, a na stronie o ścieżce `rejestr-zmian` pokazuje `changelog_site` przed treścią (Liquid: `{% if page.path == 'rejestr-zmian' %}`). ### Tag CMS article - lista i widok artykułów Tag `` obsługuje zarówno wyświetlanie listy artykułów jak i pojedynczego artykułu. Automatycznie rozpoznaje czy pokazać listę czy szczegóły na podstawie ścieżki URL. **Jak to działa:** - `/blog` → wyświetla listę artykułów (sekcja ``) - `/blog/moj-artykul` → wyświetla pojedynczy artykuł (sekcja ``) **Składnia:** ```html
{{ title }}

{{ title }}

{{ author }}

{{ abstract }}

 ``` | Atrybut | Opis | |---------|------| | `type` | `article` | | `category_code` | Opcjonalnie: kody kategorii artykułów. Kilka kodów po przecinku (`category_code="blog,radar"`) łączy je w jedną chronologiczną listę; artykuł wchodzi, gdy ma którąś z nich. Atrybut tylko filtruje - segment `path` w adresie daje kategoria samego artykułu (główna, inaczej pierwsza dodatkowa z `path` wg `priority`), niezależnie od tego, co wymienia tag. Brak atrybutu = wszystkie kategorie | | `topic` | Opcjonalnie: zawężenie na sztywno do jednej kategorii (kod albo `path`). `topic="any"` wyłącza zawężanie kategorią z URL-a (blok "najnowsze" obok chipów zostaje pełny) | | `mode` | `list` - zawsze lista, `detail` - zawsze widok artykułu. Domyślnie zależnie od adresu | | `per_page` | Opcjonalnie: artykułów na stronie (domyślnie: 10, max: 25) | | `paginate` | `paginate="false"` - lista bez paginacji (sekcja "najnowsze" na stronie głównej) | | `site` | Domyślnie lista pokazuje **tylko artykuły witryny, na której stoi strona**. `site="any"` pokazuje artykuły ze wszystkich witryn konta. Artykuł nie może być wspólny dla kilku witryn - ma jedną witrynę | **Zawężanie kategorią z adresu:** lista bez atrybutu `topic` czyta kategorię ze ścieżki (`/blog/porady` - podstrona kategorii z `path`) albo z parametru `?topic=porady` (stare linki `?category=porady` też działają; kategoria z `path` robi z nich 301 na ścieżkę). Linki do chipów buduje zmienna `{{ topics }}` (patrz "Menu kategorii i chipy kategorii z `path`"). **WAŻNE:** - Artykuł renderuje się tylko na witrynie, do której należy (`site_id`) — artykuł innej witryny ani stary bez witryny nie pokaże się na liście, chyba że tag ma `site="any"` - Zmienne Liquid w template `` i `` są **FLAT**: `{{ title }}`, `{{ path }}`, `{{ abstract }}`, `{{ summary }}`, `{{ content }}`, `{{ published_at }}`, `{{ image_url }}`, `{{ back_url }}`, `{{ author }}` — NIE `{{ article.title }}` - Jeśli treść artykułu zawiera przykłady kodu Liquid (`{{ }}`, `{% %}`), owij ją w `...` — bez tego CMS zwróci 500 - Layout musi mieć ustawiony `site_id` — bez tego `` może nie renderować artykułów **Obrazki w treści:** - Upload przez `POST /cms/assets.json` (multipart: `asset[file]=@plik`, `asset[site_id]=ID`) - Referencja: `/cms/assets/ID/view` — **NIE** `{{ asset 'nazwa' }}` (ten tag nie działa) - Unikaj URL-i `s3.eu-west-1.amazonaws.com/attachments.intum.net/public-files/` — wygasają (403) **Paginacja:** Gdy artykułów jest więcej niż `per_page`, automatycznie wyświetlana jest paginacja. Nawigacja między stronami przez parametr `?page=N`: - `/blog` → strona 1 - `/blog?page=2` → strona 2 - `/blog?page=3` → strona 3 **Klasy CSS paginacji:** | Klasa | Element | |-------|---------| | `cms-pagination` | Kontener `