21 KiB

Raw Blame History Unescape Escape

Dynamic Collections

Plex Meta Manager can dynamically create collections based on different criteria, such as

Collections based on the Collections from TMDb for every item in the library. ( Star Wars, Harry Potter, etc...)
Collections based on each of a Users Trakt Lists
Collections for the top X popular people on TMDb (Bruce Willis, Tom Hanks, etc...)
Collections for each decade represented in the library (Best of 1990s, Best of 2000s, etc...)
Collections for each of the moods/styles within a Music library (A Cappella, Pop Rock, etc...)

The main purpose of dynamic collections is to automate the creation of collections which would otherwise require considerable user input and repetition (such as creating a collection for every genre).

Using Dynamic Collections

Each dynamic collection definition creates a set of collection definitions based on some given criteria and uses either the built-in default template or a user defined custom template to dynamically create collection definitions.

Collection Naming

By default, the collections generated will be named for the thing being used to create them; things like genres, countries, actors, or even Trakt List Names.

To change the name of the collection, you can use dynamic collection attributes including title_format, remove_suffix, remove_prefix, key_name_override, and title_override all detailed below.

Dynamic Keys & Key Names

A dynamic key or key for short is used to refer to a specific value/result from the dynamic collection criteria that will be used to create the collection.

A key_name is the name that replaces <<key_name>> in title_format to create the collection titles for each key.

An example of some keys and their names that would be generated from a tmdb_collection dynamic collection are:

key: "10"
- key_name: Star Wars Collection
key: "1241"
- key_name: Harry Potter Collection

`key`	`key_name`
10	Star Wars Collection
1241	Harry Potter Collection

Example Key Usage

Keys can be used for a number of purposes, examples can be found throughout this page. A few examples are shown below:

Excluding the "Horror" key from the Genre dynamic collection definition

dynamic_collections:
  Genres:         # mapping name does not matter, just needs to be unique
    type: genre
    exclude:
      - Horror

Using the key_name_override attribute to change the formatting of "France" to "French" so that a collection can be named "French Cinema" instead of simply "France"
- This particular example also uses the title_format attribute to manipulate the naming convention of the collections.

dynamic_collections:
  Countries:         # mapping name does not matter, just needs to be unique
    type: country
    title_format: <<key_name>> Cinema
    key_name_override:
      France: French

Using the addons attribute to combine multiple keys, i.e. merging "MTV2", "MTV3" and "MTV (UK)" into one "MTV" collection.
- When doing this, individual collections will not be created for the individual MTV collections, instead they will be merged within the "MTV" collection.

dynamic_collections:
  networks:
    type: network
    addons:
      MTV:
        - MTV2
        - MTV3
        - MTV (UK)

Dynamic Collection Definition

Each dynamic collection definition must have a mapping name (just like standard collections) under the dynamic_collections attribute, which is also attached to the collection as a label to mark it as having been created by this dynamic collection.

??? example "Dynamic Collection Example (click to expand)"

This example will create a collection for every TMDb Collection associated with items in the library.

```yaml
dynamic_collections:
  TMDb Collections:          # This name is the mapping name
    type: tmdb_collection
    remove_suffix: "Collection"
```

Attributes

??? blank "type & data - Used to specify the type of Dynamic Collection.¶"

<div id="type-data" />Used to specify the type of Dynamic Collection and its data. `type` is required for every 
dynamic collection and `data` is required for any type that uses the attribute.

<hr style="margin: 0px;">

**Attribute:** `type` & `data`

**Accepted Values:** See [Dynamic Collection Types & Data](dynamic_types.md)

??? blank "exclude - Used to exclude a list of keys from being created into collections.¶"

<div id="exclude" />Used to exclude a list of `dynamic keys` from being created into collections.

<hr style="margin: 0px;">

**Attribute:** `exclude`

**Accepted Values:** List of keys

???+ example "Example"
    
    For example when making a `genre` dynamic collection definition you can exclude "Horror" from having a 
    collection created from the key.
    
    ```yaml
    dynamic_collections:
      Genres:         # mapping name does not matter, just needs to be unique
        type: genre
        exclude:
          - Horror
    ```

??? blank "addons - Used to define how multiple keys can be combined under a parent key.¶"

<div id="addons" />Used to define how multiple `dynamic keys` can be combined under a parent key.

You can define custom parent keys under addons by just using the a key that doesnt exist; it will be considered a 
custom key combining all keys into one key.

<hr style="margin: 0px;">

**Attribute:** `addons`

**Accepted Values:** [Dictionary](../pmm/yaml.md#dictionaries) where the key is the `dynamic key` and the value is a
list of `dynamic keys` to combine.

???+ example "Example"
    
    In this example the attribute is used to merge "MTV2", "MTV3" and "MTV (UK)" into the "MTV" collection.
    
    ```yaml
    dynamic_collections:
      networks:
        type: network
        addons:
          MTV:
            - MTV2
            - MTV3
            - MTV (UK)
    ```

??? blank "template - Used to define which templates are used.¶"

<div id="template" />Used to define which templates are used for these dynamic collections. Each dynamic collection 
`type` has its own default template, but if you want to define and use your own template you can.

Each template is passed a few template variables you can use.

* `value`: The list of keys and addons

* `key`: The dynamic key

* `key_name`: The key after `key_name_override`, `remove_prefix`, or `remove_suffix` are run on it.

<hr style="margin: 0px;">

**Attribute:** `template`

**Accepted Values:** Name of template or list of templates to use 

???+ example "Example"

    In this example the template removes the limit on the `smart_filter` so it shows all items in each network.

    Press the :fontawesome-solid-circle-plus: icon to learn more
    
    ```yaml
    templates:
      network collection: #(1)!
        smart_filter:
          sort_by: critic_rating.desc
          all:
            network: <<value>>
    dynamic_collections:
      Networks: #(2)!
        type: network
        title_format: <<key_name>>
        template: network collection #(3)!
    ```
    
    1. This is the mapping name of the template.
    2. This is the mapping name of the Dynamic Collection Definition.
    3. This must match the mapping name of the template you want to use.

??? blank "template_variables - Used to define template variables by key.¶"

<div id="template-variables" />Used to define template variables by key. This attribute will allow multiple template
variables to be set per dynamic key. 

???+ tip

    You can set a default value for a variable by using `default` instead of the dynamic key. 

<hr style="margin: 0px;">

**Attribute:** `template_variables`

**Accepted Values:** [Dictionary](../pmm/yaml.md#dictionaries) where the key is the template variable and the value 
is another [Dictionary](../pmm/yaml.md#dictionaries) where the key is the `dynamic key` of the collection you want 
change the template variable for and the value is the new value for the template variable.

???+ example "Example"

    For example, when using `type: tmdb_collection` and you want to define a poster url for some collections.
    
    ```yaml
    templates:
      my_template:
        optional:
          - my_collection_poster
        tmdb_collection_details: <<value>>
        collection_order: release
        url_poster: <<my_collection_poster>>
    dynamic_collections:
      TMDb Collections:          # This name is the mapping name
        type: tmdb_collection
        remove_suffix: "Collection"
        template: my_template
        template_variables: #(1)!
          my_collection_poster: #(2)!
            119: https://www.themoviedb.org/t/p/original/oENY593nKRVL2PnxXsMtlh8izb4.jpg #(3)!
            531241: https://www.themoviedb.org/t/p/original/nogV4th2P5QWYvQIMiWHj4CFLU9.jpg #(4)!
    ```

    1. Template variables are placed under `template_variables`.
    2. `my_collection_poster` is the template variable being changed.
    3. For key `119` use the url as the my_collection_poster template variable.
    4. For key `531241` use the url as the my_collection_poster template variable.

??? blank "remove_suffix - Used to remove the defined suffixes.¶"

<div id="remove-suffix" />Used to remove the defined suffixes from the key before it’s used in the collection title.

<hr style="margin: 0px;">

**Attribute:** `remove_suffix`

**Accepted Values:** List or comma-separated string of suffixes to remove

???+ example "Example"

    When using `type: tmdb_collection` you may not want every collection title to end with `Collection`.

    ```yaml
    dynamic_collections:
      TMDb Collections:          # This name is the mapping name
        type: tmdb_collection
        remove_suffix: "Collection"
    ```

??? blank "remove_prefix - Used to remove the defined prefixes.¶"

<div id="remove-prefix" />Used to remove the defined prefixes from the key before it’s used in the collection title.

<hr style="margin: 0px;">

**Attribute:** `remove_prefix`

**Accepted Values:** List or comma-separated string of prefixes to remove

???+ example "Example"

    When using `type: tmdb_collection` you may not want every collection title to start with `The`.

    ```yaml
    dynamic_collections:
      TMDb Collections:          # This name is the mapping name
        type: tmdb_collection
        remove_prefix: "The"
    ```

??? blank "title_format - Used to specify the format you want the collection titles to be.¶"

<div id="title-format" />Used to specify the format you want the collection titles to be.

There are a few special tags you can include in the `title_format`:

* `<<key_name>>` is **required** and is what will be replaced by the dynamic key name.

* `<<limit>>` will be replaced the limit template variable if passed to the definition.

* `<<library_type>>` will be replaced with either `movie`, `show`, `artist`, or `video` depending on your library 
type.

* `<<library_typeU>>` will be replaced with either `Movie`, `Show`, `Artist`, or `Video` depending on your library 
type.

<hr style="margin: 0px;">

**Attribute:** `title_format`

**Accepted Values:** String with `<<key_name>>` in it.

???+ example "Example"

    ```yaml
    dynamic_collections:
      Genres:         # mapping name does not matter just needs to be unique
        type: genre
        title_format: Top 50 <<key_name>> <<library_type>>s
    ```

??? blank "key_name_override - Used to override key names before being formatted into titles.¶"

<div id="key-name-override" />Defines how key names can be overridden before they are formatted into collection 
titles.

<hr style="margin: 0px;">

**Attribute:** `key_name_override`

**Accepted Values:** [Dictionary](../pmm/yaml.md#dictionaries) where the key is the key name you want to change and 
the value is what to change that key name to. 

???+ example "Example"

    This example uses `key_name_override` to change the formatting of "France" to "French" so that a collection can 
    be named "French Cinema" instead of simply "France".
      
    * This particular example also uses the `title_format` attribute to manipulate the naming convention of the 
    collections.
    
    ```yaml
    dynamic_collections:
      Countries:         # mapping name does not matter, just needs to be unique
        type: country
        title_format: <<key_name>> Cinema
        key_name_override:
          France: French
    ```

??? blank "title_override - Used to override titles ignoring title formatting.¶"

<div id="title-override" />Defines how collection titles can be overridden ignoring title formatting.

<hr style="margin: 0px;">

**Attribute:** `title_override`

**Accepted Values:** [Dictionary](../pmm/yaml.md#dictionaries) where the key is the `dynamic key` you want to change 
and the value is what to change the title to. 

???+ example "Example"

    This example will override the TMDb Star Wars collection which has an TMDb ID of `10` with `Star Wars Universe.
    
    ```yaml
    dynamic_collections:
      TMDb Collections:          # mapping name does not matter, just needs to be unique
        type: tmdb_collection
        remove_suffix: "Collection"
        title_override:
          10: Star Wars Universe
    ```

??? blank "custom_keys - Used to allow the use of custom keys.¶"

<div id="custom-keys" />Defines if custom keys are allowed. **Defaults to `true`**

<hr style="margin: 0px;">

**Attribute:** `custom_keys`

**Accepted Values:** `true` or `false`

???+ example "Example"

    ```yaml
    dynamic_collections:
      TMDb Collections:          # mapping name does not matter, just needs to be unique
        type: tmdb_collection
        remove_suffix: "Collection"
        custom_keys: false
    ```

??? blank "test - Used to run all collections in this set as tests.¶"

<div id="test" />Used to run all collections in this set with `test: true` in each collection definition. 
**Defaults to `fales`**

<hr style="margin: 0px;">

**Attribute:** `test`

**Accepted Values:** `true` or `false`

???+ example "Example"

    ```yaml
    dynamic_collections:
      Genres:         # mapping name does not matter just needs to be unique
        type: genre
        test: true
    ```

??? blank "sync - Used to remove dynamic collections that are no longer in the creation list.¶"

<div id="sync" />Will remove dynamic collections that are no longer in the creation list. **Defaults to `fales`**

???+ warning

    The mapping name is added as a label to any collection created using this dynamic collection set and because of 
    this when `sync` is true all collections with that label not found in this run will be deleted.

<hr style="margin: 0px;">

**Attribute:** `sync`

**Accepted Values:** `true` or `false`

???+ example "Example"

    ```yaml
    dynamic_collections:
      Trakt Liked Lists:          # mapping name does not matter just needs to be unique
        type: trakt_liked_lists
        sync: true
    ```

??? blank "include - Used to define a specific list of keys to be made into collections.¶"

<div id="include" />Define a list of keys to be made into collections. 

???+ warning

    This cannot be used with `exclude`.

???+ tip

    Use with the `other_name` attribute to create a catch-all collection for all keys not in the `include` list or 
    in any [`addons`](#addons) list.

<hr style="margin: 0px;">

**Attribute:** `include`

**Accepted Values:** `true` or `false`

???+ example "Example"

    ```yaml
    dynamic_collections:
      Genres:         # mapping name does not matter just needs to be unique
        type: genre
        include:
          - Action
          - Adventure
          - Animation
          - Comedy
          - Family
          - Fantasy
          - Horror
          - Romance
          - Science Fiction
          - War
    ```

??? blank "other_name - Used to create an "other" collection.¶"

<div id="other-name" />Will create an "other" collection when also using the [`include`](#include) by specifying the
"other" collection's name as `other_name`. When defined, all keys not in [`include`](#include) or 
[`addons`](#addons) will be combined into this collection.

<hr style="margin: 0px;">

**Attribute:** `other_name`

**Accepted Values:** String to make the "other" collection's name

???+ example "Example"

    ```yaml
    dynamic_collections:
      Genres:         # mapping name does not matter just needs to be unique
        type: genre
        other_name: Other Genres
        include:
          - Action
          - Adventure
          - Animation
          - Comedy
          - Family
          - Fantasy
          - Horror
          - Romance
          - Science Fiction
          - War
    ```

??? blank "other_template - Used to define which templates the dynamic other collection uses.¶"

<div id="other-template" />Used to define which templates are used for the dynamic other collection when they need 
to be different from the regular collection templates.

???+ tip

    To use an other collection you must be using the [`include`](#include) and [`other_name`](#other-name) 
    attributes.

Each template is passed a few template variables you can use.

* `value`: The list of keys and addons

* `key`: The dynamic key

* `key_name`: The key after `key_name_override`, `remove_prefix`, or `remove_suffix` are run on it.

* `included_keys`: The list of included keys

* `used_keys`: The list of all keys used (included_keys and their addon keys)

<hr style="margin: 0px;">

**Attribute:** `other_template`

**Accepted Values:** Name of template or list of templates to use for the other collection only

???+ example "Example"

    ```yaml
    templates: 
      Other:
        plex_search:
          any:
            genre: <key>
        summary: Other Genres found in the library.
    dynamic_collections:
      Genres:         # mapping name does not matter just needs to be unique
        type: genre
        other_name: Top Other Genres
        other_template: Other
        include:
          - Action
          - Adventure
          - Animation
          - Comedy
          - Family
          - Fantasy
          - Horror
          - Romance
          - Science Fiction
          - War
    ```

Dynamic Collection Template Variables

When calling a collection file with dynamic collection all the following are automatically accepted as template variables which will just replace the same attribute when running the file.

data
exclude
addons
remove_suffix
remove_prefix
title_format
key_name_override
title_override
custom_keys
test
sync
include
other_name

There are also several template variables that will be automatically append/remove from data, exclude, include, and addons so they can be changed by the user on the fly when needed.

append_data
remove_data
append_exclude
remove_exclude
append_include
remove_include
append_addons
remove_addons

{% include-markdown "./dynamic_examples.md" %}

21 KiB Raw Blame History Unescape Escape