Defining Template Inputs

There are two types of inputs. A jsonjson input contains structured data while a blobblob input passes bytes and optionally metadata to the template. For example, in an invoice the items and customer data could be a jsonjson input and the company logo could be a blobblob input.

The Oicana Typst package

Template inputs are configured in the manifest file typst.tomltypst.toml. The Oicana Typst package determines the current values of inputs.

Add the following to the top of your main.typmain.typ file to initialize the package:

#import "@preview/oicana:0.1.0": setup

#let read-project-file(path) = return read(path, encoding: none);

#let (input, oicana-image, oicana-config) = setup(read-project-file);

#set document(date: datetime.today())

#import "@preview/oicana:0.1.0": setup

#let read-project-file(path) = return read(path, encoding: none);

#let (input, oicana-image, oicana-config) = setup(read-project-file);

#set document(date: datetime.today())

#import "@preview/oicana:0.1.0": setup

#let read-project-file(path) = return read(path, encoding: none);

#let (input, oicana-image, oicana-config) = setup(read-project-file);

#set document(date: datetime.today())

#import "@preview/oicana:0.1.0": setup

#let read-project-file(path) = return read(path, encoding: none);

#let (input, oicana-image, oicana-config) = setup(read-project-file);

#set document(date: datetime.today())

This snippet gives the Oicana package access to the Typst project's files. We can now use the return values from calling setupsetup in the rest of the template.

Defining inputs

We will use a jsonjson input to pass a name into the template. Add the following to the end of the typst.tomltypst.toml file:

[[tool.oicana.inputs]]

type = "json"

key = "info"

[[tool.oicana.inputs]]

type = "json"

key = "info"

[[tool.oicana.inputs]]

type = "json"

key = "info"

[[tool.oicana.inputs]]

type = "json"

key = "info"

The value of this input is now available in the template as input.infoinput.info, where infoinfo is the key of the input as defined in typst.tomltypst.toml.

While we develop the template, the value of the input will be nonenone, because there is no Oicana integration setting a value for it. We can change that by defining a defaultdefault or developmentdevelopment value for the input.

Default and Development values

Inputs can define two different fallback values, defaultdefault and developmentdevelopment. These fallback values differ in priority based on which mode the template is compiled in.

When compiling a template in development mode, input values have the priority

Explicit input value (for example through an integration)
developmentdevelopment value
defaultdefault value

If you compile in production mode, the developmentdevelopment value is ignored:

Explicit input value (for example through an integration)
defaultdefault value

When to use each mode

Development mode is used in two scenarios:

When developing templates in a Typst editor, live previews will use the development mode. The same goes for other tooling without Oicana integration (like the official Typst CLI).
By default, template registration (typically at application startup) uses development mode when warming up the Typst cache for the template to speed up later compilations.

Production mode is the default for document compilation in integrations. It ensures your application fails explicitly rather than accidentally using test data in production documents. If an input value is missing in production mode and the input does not have a defaultdefault value, the compilation will fail unless your template handles nonenone values for that input.

While developing an Oicana template in a Typst editor, it will be compiled in development mode. It makes sense to define developmentdevelopment values for all required inputs of your template to have a functioning preview.

Let's extend our input with a developmentdevelopment value. First create an info.jsoninfo.json file in the template directory:

  "name": "Chuck Norris"

  "name": "Chuck Norris"

  "name": "Chuck Norris"

  "name": "Chuck Norris"

Then extend the input definition and set the developmentdevelopment value to be info.jsoninfo.json:

[[tool.oicana.inputs]]

type = "json"

key = "info"

development = "info.json"

[[tool.oicana.inputs]]

type = "json"

key = "info"

development = "info.json"

[[tool.oicana.inputs]]

type = "json"

key = "info"

development = "info.json"

[[tool.oicana.inputs]]

type = "json"

key = "info"

development = "info.json"

In our template we can now use input.info.nameinput.info.name and the preview will show "Chuck Norris".

#import "@preview/oicana:0.1.0": setup

#let read-project-file(path) = return read(path, encoding: none);

#let (input, oicana-image, oicana-config) = setup(read-project-file);

#set document(date: datetime.today())

= Hello from Typst, #input.info.name

Now we can pass names into the template from any Oicana integration.

#import "@preview/oicana:0.1.0": setup

#let read-project-file(path) = return read(path, encoding: none);

#let (input, oicana-image, oicana-config) = setup(read-project-file);

#set document(date: datetime.today())

= Hello from Typst, #input.info.name

Now we can pass names into the template from any Oicana integration.

#import "@preview/oicana:0.1.0": setup

#let read-project-file(path) = return read(path, encoding: none);

#let (input, oicana-image, oicana-config) = setup(read-project-file);

#set document(date: datetime.today())

= Hello from Typst, #input.info.name

Now we can pass names into the template from any Oicana integration.

#import "@preview/oicana:0.1.0": setup

#let read-project-file(path) = return read(path, encoding: none);

#let (input, oicana-image, oicana-config) = setup(read-project-file);

#set document(date: datetime.today())

= Hello from Typst, #input.info.name

Now we can pass names into the template from any Oicana integration.

With the input defined in your template, you're ready to choose an integration and learn how to pass dynamic values from your application code. In preparation for that, you should pack the template again using oicana packoicana pack to have the latest state of the template at hand.