Jakie zmienne Twig są dostępne w Nonli?

Szablony Smart Message pisze się w Twig 3. Ta strona zawiera wszystkie zmienne, funkcje i filtry obsługiwane przez Nonli w tym kontekście, wraz z ich typem, sytuacjami, w których mogą być niedostępne, i przetestowanym przykładem. Aby utworzyć szablon krok po kroku, zacznij od artykułu Jak utworzyć Smart Message.

1. Gdzie obowiązuje ten kontekst#

Ten sam kontekst jest dostępny w dwóch miejscach:

• Szablony Smart Message używane przez boty, przez przycisk z żarówką w edytorze posta i przez przycisk pierwszego komentarza. Mogą wypełniać wiadomość, tytuł, opis, komentarz, tytuł wideo, tekst alternatywny i tytuł kotwicy na TikToku.
• Wartości dynamiczne Smart Image, gdy tekst lub kolor w Smart Image korzysta z szablonu Smart Message jako źródła. W takim przypadku zmienna context ma wartość 'smart_image'. Zobacz Jak używać dynamicznych kolorów w Smart Image.

Dynamiczne parametry URL i dynamiczny paywall również korzystają z Twig, ale w znacznie węższym kontekście: ograniczony post (source, social_account, post_type, author, user_id, breaking_news, short_id), referer, funkcja isComment() oraz liczniki i percentyle. Nie istnieją tam organic, aliasy najwyższego poziomu ani opisane niżej funkcje Smart Message.

2. Zasady nazewnictwa i typów#

• Używaj pełnych ścieżek. Pisz organic.title lub post.social_account.type zamiast aliasu najwyższego poziomu. Aliasy są nadal obsługiwane w istniejących szablonach.
• Nazwy są w formacie snake_case i odpowiadają nazwom zapisanych pól: canonical_url, published_at, open_graph.
• Zwracaj uwagę na liczbę pojedynczą i mnogą. Ścieżki to organic.category, organic.tag, organic.author; aliasy to tags i authors. Błędna nazwa, taka jak categories, organic.categories, tag czy author, nie powoduje błędu: zwraca pustą wartość.
• Typy. string to tekst. list (lista) to ciąg wartości: sprawdzaj ją za pomocą in, odczytuj za pomocą |first lub |join(', ') i nigdy nie wyświetlaj jej bezpośrednio. object (obiekt) grupuje inne ścieżki. Dalej są liczby, wartości logiczne i daty. Daty to ciągi znaków w formacie ISO 8601 UTC, takie jak 2026-10-18T07:30:00.000Z; formatuj je za pomocą |date.
• Brak wartości. Wartość istnieje tylko wtedy, gdy dostarcza ją źródło. Zależy to od pochodzenia posta (artykuł, post ręczny, post bez linku), sieci społecznościowej, typu posta i metadanych, które scraper znalazł na stronie. Brakująca ścieżka organic daje pustą wartość; pusta lista jest traktowana jak brak wartości.

Użyj ??, aby zastąpić brakującą wartość lub null, oraz ?: lub |default(), aby zastąpić także pusty ciąg znaków:

Po filtrze używaj ?: lub |default(), nigdy ??: {{ x|upper ?? 'B' }} to błąd składni, a szablon zostanie odrzucony przy zapisie.

3. Zmienne najwyższego poziomu#

Te zmienne są zawsze zdefiniowane w Smart Message.

3.1. Starsze aliasy#

Gdy post pochodzi z artykułu, Nonli kopiuje też niektóre pola artykułu na najwyższy poziom. Te aliasy są zdefiniowane (mogą mieć wartość null), gdy tylko istnieje artykuł, i niezdefiniowane, gdy post go nie ma. Każdy z nich ma zalecaną pełną ścieżkę.

W prawdziwym artykule title i title1 często zawierają ten sam nagłówek, head_title zawiera dłuższy tytuł SEO, a meta_description często zaczyna się od leadu. Każda z tych wartości może być pusta, więc zawsze przewiduj wartość zastępczą.

Opcje „Meta custom …” w edytorze i w źródłach botów odpowiadają aliasom meta_custom_*. Są wypełniane tylko na stronach, dla których Nonli skonfigurowało dedykowaną regułę wyodrębniania. Artykuł ze strony spoza Twojej firmy udostępnia tylko swoje pola publiczne, dlatego brakuje dla niego organic.counter.view.

4. [object Object],: artykuł źródłowy#

organic istnieje, gdy post pochodzi z artykułu (bot, adres URL wklejony w edytorze, SDK, RSS). Post ręczny lub post bez linku nie ma artykułu: organic jest wtedy pustą listą, a każda ścieżka organic.* jest pusta.

4.1. Kategorie i ,[object Object]#

Nonli zapisuje wartość JSON-LD articleSection oraz inne sygnały kategorii ze strony w organic.category. Jest to lista, a nie tekst, i nie istnieje zmienna categories. Wartości są normalizowane: małe litery, usunięte znaki diakrytyczne, znaki interpunkcyjne zamienione na spacje. Na przykład Politique & Société, Économie i Sports > Rugby stają się politique societe, economie i sports rugby. Zawsze porównuj z wartościami faktycznie występującymi w Twoich artykułach.

1{%- set categories = organic.category ?? [] -%}
2{%- if 'politique' in categories -%}
3Politics
4{%- endif -%}

Pierwsza kategoria lub nic: {{ organic.category|default([])|first|default('') }}

Wszystkie kategorie: {{ organic.category|default([])|join(', ') }}

Surowa sekcja Open Graph, bez normalizacji, pozostaje dostępna jako {{ organic.meta.open_graph.article.section ?? '' }}.

5. [object Object],: post#

post opisuje tworzony lub edytowany post. Pola są wypełniane stopniowo: pole, które jest właśnie generowane, pozostaje puste podczas renderowania jego własnego szablonu.

Identyfikatory wewnętrzne i pola techniczne (identyfikatory użytkownika, firmy i marki, adres e-mail konta, adres URL webhooka, statusy, ślady błędów, surowe liczniki) są celowo wykluczone: nie stanowią stabilnego interfejsu publicznego i nie mogą pojawiać się w publikowanym tekście. post.user_id jest udokumentowany tylko dla parametrów URL.

6. Liczniki i percentyle#

Licznik jest wczytywany tylko wtedy, gdy szablon jawnie go wymienia, na przykład post.counter.click. Brakuje go, gdy metryka jeszcze nie istnieje, co zawsze dotyczy posta, który nie został opublikowany. Zawsze dodawaj wartość zastępczą: {{ post.counter.click ?? 0 }}.

Zmienna percentyla porównuje post z postami opublikowanymi przez to samo konto w danym okresie, z wyłączeniem newsów z ostatniej chwili. Jej nazwa składa się z percentile + percentyl (1 lub 2 cyfry) + metryka + czas trwania (1 lub 2 cyfry) + jednostka:

• metryki: Click, Engagement, Reach, VideoViews, Ctr, Overperforming, Monetization;
• jednostki: h godzina, d dzień, w tydzień, m miesiąc, y rok.

percentile50Click1d to mediana kliknięć z 1 dnia; percentile90Engagement7d to 90. percentyl zaangażowania z 7 dni. Bez danych wartość wynosi null i jest przechowywana w pamięci podręcznej przez 30 minut.

1{%- if (post.counter.engagement ?? 0) > (percentile50Engagement7d ?? 0) -%}TOP{%- else -%}NORMAL{%- endif -%}

7. Funkcje#

aiGenerated() rozpoznaje tylko nazwy najwyższego poziomu podane jako tekst. Przekaż 'description' lub samą wartość (organic.title), nigdy tekst 'organic.title', który zostanie zwrócony dosłownie. Nazwa, która nie istnieje, również jest zwracana dosłownie: w poście bez artykułu aiGenerated('description', …) zwraca słowo description. Zabezpiecz to warunkiem:

1{%- if organic -%}
2{{- aiGenerated('description', null, null, 40, '…', true) -}}
3{%- endif -%}

8. Filtry#

Standardowe filtry i operatory Twig (default, first, join, length, trim, replace, date, map, in, ??, ?:, ~) są opisane w dokumentacji Twig. Nonli dodaje lub zastępuje poniższe filtry. Wszystkie wyniki poniżej pochodzą z renderera Nonli.

Zasady, które pozwalają uniknąć błędów renderowania:

• extractMatch i pregReplace zwracają błąd, gdy wartość to null. Dodaj przed nimi |default(''): {{ meta_custom_publisher|default('')|extractMatch('/^(.+?[.!?…])(?=[[:space:]]|$)/u') }}.
• encode nie chroni &, = ani #: nie używaj go do budowania parametru z wartości, która może je zawierać.
• Zamiast sekwencji z ukośnikiem wstecznym używaj klas POSIX, takich jak [[:digit:]], [[:space:]] i [[:alpha:]]: nie psują się przy kopiowaniu i wklejaniu. Kopiuj szablony z bloku kodu, nigdy z wyrenderowanej wiadomości czatu lub e-maila, które mogą usuwać ukośniki wsteczne.

9. Przetestowane przepisy#

Każdy poniższy przepis został wyrenderowany silnikiem Twig Nonli na pełnych, częściowych i pustych danych testowych artykułów.

Nagłówek (H1 lub tytuł), a po nim opis meta, z krótkim linkiem tylko tam, gdzie jest potrzebny. W poście z linkiem na Facebooku zwraca nagłówek i opis; w poście ze zdjęciem na Facebooku dodaje ➡️ [SHORTLINK]; na Instagramie nigdy nie dodaje linku; bez artykułu zwraca pusty tekst.

1{%- set titre = title1 ?: title -%}
2{%- set desc = meta_description ?: description -%}
3{{- titre -}}
4{%- if desc -%}{{- '\n\n' ~ desc -}}{%- endif -%}
5{%- if post_type != 'link' and social_network not in ['instagram', 'tiktok', 'pinterest'] and not hasFirstCommentShortlink() and hasLink() -%}
6{{- '\n\n' ~ shortlink_prefix -}}[SHORTLINK]
7{%- endif -%}

Pierwsze zdanie opisu, w razie jego braku opis, a następnie tytuł.

1{%- set source = meta_description ?: description ?: '' -%}
2{{- source|extractMatch('/^(.+?[.!?…])(?=[[:space:]]|$)/u') ?: source ?: title -}}

Pierwsze zdanie niestandardowego pola wydawcy, w razie jego braku tekst alternatywny obrazu, a następnie tytuł.

1{{- meta_custom_publisher|default('')|extractMatch('/^(.+?[.!?…])(?=[[:space:]]|$)/u') ?: organic.image_alt|default('') ?: title -}}

Tekst zależny od sieci i typu posta.

1{%- if social_network == 'instagram' -%}
2{{- title -}}
3{%- elseif post_type == 'link' -%}
4{{- description ?: title -}}
5{%- else -%}
6{{- title -}}
7{%- endif -%}

Kolor Smart Image zależny od kategorii. Zwraca #E50032 dla polityki, #16A34A dla sportu i #6F819D w pozostałych przypadkach.

1{%- set categories = organic.category ?? [] -%}
2{%- if 'politique' in categories -%}#E50032
3{%- elseif 'sport' in categories -%}#16A34A
4{%- else -%}#6F819D
5{%- endif -%}

Wartości śledzące z konta docelowego.

1utm_source={{ post.social_account.type|default('social') }}&utm_campaign={{ post.social_account.slug|default('')|encode }}

Data publikacji w strefie czasowej redakcji. 2026-10-18T07:30:00.000Z zmienia się w 18/10/2026 09:30. Bez daty publikacji date wyświetliłby bieżącą datę, dlatego warunek pozostawia wtedy pusty tekst.

1{%- if organic.published_at|default(null) -%}
2{{- organic.published_at|date('d/m/Y H:i', 'Europe/Paris') -}}
3{%- endif -%}

Hashtagi z tagów. ['budget', 'impots'] zmienia się w #Budget #Impots.

1{{ tags|default([])|map(t => '#' ~ t|camel)|join(' ') }}

Krótkie słowa i liczby trzymane razem z następnym słowem (w tytułach Smart Image, które nigdy nie łamią wiersza na spacji nierozdzielającej). W La finale se jouera à guichets fermés słowa La, se i à pozostają połączone z następnym słowem, a 16 septembre czy 3 000 euros nie są rozdzielane. Zmiana dotyczy tylko nowo generowanych obrazów.

1{%- set titre = organic.title ?? title -%}
2{{- titre|pregReplace("/(?<=^|[[:space:]])([[:alpha:]]{1,2}|[[:digit:]]+)[[:space:]]+/u", "$1\xC2\xA0") -}}

Twig zamienia \xC2\xA0 na spację nierozdzielającą; $1 zachowuje dopasowane krótkie słowo lub liczbę.

10. Inteligentne pola automatyczne i uruchamiane kliknięciem#

Każda marka ma dwa ustawienia: Automatic configuration of smart fields (automatyczna konfiguracja inteligentnych pól) i Smart field configuration at the click of the button (konfiguracja inteligentnych pól po kliknięciu przycisku). Przycisk w edytorze korzysta z konfiguracji uruchamianej kliknięciem, a do automatycznej wraca tylko wtedy, gdy konfiguracja uruchamiana kliknięciem nie istnieje. Pole ustawione na publiczny szablon Empty (pusty) jest czyszczone po kliknięciu przycisku, ponieważ edytor wpisuje wygenerowaną wartość z powrotem do pola.

Boty nie korzystają z tych ustawień marki. Każdy bot ma własne źródła, takie jak Message's source (źródło wiadomości) i Description's source (źródło opisu), które wskazują wbudowaną wartość (Title, Description i tak dalej) lub szablon Smart Message.

11. Rozwiązywanie problemów#

11.1. Mój bot sprawdza źródło, ale nie tworzy żadnego posta#

Aktywny bot może znaleźć artykuł, a mimo to nie utworzyć posta, gdy jego Smart Message renderuje pustą wiadomość. Dzieje się tak na przykład wtedy, gdy szablon odczytuje pole opcjonalne, takie jak meta_custom_publisher, a artykuł go nie ma. Nonli odfiltrowuje wtedy kandydata przed jakąkolwiek publikacją: wiadomość pusta lub mająca pięć znaków lub mniej po usunięciu krótkiego linku zostaje odrzucona, podobnie jak post z linkiem z pustym tytułem. Sprawdzenie pustej wiadomości nie dotyczy botów ustawionych na No message (bez wiadomości) ani Pinteresta; sprawdzenie pustego tytułu dotyczy każdego bota.

Jest to coś innego niż post, który został utworzony, a następnie nie powiódł się w sieci: taki post jest widoczny w Posts ze statusem błędu. Zobacz Dlaczego bot nie opublikował tego artykułu?, aby najpierw ustalić, na którym etapie wystąpił problem.

1. Porównaj. Zidentyfikuj dokładnie, o którego bota chodzi. Porównaj kilka wiadomości, które wcześniej wygenerował poprawnie, z metadanymi odpowiednich artykułów i sprawdź, co zmieniło się w jego konfiguracji. Sama nazwa szablonu ani obecny kod HTML strony nie dowodzą, co wcześniej działało. Wyrenderuj obecny szablon na reprezentatywnym artykule spełniającym warunki i sprawdź, czy zmiennej brakuje, czy istnieje, ale jest pusta.

2. Napraw. Najlepiej przywróć poprzednie źródło wiadomości, jeśli dawało zamierzone sformułowanie, albo dodaj wartość zastępczą dopasowaną do typu zmiennej:

   twigCopy

   1{{- meta_custom_publisher ?: title -}}

   Jeśli tytuł artykułu odpowiada zamierzonemu sformułowaniu, otwórz bota, ustaw Message's source na Title, a następnie kliknij Save. Zmienia to generowany tekst.

   

   Fragment ustawień bota: Message's source ustawione na Title, przed kliknięciem Save.

3. Zakres. Zmiana źródła bota dotyczy tylko przyszłych postów tego bota. Edycja udostępnionego szablonu Smart Message wpływa na każdego bota i każde pole, które z niego korzysta. Istniejące posty nigdy nie są przepisywane.

4. Sprawdź. Poczekaj na następne zwykłe sprawdzenie źródła i obejrzyj artykuły, które nadal spełniają warunki. Starsze artykuły nie są automatycznie nadrabiane, a post ręczny nie dowodzi, że bot znów działa.

11.2. Krótki znacznik, lead i pierwsze zdanie to różne wartości#

Krótki znacznik redakcyjny (nazywany czasem nadtytułem), pełny lead i pierwsze zdanie tekstu to trzy różne rzeczy. Nonli nie ma dedykowanej zmiennej dla krótkiego znacznika: reguła właściwa dla danej strony może zapisywać go w polu meta_custom_*, a niektóre artykuły po prostu go nie mają. Nie zastępuj brakującego znacznika całym leadem. Wyświetlaj znacznik tylko wtedy, gdy istnieje:

1{%- set marker = meta_custom_instagram|default('')|trim -%}
2{%- if marker -%}{{- marker ~ ' | ' -}}{%- endif -%}
3{{- title -}}

Ze znacznikiem wynik to EXCLUSIVE | Budget 2027: what changes; bez niego tylko tytuł. meta_custom_instagram jest tu tylko przykładem: użyj pola, które faktycznie wypełnia reguła Twojej strony.

meta_description (natywny opis meta), meta_custom_publisher (pole niestandardowe) i description (opis wybrany przez Nonli) to odrębne dane wejściowe. Poprawienie jednego z nich nie wpływa na szablon, który odczytuje inne. Aktualizacja zebranego pola nie zmienia wybranego źródła bota, tekstu Smart Image ani już wygenerowanych postów.

11.3. Pełny zebrany opis czy pierwsze zdanie leadu#

Gdy bot tworzy wiadomość, często myli się cztery wartości:

• Zebrany opis (description, organic.description): opis artykułu zebrany przez Nonli, używany w całości, bez dzielenia na zdania. Nonli pobiera go najpierw z danych strukturalnych artykułu, a w razie ich braku z Open Graph, następnie z Twitter Card, a na końcu z natywnego opisu meta. Gdy pochodzi z tych znaczników, zachowuje ich przycięcie do 500 znaków. Opis elementu RSS (meta_custom_rss_description) nigdy nie jest używany jako zebrany opis.
• Metadane natywne (meta_description, og_description, twitter_description): opisy zadeklarowane w znacznikach meta strony. Nonli przycina każdy z nich do 500 znaków podczas zbierania. Ten limit dotyczy tylko tych trzech pól: zebrany opis pobrany z danych strukturalnych nie jest przycinany.
• Pierwsze zdanie: szablon taki jak Template: [public] Message from first standfirst sentence celowo zachowuje jedno zdanie i obsługuje link za pomocą własnego znacznika [SHORTLINK].
• Krótki znacznik: pole opcjonalne opisane w poprzedniej sekcji, którego niektóre artykuły nie mają.

Ani nazwa szablonu, ani wybrane źródło nie dowodzą, że zebrany opis to Twój pełny lead. Aby publikować pełny zebrany opis zamiast jego pierwszego zdania:

1. Sprawdź, co zostało zebrane. Na kilku reprezentatywnych artykułach porównaj description z pełnym leadem, którego oczekujesz. Jeśli go brakuje, jest przycięty lub zawiera treść artykułu zamiast leadu, najpierw poproś wsparcie o poprawienie i sprawdzenie zbierania danych. Zmiana źródła bota nie odzyska tekstu, który nie został zebrany.
2. Zmień źródło. Otwórz bota, ustaw Message's source na Description, a następnie kliknij Save. Nie myl tego z Description's source, które wypełnia pole opisu posta, a nie jego tekst.
3. Sprawdź następną wiadomość. Obejrzyj następny post wygenerowany przez bota: pełny tekst, miejsce linku i limit tekstu każdej sieci docelowej. Pełny opis może być długi, a jego wybór nie gwarantuje, że każda sieć przyjmie cały tekst. Nonli nadal obsługuje krótki link: w poście bez natywnego linku dodaje krótki link bezpośrednio po wygenerowanym tekście, przed ewentualnym sufiksem bota i hashtagami, chyba że pierwszy komentarz już go zawiera. Posty z linkiem i udostępnienia nie dostają dołączonego krótkiego linku, z wyjątkiem postów z linkiem w X i na Mastodonie, gdzie jest on dodawany na samym końcu. Wiadomości na Instagramie i TikToku nie dostają krótkiego linku. Szablon pierwszego zdania może skracać tekst lub umieszczać link w różnych miejscach zależnie od sieci, więc nie oczekuj takiego samego wyniku.
4. Zakres. Zmiana dotyczy tylko postów generowanych przez tego bota od teraz. Istniejące posty, inne boty i udostępnione szablony Smart Message pozostają bez zmian, a żaden starszy artykuł nie jest importowany ani publikowany ponownie.

11.4. Apostrofy psują mój szablon#

W ciągu Twig w pojedynczych cudzysłowach apostrof kończy ciąg. Ten szablon zostanie odrzucony przy zapisie z błędem takim jak „Invalid template syntax at line 1”:

1{{ gpt('Summarize the article's main point') }}

Poprzedź apostrof znakiem ucieczki, użyj apostrofu typograficznego lub podwójnych cudzysłowów:

1{{ gpt('Summarize the article\'s main point') }}
2{{ gpt('Summarize the article’s main point') }}
3{{ gpt("Summarize the article's main point") }}

Podany numer wiersza to wiersz szablonu, który zawiera błąd.

11.5. Zmienna pozostaje pusta#

• Sprawdź dokładną pisownię: organic.category, a nie categories; tags, a nie tag.
• Sprawdź, czy post ma artykuł: organic jest puste w przypadku postów ręcznych i postów bez linku, a aliasy są wtedy niezdefiniowane.
• Wyświetlaj listę za pomocą |join(', ') lub sprawdzaj ją za pomocą in.
• Porównuj kategorie z ich znormalizowaną postacią (politique societe, a nie Politique & Société).
• Zabezpieczaj liczniki za pomocą ?? 0: przed publikacją ich brakuje.

11.6. Czy szablon może dodać współpracowników na Instagramie?#

Nie. Szablony wypełniają tylko pola tekstowe, a airtable() zwraca tekst: może wpisać oznaczenie z @, ale nie utworzy współpracy. Dodaj współpracowników w edytorze posta za pomocą Collaborators (współpracownicy) lub pola API collaborator[] (slug, type) w POST lub PUT /v2.1/posts/bulk. Meta akceptuje maksymalnie 3 współpracowników; zobacz Jak utworzyć współpracę na Instagramie z Nonli.