Inputs

Oicana supports two types of inputs. A json input takes structured data while binary data can be passed into templates through a blob input.

Inputs are defined in the template manifest. Integrations can list all inputs of a template to, for example, validate input values or offer an editor.

The typetype property of the input definition must be jsonjson. The only other required property is keykey.

[[tool.oicana.inputs]]

type = "json"

key = "data"

[[tool.oicana.inputs]]

type = "json"

key = "data"

[[tool.oicana.inputs]]

type = "json"

key = "data"

[[tool.oicana.inputs]]

type = "json"

key = "data"

A json schema file can be used for input validation.

[[tool.oicana.inputs]]

type = "json"

key = "data"

schema = "data.schema.json"

[[tool.oicana.inputs]]

type = "json"

key = "data"

schema = "data.schema.json"

[[tool.oicana.inputs]]

type = "json"

key = "data"

schema = "data.schema.json"

[[tool.oicana.inputs]]

type = "json"

key = "data"

schema = "data.schema.json"

Blob inputs can be used for binary data like images. Additional metadata can be used to further specify the type of binary data in the input.

[[tool.oicana.inputs]]

type = "blob"

key = "logo"

[[tool.oicana.inputs]]

type = "blob"

key = "logo"

[[tool.oicana.inputs]]

type = "blob"

key = "logo"

[[tool.oicana.inputs]]

type = "blob"

key = "logo"

As a common use case for blob inputs, images have special support in the oicanaoicana Typst package.

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

1. Explicit input value (for example through an integration)
2. developmentdevelopment value
3. defaultdefault value

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

1. Explicit input value (for example through an integration)
2. defaultdefault value

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 you template to have a functioning preview.

Considering a template with the files development-data.jsondevelopment-data.json, default-data.jsondefault-data.json, development-logo.pngdevelopment-logo.png, and default-logo.pngdefault-logo.png. It could define the following inputs:

[[tool.oicana.inputs]]

type = "json"

key = "data"

development = "development-data.json"

default = "default-data.json"

[[tool.oicana.inputs]]

type = "blob"

key = "logo"

development = { file = "development-logo.png", meta = { image_format = "png", foo = 5, bar = ["development", "two"] } }

default = { file = "default-logo.png", meta = { image_format = "png", foo = 5, bar = ["default", "two"] } }

[[tool.oicana.inputs]]

type = "json"

key = "data"

development = "development-data.json"

default = "default-data.json"

[[tool.oicana.inputs]]

type = "blob"

key = "logo"

development = { file = "development-logo.png", meta = { image_format = "png", foo = 5, bar = ["development", "two"] } }

default = { file = "default-logo.png", meta = { image_format = "png", foo = 5, bar = ["default", "two"] } }

[[tool.oicana.inputs]]

type = "json"

key = "data"

development = "development-data.json"

default = "default-data.json"

[[tool.oicana.inputs]]

type = "blob"

key = "logo"

development = { file = "development-logo.png", meta = { image_format = "png", foo = 5, bar = ["development", "two"] } }

default = { file = "default-logo.png", meta = { image_format = "png", foo = 5, bar = ["default", "two"] } }

[[tool.oicana.inputs]]

type = "json"

key = "data"

development = "development-data.json"

default = "default-data.json"

[[tool.oicana.inputs]]

type = "blob"

key = "logo"

development = { file = "development-logo.png", meta = { image_format = "png", foo = 5, bar = ["development", "two"] } }

default = { file = "default-logo.png", meta = { image_format = "png", foo = 5, bar = ["default", "two"] } }

The default.metadefault.meta objects for blob fallback values are optional.

In the preview of an editor, the content of development-data.jsondevelopment-data.json and development-logo.pngdevelopment-logo.png would be used. If compiled in production mode through an Oicana integration, the default fallbacks would be used if the input values are not set programmatically.