(templates)=
# Templates

## Template types
Templates are JSON files that define how to generate images. They let you define which recipes should be included in the generated images, how they should be arranged, and what information should be included in the images.

There are two types of templates supported in the Recipe Image Generator.
- **Page Templates** - simpler, all images are generated in the same way.
- **Book Templates** - these are used to define a collection of Page templates either by referencing them or by defining them inline.

(page-templates)=
### Page Templates

The page templates have the following structure:

```json
{
    "output_file_name": "${last_recipe_name}_page",
    "background": "example_background.png",
    "size": [ 256, 256 ],  // This is optional if "background" is defined.
    "scale": 1,  // This is always optional
    "foreground": [
      // The "foreground_items" are explained in a
      // separate section of the documentation.
    ]
}
```


#### output_file_name
The names of the files generated by the Recipe Image Generator always have a number prefix with 4 digits filled with leading zeros if necessary. The `output_file_name` defines the suffix added after that number.

The `output_file_name` can be a raw string or a string with variables. The variables are:

- `${last_recipe_namespace}` - the namespace of the last recipe used for the page (e.g. the recipe called "shapescape:dirt" will have the namespace "shapescape").
- `${last_recipe_name}` - the name of the last recipe used for the page (e.g. the recipe called "shapescape:dirt" will have the name "dirt").
- `${template_name}` - the name of  this template file.

You can simply put these values into the string that defines the name and they will be replaced with proper values.

In addition to these variables you can also use the counters, variables and last_recipe properties. You can read more about that syntax on the {ref}`Using variables<using-variables>` page.

#### background
The `background` property defines the background image of the template. Providing it is optional if you define the `size` property.

#### size
The `size` property defines the size of the image in pixels. It's an array of two numbers: `[ width, height ]`. Providing it is optional if you define the `background` property. If both the `background` and `size` properties are defined, the background image will be resized to the size defined in the `size` property.

#### scale
The scale property defines the scale of the image. It's the number that is multiplied with the size of the image. It's always optional. The default value is 1. You can use it to generate bigger images which is useful when your template scales down its elements too much.

#### foreground
The `foreground` property is an array of the foreground items that define the images pasted on top of the background. You can read about the available foreground items in the {ref}`Foreground items<foreground-items>` article.

(book-templates)=
## Book Templates

The book templates have the following structure:

```json
{
    "pages": [
      // The list of the pages of the book
    ]
}
```

The `pages` property is an array of the pages of the book. Each page can be either a reference to a page template or an inline definition of a page template. In this section, we'll only focus on the reference to a page template. The syntax for the page is explained in the {ref}`Page Templates<page-templates>` section.

The page reference syntax:
```json
    {
      "recipe_pattern": "shapescape:(witches_hat|beenade|bouncy_bomb)",
      "page": "Book (recipe with image)",
      "scope": {
        "text": "This is an example text."
      }
    },
```

### recipe_pattern
The **recipe_pattern** property is a regular expression that is matched against the name of the recipe. If the recipe matches the pattern, the page is used to generate the image.

You can read about the regular expressions here:
- [https://en.wikipedia.org/wiki/Regular_expression](https://en.wikipedia.org/wiki/Regular_expression)

For basic usage, you can use the `.+` pattern which matches any recipe. If you want to match only specific recipe names you can list them and separate them with a pipe `|` character. For example, if you want to match only the `minecraft:stone` and `minecraft:stone_slab` recipes, you can use the following pattern: `minecraft:stone|minecraft:stone_slab`.

### page
The **page** is the name of the page template to use. A correct reference is a name of the template file without the extension.

You can get the list of available page templates in the `Template` dropdown menu in the GUI.

### scope
The **scope** property defines the scope of variables that can be accessed in the page template. The use of variables in the text fields is explained in the {ref}`Using variables<using-variables>` article.