Templates

Background

The idea of templates is borrowed from Kometa, and is designed to define a common structure of YAML that can be easily repeated across multiple series. Any number of templates can be specified within a series YAML file, and templates are not shared across files.

Templates go inside their own templates section of a series YAML file, like so:

templates:
  template_1:
    # etc.
  
  template_2:
    # etc.

All templates are automatically passed the series' title, year, and clean_title (but these can also be manually overwritten/specified); as well as template_name which is the name of the template.

Specification

There are two ways to specify what template to use for a series, the "name only" method, and the "normal" method.

Name-Only

If the template being used does not have any variables, then you can just specify the name of the template, like so:

template: TEMPLATE_NAME

This is identical to specifying template: {name: TEMPLATE_NAME} (see below).

Normal

If the template being used has variables, then you must specify the template as a "dictionary" in one of the following ways

NOTE: Each way is completely identical, and which you use is just a personal preference

# Option 1
template: {name: TEMPLATE_NAME, variable_1: value_1, variable_2: value_2, ...}

# Option 2
template:
  name: TEMPLATE_NAME
  variable_1: value_1
  variable_2: value_2
  # ...

Variables

NOTE: Every template is automatically provided the <<title>>, <<year>>, <<template_name>>, and <<clean_title>> keys.

Templates support variable data, so that series-specific data can be passed into a template without creating a new template for each use-case. These variables must be entered into the template as <<key>>, and then the value is provided under that key. For example, take the following template specification and use:

templates:
  typical-card:
    year: <<year>>
    library: <<library_name>>
    card_type: standard

series:
  Breaking Bad (2008):
    template:
      name: typical-card
      library_name: TV

This uses the template under the name typical-card, and passes into the template variables <<year>> and <<library_name>> the value of TV respectively. Note that year was not supplied - this is because all templates are automatically given year and title; also note that not all parts of a template need variables (in fact none of them do), such as the value of card_type being fixed at standard.

If a template has any variables, then those must be provided by the series applying that template. If any variables are omitted, then the series will be skipped by the Maker.

Advanced Variable Specification

Technically the Maker can replace a variable anywhere in the text of a template definition. This means you can get very fancy (such as combining variables in a template), but is not widely useful. For example, take the following:

templates:
  tvdb-folder-naming:
    year: <<year>>
    library: TV
    media_directory: ./media/<<title>> (<<year>>) [<<tvdb_id>>]/

series:
  Breaking Bad (2008):
    template:
      name: tvdb-folder-naming
      tvdb_id: 81189

This would effectively assign the media directory of Breaking Bad to ./media/Breaking Bad (2008) [81189]/.

Default Values

You can specify default values, which will apply to any unspecified variables, by providing a default section of your template. For example:

templates:
  standard-anime:
    card_type: <<ctype>>
    library: Anime
    defaults: # DEFAULT VALUES
      ctype: anime

This means that if the template is specified and a value for <<ctype>> is not provided, then the default value of anime will be used.

Overwriting a Template

All template values are viewed as "lower priority" than those within the series specification itself. This means that anything within a template can be overwritten by re-specifying that value. Take the following example:

templates:
  standard-tv:
    year: <<year>>
    library: TV
    tmdb_sync: false

series:
  Breaking Bad (2008):
    template: standard-tv
    tmdb_sync: true

Although the template that has a fixed value of tmdb_sync that is false, by repeating that value within the series itself, a value of true can be used instead.

Example

The following two examples are identical and are designed to showcase the benefits of using templates when "repeating" a lot of structure.

This first example showcases a "typical" structure of a series YAML file without templating.

libraries:
  Anime: 
    path: ./Media/Anime/
    card_type: anime

series:
  Cowboy Bebop (1998):
    library: Anime
    translation:
    - language: ja
      key: kanji
    seasons:
      hide: true

  "Demon Slayer: Kimetsu no Yaiba (2019)":
    library: Anime
    translation:
    - language: ja
      key: kanji

  "Fullmetal Alchemist: Brotherhood (2009)":
    library: Anime
    translation:
    - language: ja
      key: kanji
    seasons:
      hide: true

There is clearly a lot of "repeat" information, indicating that templates are a great way to speed up this process. The exact same specification can be achieved with:

libraries:
  Anime: 
    path: ./Media/Anime/
    card_type: anime

templates:
  anime_with_kanji:
    year: <<year>>
    library: Anime
    translation:
      language: ja
      key: kanji
    seasons:
      hide: <<seasonless>>
    defaults:
      seasonless: true

series:
  Cowboy Bebop (1998):
    template: anime_with_kanji

  "Demon Slayer: Kimetsu no Yaiba (2019)":
    template: {name: anime_with_kanji, seasonless: false}

  "Fullmetal Alchemist: Brotherhood (2009)":
    template: {name: anime_with_kanji, seasonless: true}

Notice how the default value of true for the <<seasonless>> variable is utilized for Cowboy Bebop. It could have been used for FMAB, but for demonstrative purposes both ways are shown.