Templates

Templates

Applies to all versions (1.21.1 and 26.2).

Templates are reusable page layouts made of components. A template lives at:

assets/<namespace>/vellumli_books/<book>/<lang>/templates/<id>.json

To use a template as a page, set the page type to the template id. Any type that is not a built-in page type is resolved as a template id, so the page's remaining fields are available to the template as variables.

{
  "type": "mymod:card",
  "title": "Amethyst",
  "text": "A shiny crystal.",
  "item": "minecraft:amethyst_shard"
}

Template fields

Field	Type	Default	Description
components	array	[]	The components to draw.
include	array	[]	Other templates to include into this one.
processor	string	(optional)	Fully qualified class name of an IComponentProcessor (no-arg constructor) that supplies variables and controls visibility.

Components

Every component has these fields in common:

Field	Type	Default	Description
type	string	(required)	The component type id.
x, y	int	0	Position on the page. Some components use -1 as "place me at my default position".
group	string	""	Group name. A processor can hide the whole group via allowRender.
flag	string	""	Config flag gating the component.
advancement	string	""	Advancement gating the component.
negate_advancement	boolean	false	Invert the advancement check.
guard	string	null	A variable expression; when it evaluates to false the component is hidden.

vellumli:text

Field	Type	Default	Description
text	string	(required)	Body text. Supports formatting.
color	hex string	book text_color	Text color.
max_width	int	page width	Maximum text width before wrapping.
line_height	int	default line height	Line height in pixels.

{ "type": "vellumli:text", "text": "#description", "x": 32, "y": 22, "max_width": 78 }

vellumli:item

Field	Type	Default	Description
item	string or array	(required)	Item stack string(s); multiple items cycle over time.
framed	boolean	false	Draw a slot frame behind the item.
link_recipe	boolean	false	Add the items to the recipe lookup.

{ "type": "vellumli:item", "item": "#item", "x": 12, "y": 24, "framed": true }

vellumli:image

Field	Type	Default	Description
image	resource location	(required)	The texture to draw.
u, v	int	0	Texture source position.
width, height	int	0	Region size on the page.
texture_width, texture_height	int	256	Full texture dimensions.
scale	float	1.0	Scale multiplier (0 hides it).

vellumli:header

Field	Type	Default	Description
text	string	(required)	Header text.
color	hex string	book header_color	Header color.
centered	boolean	true	Center the text.
scale	float	1.0	Scale multiplier.

x = -1 centers it on the page and y = -1 puts it at the top.

vellumli:separator

Draws the horizontal separator. x = -1 defaults to 0, y = -1 defaults to 12.

vellumli:frame

Draws the decorative item frame. x = -1 centers it and y = -1 puts it at the top.

vellumli:entity

Field	Type	Default	Description
entity	string	(required)	Entity id, optionally with NBT.
render_size	float	100	Render size in pixels.
rotate	boolean	true	Continuously rotate the entity.
default_rotation	float	-45	Rotation when rotate is false.

vellumli:tooltip

Field	Type	Default	Description
tooltip	array of strings	(required)	Lines of the tooltip.
width, height	int	0	Hover area.

vellumli:custom

Field	Type	Default	Description
class	string	(required)	Fully qualified class name implementing com.skd.vellumli.api.ICustomComponent.

See API for the ICustomComponent interface.

A complete template

templates/card.json:

{
  "components": [
    { "type": "vellumli:header", "text": "#title", "x": -1, "y": -1 },
    { "type": "vellumli:separator" },
    { "type": "vellumli:item", "item": "#item", "x": 12, "y": 24, "framed": true },
    { "type": "vellumli:text", "text": "#text", "x": 34, "y": 24, "max_width": 76 }
  ]
}

Including other templates

The include array merges other templates into this one. Inclusion fields:

Field	Type	Default	Description
template	string	(required)	Template id to include (required).
as	string	(required)	Scope under which the included template's variables are exposed.
using	object	{}	Bindings for the included template; right-hand values may reference variables of the including template.
x, y	int	0	Offset applied to the included components.

{
  "include": [
    { "template": "mymod:base", "as": "base", "x": 0, "y": 0,
      "using": { "title": "#title" } }
  ]
}

Included variables are addressed through the as scope, for example #base.title. Circular includes are rejected.

Variables

Inside component fields, #name refers to a variable. In a string, inline variables can appear anywhere and are written ...#name#....

Variables are resolved, in order, from:

1. Bindings of the nearest included template (for using-bound names).
2. The template's processor, via IComponentProcessor.process.
3. The variables of the including template.
4. The page's own JSON fields (the object containing the type).

Derivation functions

Append ->function to a variable to transform it:

Function	Description
iname	The display name of an item stack.
icount	The count of an item stack.
ename	The display name of an entity id.
lower	Lowercase.
upper	Uppercase.
trim	Trim whitespace.
capital	Capitalize the first letter of each word.
fcapital	Fully capitalize (first letter of every word, rest lowercased).
i18n	Translate the value as a key.
exists	true if the variable is not null.
iexists	true if the variable is a non-empty item stack.
inv	Boolean negation.
stacks	Expand an ingredient into its item stacks.

Functions chain: #item->iname->upper uppercases the item's name.

Processors

A processor is a class implementing com.skd.vellumli.api.IComponentProcessor. Set it with the template's processor field:

{
  "processor": "com.example.mymod.MyProcessor",
  "components": [ { "type": "vellumli:text", "text": "#greeting" } ]
}

The processor receives the template's variables in setup and can return values for #keys in process. It can also hide groups of components with allowRender(group). A full example is in API.