Templates
Under Construction
This documentation is actively being developed.
A Template is a set of custom settings and Card configurations that can be
assigned to multiple Series or Episodes at once. Mutliple Templates can be
assigned to a Series or Episode, and, with Filters, can be used to conditionally
apply setting changes. Templates can be viewed and edited at the Templates page
within TCM (the /card-templates URL).
An easy way to view Templates is that they allow you to group Card customizations together so they can be easily edited en-masse without changing each Series individually. The most common use-case is to develop a Template (or a set of Templates) that applies to some subset of your Series - e.g. all anime, or all documentaries - and apply those Templates automatically when Syncing.
Standard Example
By far the most common example of using a Template is for utilizing different card configurations for anime and non-anime cards. Creating an anime Template which overrides the card type, adds translations, and potentially adds absolute episode numbering allows for easily maintaining two very separate card looks.
Some widely used Templates can be found here.
Template Priority
One key feature of Templates is the ability to assign more than one to a Series or Episode and implement a priority system using Filters.
Whenever a Template is assigned, TCM evaluates whether that Template should be applied to whatever operation it is performing. It does this by looking at the assigned Filters; and the first Template whose Filter conditions are all met will be utilized.
Within the UI, Templates are always displayed in order. Meaning the first Template listed in the dropdown of a Sync, Series, or Episode is the highest priority Template.
Creating a New Template
At the top of the Templates page, a new Template can be created by clicking the button. This will create a "blank" Template.
Clicking the accordion will expand the Template, where all customization can be entered.
Previews
On the right-hand side of all Templates are 'live' previews of the current Template. This preview reflects the currently entered settings - not necessarily what is saved - and can be refreshed by clicking the button.
Customization
All Templates have the following options which can be adjusted:
- ...
Each of these is described in greater detail below. All values can be left blank - if blank, TCM will use the next highest priority setting from the Series, Episode, or global setting. Setting priorities are listed here.
Name
A Template's name is purely for easier selection within the TCM UI. If you are using Tiered Templates, it is recommended to include the relative priority of the Template in the name - e.g. Tier 1 - Unwatched Anime, or Tier 0 - All Anime.
Importing Blueprint Templates
The name of a Template is also used to match Templates when importing Blueprints.
For example - if you are importing a Blueprint featuring a Template named Anime and have already created a Template named Anime, then TCM will not duplicate the Template and instead just assign the existing Template to the Series.
This is relatively uncommon, as Templates are not typically included in Blueprints.
Filters
Filters are a critical component of utilizing different priority Templates for more fine-tuned customization. A Template can have any number of Filters, and all Filters must be true (or unevaluatable) for a Template to be applied.
Each condition of a Filter is made up of 3 parts. An Argument, which is the variable pulled from the specific Series or Episode being evaluated; an Operation which is what operation is being applied to the Argument; and a Reference Value which is what the result of the evaluation is compared against. To remove a condition, clear its Operation (the middle column).
Example
To add a Filter condition which only applies to unwatched pilots (season 1 episode 1 of a Series), you would create the following conditions:
| Argument | Operation | Reference Value |
|---|---|---|
Season Number |
equals |
1 |
Episode Number |
equals |
1 |
Episode Watched Status |
is false |
Note that there is no reference value for the Episode Watched Status
condition, as the is false operation does not need to reference another
value.
If you enter some invalid condition - like a bad reference value, or a nonsensical operation - then the condition is skipped (which is the same as being true).
Optimal Filter Ordering
If you'd like to make marginal perfomance improvements, it is best practice to put conditions which are more likely to fail - i.e. the more restrictive conditions - first, as this short-circuits the Filter evaluation logic.
For example, putting a condition for Episode Number equals before
Season Number equals would be ideal since more failures will occur on
the Episode number condition than the season number condition.
Below is a summary of all Filter arguments, their valid operations, a description of what this Filter accomplishes, and whether it requires a reference value.
All Supported Filter Conditions1
| Operation | Description | Reference Value |
|---|---|---|
| equals | Only apply to Series of the given name | |
| does not equal | Do not apply to Series of the given name | |
| starts with | Only apply to Series whose name starts with the given text | |
| does not start with | Do not apply to Series whose name starts with the given text | |
| ends with | Only apply to Series whose name ends with the given text | |
| does not end with | Do not apply to Series whose name ends with the given text | |
| contains | Only apply to Series whose name contains the given text | |
| does not contain | Do not apply to Series whose name contains the given text | |
| matches | Only apply to Series whose name matches the given regex | |
| does not match | Do not apply to Series whose name matches the given regex |
The is before and is after conditions cannot be used with a Series
Year argument; see the Episode Airdate argument, or use the math
operations (less than, greater than, etc.).
| Operation | Description | Reference Value |
|---|---|---|
| equals | Only apply to Series whose year is exactly the given number | |
| does not equal | Do not apply to Series whose year is exactly the given number | |
| matches | Only apply to Series whose year matches the given regex | |
| does not match | Do not apply to Series whose year matches the given regex | |
| is less than | Only apply to Series whose year is less than the given number | |
| is less than or equal | Only apply to Series whose year is less than or equal to the given number | |
| is greater than | Only apply to Series whose year is greater than the given number | |
| is greater than or equal | Only apply to Series whose year is greater than or equal to the given number |
The Number of Seasons argument only counts Episodes which are in TCM.
| Operation | Description | Reference Value |
|---|---|---|
| equals | Only apply to Series with exactly the given number of seasons | |
| does not equal | Do not apply to Series with exactly the given number of seasons | |
| is less than | Only apply to Series whose number of seasons is less than the given number | |
| is less than or equal | Only apply to Series whose number of seasons is less than or equal to the given number | |
| is greater than | Only apply to Series whose number of seasons is greater than the given number | |
| is greater than or equal | Only apply to Series whose number of seasons is greater than or equal to the given number |
Library names are evaluated as a list of all assigned libraries, meaning
the full library name must be specified to filter on this argument. For
example, if I had a Series assigned to the Anime HD and Anime 4K
libraries, the reference value Anime would not match either of
these. The entire name, such as Anime HD would be required.
| Operation | Description | Reference Value |
|---|---|---|
| contains | Only apply to Series with a library of the given name | |
| does not contain | Do not apply to Series with a library of the givens name |
This Filter condition only looks at the default Series logo - e.g.
logo.png within the source directory.
| Operation | Description | Reference Value |
|---|---|---|
| file exists | Only apply to Series whose logo exists |
This Filter condition can be used with Variables to dynamically apply a Template based on the existence of some file, such as a poster, per-season logo, etc.
| Operation | Description | Reference Value |
|---|---|---|
| file exists | Only apply to Series where the indicated File exists |
Watched statuses are evaluated per-library (even if Multi-Library mode is disabled).
| Operation | Description | Reference Value |
|---|---|---|
| is true | Only apply to Episodes that have been watched | |
| is false | Do not apply to Episode that have been watched | |
| is null | Only apply to Episode whose watched status is unknown2 | |
| is not null | Only apply to Episode whose watched status is known2 |
| Operation | Description | Reference Value |
|---|---|---|
| is true | Only apply to Episodes that are not part of season 0 | |
| equals | Only apply to Episodes with exactly the given season number | |
| does not equal | Do not apply to Episodes with exactly the given season number | |
| is less than | Only apply to Episodes whose season number is less than the given number | |
| is less than or equal | Only apply to Episodes whose season number is less than or equal to the given number | |
| is greater than | Only apply to Episodes whose season number is greater than the given number | |
| is greater than or equal | Only apply to Episodes whose season number is greater than or equal to the given number |
| Operation | Description | Reference Value |
|---|---|---|
| equals | Only apply to Episodes with exactly the given episode number | |
| does not equal | Do not apply to Episodes with exactly the given episode number | |
| is less than | Only apply to Episodes whose episode number is less than the given number | |
| is less than or equal | Only apply to Episodes whose episode number is less than or equal to the given number | |
| is greater than | Only apply to Episodes whose episode number is greater than the given number | |
| is greater than or equal | Only apply to Episodes whose episode number is greater than or equal to the given number |
Special Variable
The variable {absolute_episode_number} can be used in episode text
format strings (and other locations) which will use the absolute
episode number if available, and the normal episode number,
otherwise.
| Operation | Description | Reference Value |
|---|---|---|
| is null | Only apply to Episodes with no absolute episode number | |
| is not null | Only apply to episodes with an absolute episode number | |
| equals | Only apply to Episodes with exactly the given absolute episode number | |
| does not equal | Do not apply to Episodes with exactly the given absolute episode number | |
| is less than | Only apply to Episodes whose absolute episode number is less than the given number | |
| is less than or equal | Only apply to Episodes whose absolute episode number is less than or equal to the given number | |
| is greater than | Only apply to Episodes whose absolute episode number is greater than the given number | |
| is greater than or equal | Only apply to Episodes whose absolute episode number is greater than or equal to the given number |
| Operation | Description | Reference Value |
|---|---|---|
| equals | Only apply to Episodes whose title is exactly some text | |
| does not equal | Do not apply to Episodes whose title is exactly some text | |
| starts with | Only apply to Episodes whose title starts with some text | |
| does not start with | Do not apply to Episodes whose title starts with some text | |
| ends with | Only apply to Episodes whose title ends with some text | |
| does not end with | Do not apply to Episodes whose title ends with some text | |
| contains | Only apply to Episodes whose title contains some text | |
| does not contain | Do not apply to Episodes whose title contains some text | |
| matches | Only apply to Episodes whose title matches some regex | |
| does not match | Do not apply to Episodes whose title matches some regex |
All title length evaluations are done on the original title, before any title text formatting or splitting.
| Operation | Description | Reference Value |
|---|---|---|
| equals | Only apply to Episodes whose title length is exactly the given number | |
| does not equal | Do not apply to Episodes whose title length is exactly the given number | |
| is less than | Only apply to Episodes whose title length is less than the given number | |
| is less than or equal | Only apply to Episodes whose title length is less than or equal to the given number | |
| is greater than | Only apply to Episodes whose episode title length is greater than the given number | |
| is greater than or equal | Only apply to Episodes whose episode title length is greater than or equal to the given number |
All airdate reference values must be entered as YYYY-MM-DD - e.g.
2023-12-30.
| Operation | Description | Reference Value |
|---|---|---|
| is null | Only apply to Episodes with no airdate | |
| is not null | Do not apply to Episodes with airdates | |
| is before | Only apply to Episodes which aired before the given date | |
| is after | Only apply to Episodes which aired after the given date |
| Operation | Description | Reference Value |
|---|---|---|
| is null | Only apply to Episodes with no extras | |
| is not null | Do not apply to Episodes with any extras | |
| contains | Only apply to Episodes with extras of the given label | |
| does not contain | Do not apply to Episodes with extras of the given label |
Card Type
The card type to apply as part of this Template.
Font
A Named Font to apply as part of this Template.
Watched and Unwatched Episode Style
How to stylize watched and unwatched Episodes as part of this Template.
Hide Season Titles
Whether to hide season titles as part of this Template.
Season Titles
-
Argument and operation pairs which are meaningless (but technically valid) - e.g.
Series Nameis greater than...- are not listed. Many of these are either always true or always false, but hold no real meaning. ↩ -
An Episode's watched status is unknown if the Episode cannot be found in an associated Media Server within the specified library. ↩↩