Справочник функций Jet

Три способа вызвать функцию

Функцию можно вызвать напрямую или через пайп. В пайпе значение слева становится первым аргументом, остальные пишутся после двоеточия:

{{ upper("hello") }}                {* → HELLO *}
{{ "hello" | upper }}               {* → HELLO *}
{{ "a-b-c" | replace: "-", " ", -1 }}
{* replace("a-b-c", "-", " ", -1) → a b c *}
{{ "Hello" | hasPrefix: "He" }}     {* → true *}
{{ "a-b" | replace: "-", " ", -1 | upper }}
{* pipes chain → A B *}

{{ 3 | repeat: "ab" }} падает: это вызов repeat(3, "ab"). Пишите repeat("ab", 3).

Строки

{{ lower("ABC") }}                  {* → abc *}
{{ trimSpace("  x  ") }}            {* → x *}
{{ repeat("ab", 3) }}               {* → ababab *}
{{ replace("aaa", "a", "b", 2) }}   {* → bba *}

{{ range i, part := split("a,b,c", ",") }}
  [{{ part }}]
{{ end }}
{* → [a] [b] [c] *}

{{ if hasSuffix(note.Permalink(), "/faq") }}
  <a href="/faq/contact">Ask a question</a>
{{ end }}

len считает байты, а не буквы: len("héllo") — это 6, len("привет") — 12.

isset

{{ m := map("a", 1) }}
{{ isset(m["a"]) }}        {* → true *}
{{ isset(m["z"]) }}        {* → false: missing map key *}
{{ isset(undefinedVar) }}  {* → false, no error *}

isset — единственное место, где неопределённая переменная не ошибка. В остальных случаях {{ undefinedVar }} останавливает рендер с identifier "undefinedVar" not available.

map, slice, ints

{{ links := map("docs", "/docs", "blog", "/blog") }}
{{ links["blog"] }}  {{ links.blog }}   {* both → /blog *}

{{ range i, n := ints(1, 4) }}
  {{ n }}
{{ end }}
{* → 1 2 3 *}

• Ключи map — строки, аргументов должно быть чётное число.
• ints(from, to) не включает to, и from должен быть меньше to. ints(3, 1) — ошибка рендера.
• По числу range не ходит: {{ range i := 3 }} падает. Пишите ints(0, 3).

Индекс и срез

list[from:to] берёт элементы с from до to, не включая to. Любую границу можно опустить, и обе могут быть переменными или выражениями:

{{ colors := slice("red", "green", "blue", "black") }}
{{ colors[1] }}             {* → green *}
{{ colors[1:3] }}           {* → [green blue] *}

{{ from := 1 }}
{{ to := len(colors) - 1 }}
{{ colors[from:to] }}       {* → [green blue] *}
{{ colors[from:] }}         {* → [green blue black] *}
{{ colors[:to] }}           {* → [red green blue] *}

Строки режутся так же, по байтам: {{ word := "hello" }}{{ word[1:4] }} выведет ell. Строковый литерал напрямую не режется: "hello"[1:4] не загрузится.

Ставьте пробелы вокруг - в индексе: colors[len(colors) - 2:] работает, а colors[len(colors)-2:] не загрузится — Jet прочитает -2 как число.

json и writeJson

<script>
  window.pageData = {{ json(map(
    "title", note.Title(),
    "tags", note.Tags()
  )) }};
</script>

<script type="application/json" id="data">
  {{ writeJson(note.M().Raw()) }}
</script>

Обе экранируют <, > и & как <…, поэтому результат безопасен внутри <script>, и экранирование страницы его не трогает. writeJson добавляет перевод строки в конце, json — нет.

Тег может занимать несколько строк внутри скобок, как вызов json(map(…)) выше: длинный список аргументов переносите после запятой. Цепочку методов перед . перенести нельзя. Длинную цепочку разбейте на переменные (см. пример).

includeIfExists и exec

{{ includeIfExists("partials/banner") }}

{{ if !includeIfExists("partials/sidebar", note) }}
  <p>No sidebar</p>
{{ end }}

includeIfExists рендерит шаблон, если он существует, и возвращает булево значение, которое ничего не печатает. Второй аргумент, если он есть, становится . внутри вставленного шаблона.

exec("lib/featured", данные) выполняет другой файл шаблона, отбрасывает всё, что он напечатал, и возвращает значение его {{ return }}. Внутри файла данные доступны как ., а note, nvs и другие переменные страницы работают. Путь отсчитывается от _layouts/ и пишется без расширения: exec("lib/featured") работает, exec("lib/featured.html") падает с template /lib/featured.html could not be found. exec — для данных (список, словарь, число), для разметки — компоненты. Примеры и правила путей — в Синтаксисе Jet: exec и return.

dump

<pre>{{ dump() }}</pre>       {* контекст, переменные, глобальные, блоки *}
<pre>{{ dump("x") }}</pre>    {* одна переменная: "x:=5 // float64" *}

dump показывает имена. Чтобы увидеть тип, значение и методы объекта, используйте debug() из trip2g.

Вывод, комментарии, пробелы

{{ note.Title() }}                  {* print an expression *}
{* a comment, never rendered *}
<li>   {{- note.Title() -}}   </li>
{* {{- and -}} trim whitespace on that side *}

Методы вызывайте со скобками. {{ note.Title }} без () выведет адрес функции, а не заголовок.

Переменные: := и =

{{ count := 0 }}                 {* объявить *}
{{ count = count + 1 }}          {* присвоить существующей *}

• = для переменной, которую не объявили, — ошибка рендера: could not assign "x" … variable "x" is uninitialised.
• := внутри if или range объявляет новую переменную, которая до {{ end }} закрывает внешнюю. Чтобы изменить внешнюю, пишите =:

{{ x := 1 }}{{ if true }}{{ x := 2 }}{{ end }}{{ x }}   {* → 1 *}
{{ x := 1 }}{{ if true }}{{ x = 2 }}{{ end }}{{ x }}    {* → 2 *}

Операторы и значения

• Числовые литералы — дробные: {{ 7 / 2 }} выводит 3.5.
• + со строкой склеивает: {{ "страница " + 2 }} → страница 2.
• "", 0, false и nil в if и ?: — ложь: {{ s ? s : "нет" }}. Пустой список — истина, поэтому списки проверяйте через len(list) > 0.
• || возвращает булево значение, а не первое непустое. Для значения по умолчанию есть coalesce() из trip2g.

if

{{ if n == 1 }}
  one
{{ else if n == 2 }}
  two
{{ else }}
  many
{{ end }}

{{ if v, ok := links["blog"]; ok }}
  <a href="{{ v }}">Blog</a>
{{ end }}

range

{{ range i, tag := note.Tags() }}
  <span>{{ tag }}</span>
{{ end }}

{{ range key, value := links }}
  {{ key }} → {{ value }}
{{ end }}

{{ range i, post := posts }}
  <a href="{{ post.Permalink() }}">{{ post.Title() }}</a>
{{ else }}
  <p>Nothing here.</p>
{{ end }}

• С одной переменной range отдаёт индекс, а не значение. {{ range tag := note.Tags() }} даст 0, 1, 2…. Всегда пишите range i, value :=.
• {{ else }} выводится, если коллекция пуста.
• Ненужную переменную назовите _: range _, tag := note.Tags().

block и yield

{{ block card(title="", url="") }}
  <a class="card" href="{{ url }}">{{ title }}</a>
{{ end }}

{{ yield card(title="Документация", url="/docs") }}
{{ yield card(url="/blog", title="Блог") }}

• Аргументы передаются по имени. Позиционный аргумент — yield card("Документация") — игнорируется, параметр остаётся со значением по умолчанию.
• Задавайте значение по умолчанию каждому параметру. Блок, объявленный в самой странице, ещё и выводится там, где объявлен, без аргументов. Параметр без значения по умолчанию тогда падает с missing name for block parameter.
• content — зарезервированное слово, параметр так называть нельзя.

Блок может оборачивать содержимое. Блок выводит то, что передал вызывающий, через {{ yield content }}:

{{ block panel(title="") }}
  <section>
    <h2>{{ title }}</h2>
    {{ yield content }}
  </section>
{{ end }}

{{ yield panel(title="Related") content }}
  <p>Anything here becomes the panel body.</p>
{{ end }}

Значение после вызова становится . внутри блока: {{ yield menu() items }}.

import, include, extends

{{ import "blocks" }}
{* load the blocks of _layouts/blocks.html, render nothing *}

{{ include "partials/footer" }}
{* render another template here *}

{{ include "partials/card" note }}
{* … with `note` as `.` inside it *}

extends наследует базовый шаблон и заполняет его блоки:

{{ extends "base" }}

{{ block main() }}
  <p>This replaces the main block of base.html</p>
{{ end }}

• Пути — относительно _layouts/, без .html.
• extends должен быть первым тегом файла, за ним — import, если они есть.
• Как база и страница складываются вместе, с проверенным примером, — в Шаблонах: наследование.
• Кроме того, trip2g сам импортирует блоки, когда страница вызывает блок из другого файла шаблона. Шаблон, до которого дошли через include или extends, этого не получает и импортирует компоненты сам через {{ import }}. См. Компоненты шаблонов: автоимпорт.

return и try / catch

{* lib/featured.html: the value exec gets *}
{{ return nvs.ByGlob(. + "/*.md").Public().Limit(3).All() }}

{{ try }}
  {{ stats := exec("lib/stats", "blog") }}
  <p>{{ stats.count }} posts</p>
{{ catch err }}
  {{ if currentUser.IsAdmin() }}
    <p>{{ err.Error() }}</p>
  {{ end }}
{{ end }}

• return отдаёт значение exec. В обычной странице он ничего не останавливает и ничего не выводит.
• try рендерит своё тело; если внутри что-то упало, вывод тела выбрасывается и рендерится catch. Без catch упавший try ничего не выводит. Шаблон, который не загрузился, try не ловит.

Примеры — в exec и return и try / catch.

Глобальные функции

coalesce считает пустыми отсутствующий ключ карты, nil, "", пустой список и пустую карту. 0 и false — значения:

{{ videos := map("en", "intro-en.mp4") }}
{{ coalesce(videos[note.Lang()], videos["en"]) }}
{{ coalesce(
  note.M().GetString("subtitle", ""),
  note.Description(),
  note.Title()
) }}

arg_type ничего не выводит. trip2g читает его при загрузке и сообщает инструментам, которые показывают список блоков, тип и описание параметра:

{{ block hero(title="", image="") }}
  {{ arg_type("title", "string", "Текст заголовка") }}
  {{ arg_type("image", "asset", "Фоновая картинка") }}
  …
{{ end }}

Переменные в каждом своём шаблоне

Чтобы обернуть свой контент в шапку, подвал и стили дефолтного шаблона:

<head>
  <title>{{ title }}</title>
  {{ defaultTemplate.Styles() }}
  {{ defaultTemplate.UserSpaceScripts() }}
</head>
<body>
  {{ defaultTemplate.Header() }}
  <main>{{ note.HTMLString() }}</main>
  {{ defaultTemplate.Footer() }}
  {{ if currentUser.IsAdmin() }}
    <a href="/admin">Admin</a>
  {{ end }}
</body>

UserSpaceScripts() пишет объект настроек только при первом вызове, второй вызов его не дублирует. В превью шаблона (/_system/renderlayout) все четыре функции defaultTemplate возвращают "", а currentUser.IsAdmin() — false.

Плейсхолдеры в исходнике шаблона

@lid и @did в файле шаблона до разбора заменяются на id файла (mesh/bar.html → mesh_bar / mesh-bar, my-theme/card.html → my_theme_card / my-theme-card), чтобы имена блоков и CSS-классов не пересекались. См. yield_blocks и BEM-именование.

Методы note, note.M(), nvs и выборок

Полный список — в Шаблонах: API: методы заметки (Title, HTMLString, Tags, Lang, LangAlternativesList, HasCodeLanguage…), доступ к frontmatter (GetString, GetInt, GetBool, GetStrings…), nvs (ByPath, ByPermalink, ByWikilink, BackLinks…), выборки (ByGlob, SortBy, SortByMeta, Public, Limit…) и PartialRenderer. Там же — что выборка возвращает без фильтров и как ведёт себя сортировка. FormSpecJSON() описан в Формах, debug() и note.M().Debug() — в Отладке.

PermalinkEncoded() — это Permalink(), в котором каждый сегмент пути закодирован процентами: /привет мир → /%D0%BF…%20%D0%BC…. Это кодирование URL, а не HTML-экранирование. Раз вывод экранируется, Permalink() тоже безопасен в href. PermalinkEncoded() нужен, когда в пути есть не-ASCII символы или пробелы и нужен строго закодированный адрес: в sitemap, ленте или ссылке, которую читает другая программа.

Языковой переключатель:

{{ range i, alt := note.LangAlternativesList() }}
  <a href="{{ alt.PermalinkEncoded() }}" hreflang="{{ alt.Lang() }}">
    {{ alt.LangName() }}
  </a>
{{ end }}

Две ловушки стоит знать заранее:

• Поиск, который ничего не нашёл (ByPath, ByPermalink, ByWikilink, First() / Last() выборки, LangAlternative(), Section(), FirstList()), возвращает nil. Работают и {{ if x }}, и {{ if x == nil }}, а x.Title() на нём останавливает рендер. Удобнее всего объявить и проверить в одном теге, как в примере ниже.
• nvs.ByGlob(...) без .Public() возвращает и платные, и закрытые, и системные (_) заметки.

{{ if about := nvs.ByPermalink("/about"); about }}
  <a href="{{ about.PermalinkEncoded() }}">{{ about.Title() }}</a>
{{ end }}