Origami templates

Transform data and files to text

Origami templates let you convert turn data into HTML or other text documents through expressions embedded in text.

  • These templates work directly on a wide range of data types, including file system folders or network resources.
  • Templates have a very small number of fundamental features that can be combined to address a wide range of scenarios.
  • You can extend what’s possible in a template expression in JavaScript with essentially no configuration.

You can use Origami with other template systems, but the small degree of integration code required is currently beyond the scope of this documentation.

Template files

An Origami template file is an Origami file (a text file with a .ori extension) defining an Origami expressions that either evaluates to a text string or to a function that returns text.

The most common type of Origami template is a file that defines a template literal using an = equals sign and backtick characters. Inside the backticks, placeholders marked with {{and}} curly braces contain additional Origami expressions whose results are included in the final text:

$ cat greet.ori
=`Hello, {{ _/name }}.`

You can evaluate a template in the context of data, such as an object defined in a data file.

$ cat alice.yaml
name: Alice Andrews
$ ori "greet.ori(alice.yaml)"
Hello, Alice Andrews.

Reference input

When you invoke a template as a function, you can refer to the template’s input using an underscore (_).

$ cat heading.ori
=`<h1>{{ _ }}</h1>
`$ ori "heading.ori('About Us')"
<h1>About Us</h1>

Reference local files

You can reference local files in Origami expressions. Depending on the situation, you may not have to pass any arguments to the template — it may be able obtain whatever it needs from its file system context.

$ cat fileRef.ori
=`This project is {{ copyright.txt }}.`
$ cat copyright.txt
©2024 Alice Andrews
$ ori "fileRef.ori()"
This project is ©2024 Alice Andrews.

In cases like this, where the template does not require any argument, you can avoid the need to quote parentheses by invoking the template using slash syntax:

$ ori fileRef.ori/
This project is ©2024 Alice Andrews.

Reference trees

If a template expression results in a tree such as a folder or hierarchical data, Origami will collect the deep values of that tree, convert them to strings, then concatenate them.

$ cat greetings.yaml
Alice: Hello, Alice.
Bob: Hello, Bob.
Carol: Hello, Carol.

$ cat flatten.ori
`Here are the text strings in the greetings tree:
{{ @tree greetings.yaml }}
`
$ ori flatten.ori/
Here are the text strings in the greetings tree:
Hello, Alice.Hello, Bob.Hello, Carol.

This feature forms the basis for more complex ones (like maps, below), but one basic use for it is to inline a set of files. For example, you might create a folder that contains a collection of HTML fragments as separate files:

$ ls fragments
a.html b.html c.html
$ cat fragments/a.html
<p>A</p>

You can then reference that fragments folder in a template to concatenate all those HTML fragments into the output:

$ cat concat.ori
=`Here are the fragments concatenated together:
{{ fragments }}`
$ ori concat.ori/
Here are the fragments concatenated together:
<p>A</p>
<p>B</p>
<p>C</p>

Use template expressions in any file type

It may be useful to embed Origami expressions inside other kinds of files, such as .html files. You can evaluate such expressions with the built-in @inline function.

For example, you can use this to inline resources such as stylesheets.

$ cat inline.html
<html>
  <head>
    <style>
      {{ inline.css }}
    </style>
  </head>
  <body>
    This text will be red.
  </body>
</html>
$ cat inline.css
body { color: red }
$ ori @inline inline.html
<html>
  <head>
    <style>
      body { color: red }

    </style>
  </head>
  <body>
    This text will be red.
  </body>
</html>

Here, the inline.html file is acting as an Origami template, but keeps the .html extension so that it can be otherwise treated as an HTML file.

If the input document contains any front matter (see below), @inline preserves this in the output.

Traverse into data

Inside a template, you can use slash-separated paths to traverse into data.

$ cat teamData.yaml
- name: Alice
  image: van.jpg
  location: Honolulu
  bio: After working as a manager for numerous startups over the years, I
    decided to take the plunge and start a business of my own.
…
$ cat teamLead.ori
`The leader of our team is {{ teamData.yaml/0/name }}.`
$ ori teamLead.ori/
The leader of our team is Alice.

Reference network resources

Since https and http URLs are valid Origami expressions, you can incorporate network content into a template’s output.

$ cat net.ori
=`This content came from weborigami.org:
{{ https://weborigami.org/samples/templates/net.txt }}
`
$ ori net.ori/
This content came from weborigami.org:
Hello, Origami!

This includes being able to traverse into data from the network. A teamData.yaml file posted on the network can be referenced as an expression and then further traversed:

$ cat netData.ori
=`Bob lives in {{ (https://weborigami.org/samples/templates/teamData.yaml)/1/location }}.
`
$ ori netData.ori/
Bob lives in Los Angeles.

You can also obtain a data file from the network, treat it as a tree, and map the tree to text. This allows you to directly process network data into text in a template.

Conditions

Use the built-in @if function to include text based on some condition.

The first argument to @if is a condition that is evaluated. If the result is truthy (not false, null, or undefined), the second argument to @if is included in the template’s text output. If the result is falsy and a third argument is provided, that third argument will be included in the output.

$ cat condition.ori
=@if(_/rating, `Rating: {{ _/rating }}`, `Not yet rated`)

$ ori “condition.ori({ rating: 3 })”
Rating: 3
$ ori “condition.ori({})”
Not yet rated

Call your own JavaScript functions

Your template expressions can call any JavaScript in scope via the base of the JavaScript file name.

For example, if you have a file named uppercase.js in the same directory as the template, a template expression can reference that module’s default export as uppercase:

$ cat uppercase.js
export default (x) => x.toString().toUpperCase();

$ cat callJs.ori
`Hello, {{ uppercase.js("world") }}!`
$ ori callJs.ori/
Hello, WORLD!

If the function you invoke is asynchronous, its result will be awaited before being incorporated into the text output.

Call another template as a function

One template can invoke another as a function.

We can define a template stars.ori as a component that displays a star rating:

$ cat stars.ori
=`<span class="stars">{{ @repeat(_, "★") }}</span>`

This template repeats a ★ star character for the number of times defined in in the input value. For example, you can directly invoke and test this template, passing in a value of 3:

$ ori "stars.ori(3)"
<span class="stars">★★★</span>

This stars.ori template defines a function that you can invoke inside expressions in other templates:

$ cat review.ori
=`I give it {{ stars.ori(5) }}`
$ ori review.ori/
I give it <span class="stars">★★★★★</span>

This technique can let you define components in plain HTML and CSS.

Wrap one template with another

Another application of invoking a template as a function is to wrap the output of one template inside another. For example, you can create an overall page template for a site called page.ori:

$ cat page.ori
=`<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>My Site</title>
  </head>
  <body>
{{ _ }}
  </body>
</html>
`

A template for a specific type of page, like a contact.ori template for a Contact Us page, can invoke page.ori as a function:

$ cat contact.ori
=page.ori(`
    <h1>Contact Us</h1>
    <p>We'd love to hear from you!</p>
`)

Evaluating the contact page template passes its HTML fragment to the overall site page template:

$ ori contact.ori/
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>My Site</title>
  </head>
  <body>

    <h1>Contact Us</h1>
    <p>We'd love to hear from you!</p>

  </body>
</html>

Processing input front matter

An input document can define front matter.

Both a template’s input document and the template itself can contain front matter in YAML or JSON format. The front matter is delineated with both a leading and trailing line of three hyphens (---), like so:

Example: a blog post can be stored as a markdown file with front matter that defines a title property.

$ cat posts/post1.html
---
title: The First Post
---

Here's the text of my first post.

And a template can then reference this title property. Here the template uses the @or function to provide a default title if the input document has no title.

$ can blogPost.ori
=`<html>
  <head>
    <title>{{ @or(_/title, "A blog post") }}</title>
  </head>
  <body>
    {{ _/@text }}
  </body>
</html>
`

Applying the template the blog post includes the document’s title property as desired:

$ ori blogPost.ori posts/post1.html
<html>
  <head>
    <title>The First Post</title>
  </head>
  <body>
    
Here's the text of my first post.

  </body>
</html>

Map trees to text

It’s common to have a template generate some fragment of text for each value in a tree: an array, a set, a folder, etc. You can handle such cases in Origami templates by calling the built-in @map function to map a tree’s values to text.

$ cat teamData.yaml
- name: Alice
  image: van.jpg
  location: Honolulu
  bio: After working as a manager for numerous startups over the years, I
    decided to take the plunge and start a business of my own.
- name: Bob
  image: kingfisher.jpg
  location: Los Angeles
  bio: Having been an art student for 11 years, I constantly explore various
    disciplines to incorporate artistic pursuits into product design studies.
- name: Carol
  image: venice.jpg
  location: Venice
  bio: I open the line of communication between clients, customers, and
    businesses to get projects done.

$ cat teamList.ori
=`<ul>
{{ @map(teamData.yaml, =`
  <li>{{ _/name }}</li>
`) }}
</ul>
`
$ ori teamList.ori/
<ul>
  <li>Alice</li>
  <li>Bob</li>
  <li>Carol</li>
</ul>

The teamList.ori file defines an outer template that includes an <ul> tag. Inside that, a substitution calling @map appears, which maps the array of people in teamData.yaml to a set of HTML fragments using a nested template with an <li> tag.

How maps work

Origami templates don’t treat such maps specially. Rather, the @map function is returning a tree of HTML fragments that are concatenated into the text output.

In the above example, the @map function maps an array of people to HTML fragments. The transformation can be visualized like this:

g 0 ->0 0 1 ->1 1 2 ->2 2 0/name Alice 0->0/name name 1/name Bob 1->1/name name 2/name Carol 2->2/name name
g 0 <li>Alice</li> ->0 0 1 <li>Bob</li> ->1 1 2 <li>Carol</li> ->2 2
Source tree of people objects
Result tree of HTML fragments

Per the discussion in Reference trees, the template concatenates the HTML fragments into the text output.

Reference the key for a value

When mapping a tree (like a folder) to text, you can obtain the key (like a file name) via the ambient @key property.

Suppose you have a folder holding some files:

$ ls posts
post1.html post2.html

You can create an index page that links to these files using the ambient @key property. This lets a link reference a file’s specific file name in the href attribute.

$ cat blogIndex.ori
=`<ul>
{{ @map(_, =`
  <li>
    <a href="posts/{{ @key }}">
      {{ @or(_/title, "A blog post") }}
    </a>
  </li>
`) }}
</ul>
`

This index page template defines a default title property to use if a page omits a title; see template and input front matter above.

Evaluating this template produces a list of links to each post, with each href attribute referencing the appropriate file:

$ ori blogIndex.ori posts
<ul>
  <li>
    <a href="posts/post1.html">
      The First Post
    </a>
  </li>
  <li>
    <a href="posts/post2.html">
      A blog post
    </a>
  </li>
</ul>

Using named parameters

As noted, you can reference the value being mapped as an _ underscore and the key being mapped as @key. You can also define your own parameter names that are more meaningful to your specific situation.

For example, you can rewrite the blog example above:

$ ori blogIndex2.ori
(posts) => `<ul>
{{ @map(posts, (post, fileName) => `
  <li>
    <a href="posts/{{ fileName }}">
      {{ @or(post/title, "A blog post") }}
    </a>
  </li>
`) }}
</ul>
`
$ ori blogIndex2.ori/
<ul>
  <li>
    <a href="posts/post1.html">
      The First Post
    </a>
  </li>
  <li>
    <a href="posts/post2.html">
      A blog post
    </a>
  </li>
</ul>