Templates

Background

The idea of templates is borrowed (stolen?) from Plex Meta Manager, 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, templates are not shared across files, and currently optional data is not supported.

All templates are automatically passed the series' title and year (but these can also be manually overwritten/specified).

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 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
  # ...
  
# Option 3
template: {
  name: TEMPLATE_NAME
  variable_1: value_1
  variable_2: value_2
  # ...
  }

Variables

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]/.

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>>

series:
  Cowboy Bebop (1998):
    template: {name: anime_with_kanji, seasonless: true}

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

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