From 106ad99556c808468944e6563e0101cf9fdda9e1 Mon Sep 17 00:00:00 2001
From: Pedro Silva <psilva+git@pedrosilva.pt>
Date: Wed, 15 May 2013 12:58:52 +0100
Subject: [PATCH] Perform template field substitution on albums

- adds another traversal through all plugins' template_fields for each
  'evaluate_template' call.
- requires the following idiom (or equivalent):

    @Plugin.template_field(field')
    def _tmpl_field(album):
        """Return stuff.
        """
        if isinstance(album, Album):
            return stuff
---
 beets/library.py         |  4 ++++
 docs/plugins/writing.rst | 11 +++++++++++
 2 files changed, 15 insertions(+)

diff --git a/beets/library.py b/beets/library.py
index 54b2c68e4..8d9060ad2 100644
--- a/beets/library.py
+++ b/beets/library.py
@@ -1754,6 +1754,10 @@ class Album(BaseAlbum):
         mapping['artpath'] = displayable_path(mapping['artpath'])
         mapping['path'] = displayable_path(self.item_dir())
 
+        # Get values from plugins.
+        for key, value in plugins.template_values(self).iteritems():
+            mapping[key] = value
+
         # Get template functions.
         funcs = DefaultTemplateFunctions().functions()
         funcs.update(plugins.template_funcs())
diff --git a/docs/plugins/writing.rst b/docs/plugins/writing.rst
index d92ea8374..53f0a0656 100644
--- a/docs/plugins/writing.rst
+++ b/docs/plugins/writing.rst
@@ -261,6 +261,17 @@ that adds a ``$disc_and_track`` field::
 With this plugin enabled, templates can reference ``$disc_and_track`` as they
 can any standard metadata field.
 
+Note that the above idiom expects the argument ``item`` to be an
+actual *track* item. If you'd like to provide a template field for
+*albums*, you'll need to check the argument::
+
+    @MyPlugin.template_field('field')
+    def _tmpl_field(album):
+        """Return stuff.
+        """
+        if isinstance(album, beets.library.Album):
+            return 'stuff'
+
 Extend MediaFile
 ^^^^^^^^^^^^^^^^