Jet functions reference

Calling a function: three forms

A function can be called directly, or applied with a pipe. In a pipe the piped value becomes the first argument, and the rest go after a colon:

{{ 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" }} fails, because it calls repeat(3, "ab"). Write repeat("ab", 3).

Strings

{{ 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 counts bytes, not letters: len("héllo") is 6.

isset

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

isset is the one place where an undefined variable is not an error. Everywhere else {{ undefinedVar }} stops the render with 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 keys must be strings, and the argument count must be even.
• ints(from, to) excludes to, and from must be smaller than to. ints(3, 1) is a render error.
• A plain number is not rangeable: {{ range i := 3 }} fails. Use ints(0, 3).

Index and slice

list[from:to] takes the elements from from up to, but not including, to. Either bound can be left out, and both can be variables or expressions:

{{ 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] *}

Strings slice the same way, by bytes: {{ word := "hello" }}{{ word[1:4] }} prints ell. A string literal can't be sliced directly: "hello"[1:4] doesn't load.

Put spaces around - in an index: colors[len(colors) - 2:] works, colors[len(colors)-2:] doesn't load, because Jet reads -2 as a number.

json and writeJson

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

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

Both escape <, > and & as <… so the output is safe inside <script>, and the page's escaping leaves it alone. writeJson adds a trailing newline. json does not.

A tag can span several lines inside parentheses, as the json(map(…)) call above does: break a long argument list after a comma. A chain of method calls can't break before a .. Split a long chain into variables instead (see the worked example).

includeIfExists and exec

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

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

includeIfExists renders the template when it exists and returns a boolean that prints nothing. The optional second argument becomes . inside the included template.

exec("lib/featured", data) runs another layout file, throws away what it prints and gives you the value of its {{ return }}. Inside that file data is ., and note, nvs and the other page variables work. The path starts at _layouts/ and has no extension: exec("lib/featured") works, exec("lib/featured.html") fails with template /lib/featured.html could not be found. Use it for data (a list, a map, a number), and components for markup. Examples and path rules: Templates: exec and return.

dump

<pre>{{ dump() }}</pre>       {* context, variables in scope, globals, blocks *}
<pre>{{ dump("x") }}</pre>    {* one variable: "x:=5 // float64" *}

dump lists names. To see an object's type, value and methods, use trip2g's debug() instead.

Output, comments, whitespace

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

Call methods with parentheses. {{ note.Title }} without () prints a function address, not the title.

Variables: := and =

{{ count := 0 }}                 {* declare *}
{{ count = count + 1 }}          {* assign to an existing variable *}

• = on a variable that was never declared is a render error: could not assign "x" … variable "x" is uninitialised.
• := inside if or range declares a new variable that hides the outer one until {{ end }}. To change the outer value, use =:

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

Operators and values

• Number literals are floats: {{ 7 / 2 }} prints 3.5.
• + with a string concatenates: {{ "page " + 2 }} → page 2.
• "", 0, false and nil are false in if and ?:: {{ s ? s : "none" }}. An empty list is true, so test lists with len(list) > 0.
• || returns a boolean, not the first non-empty value. For a fallback value use trip2g's coalesce().

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

• With one variable, range gives the index, not the value. {{ range tag := note.Tags() }} yields 0, 1, 2…. Always write range i, value :=.
• {{ else }} renders when the collection is empty.
• Use _ for a variable you don't need: range _, tag := note.Tags().

block and yield

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

{{ yield card(title="Docs", url="/docs") }}
{{ yield card(url="/blog", title="Blog") }}

• Pass arguments by name. A positional argument, yield card("Docs"), is ignored, and the parameter keeps its default.
• Give every parameter a default. A block defined in the page itself also renders where it is defined, with no arguments. A parameter without a default then fails with missing name for block parameter.
• content is reserved. Don't use it as a parameter name.

A block can wrap content. The block outputs the caller's content with {{ 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 }}

A value after the call becomes . inside the block: {{ 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 makes a page inherit a base layout and fill its blocks:

{{ extends "base" }}

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

• Paths are relative to _layouts/, without .html.
• extends must be the first tag in the file, then any imports.
• How a base and a page fit together, with a tested example: Templates: layout inheritance.
• trip2g also imports blocks automatically when a page yields a block defined in another layout file. A template reached through include or extends doesn't get that and needs its own {{ import }}. See Template components: auto-import.

return and 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 gives exec its value. In a page rendered normally it stops nothing and prints nothing.
• try renders its body; if anything inside fails, the body's output is dropped and catch renders instead. Without catch a failed try prints nothing. It doesn't catch a layout that fails to load.

Worked examples: exec and return, try and catch.

Global functions

coalesce treats a missing map key, nil, "", an empty list and an empty map as empty. 0 and false count as values:

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

arg_type renders nothing. trip2g reads it at load time to describe a block's parameters (type and comment) to tools that list blocks:

{{ block hero(title="", image="") }}
  {{ arg_type("title", "string", "Heading text") }}
  {{ arg_type("image", "asset", "Background image file") }}
  …
{{ end }}

Variables in every custom layout

To put the default template's header, footer and styles around your own content:

<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() writes the settings object only on its first call, so calling it twice doesn't duplicate it. In the layout preview (/_system/renderlayout) all four defaultTemplate functions return "" and currentUser.IsAdmin() returns false.

Placeholders in layout source

@lid and @did in a layout file are replaced with the file's id before parsing (mesh/bar.html → mesh_bar / mesh-bar, my-theme/card.html → my_theme_card / my-theme-card), so block and CSS names stay unique. See yield_blocks and BEM naming.

Frontmatter: note.M()

Documented in Templates and Debugging Jet templates: GetString, GetInt, GetBool, GetStrings, Has, Debug. Details the code adds:

YAML dates without quotes (date: 2024-05-10) arrive as strings. Read them with GetString. CreatedAt() is the parsed created_at / created_on value when set.