Improved documentation for get_hook_templates, noting the template tag

[mediagoblin.git] / mediagoblin / tools / pluginapi.py

diff --git a/mediagoblin/tools/pluginapi.py b/mediagoblin/tools/pluginapi.py
index 38ab631baf54b36d89cf5d722cf0677cefa32ba9..5794bf635497ced2fcc85bf82857dd97252bca64 100644 (file)
--- a/mediagoblin/tools/pluginapi.py
+++ b/mediagoblin/tools/pluginapi.py
@@ -83,6 +83,9 @@ class PluginManager(object):
         # list of registered template paths
         "template_paths": set(),
 
+        # list of template hooks
+        "template_hooks": {},
+
         # list of registered routes
         "routes": [],
         }
@@ -131,6 +134,18 @@ class PluginManager(object):
     def get_routes(self):
         return tuple(self.routes)
 
+    def register_template_hooks(self, template_hooks):
+        for hook, templates in template_hooks.items():
+            if isinstance(templates, (list, tuple)):
+                self.template_hooks.setdefault(hook, []).extend(list(templates))
+            else:
+                # In this case, it's actually a single callable---not a
+                # list of callables.
+                self.template_hooks.setdefault(hook, []).append(templates)
+
+    def get_template_hooks(self, hook_name):
+        return self.template_hooks.get(hook_name, [])
+
 
 def register_routes(routes):
     """Registers one or more routes
@@ -208,3 +223,37 @@ def get_config(key):
     return plugin_section.get(key, {})
 
 
+def register_template_hooks(template_hooks):
+    """
+    Register a dict of template hooks.
+
+    Takes template_hooks as an argument, which is a dictionary of
+    template hook names/keys to the templates they should provide.
+    (The value can either be a single template path or an iterable
+    of paths.)
+
+    Example:
+      {"media_sidebar": "/plugin/sidemess/mess_up_the_side.html",
+       "media_descriptionbox": ["/plugin/sidemess/even_more_mess.html",
+                                "/plugin/sidemess/so_much_mess.html"]}
+    """
+    PluginManager().register_template_hooks(template_hooks)
+
+
+def get_hook_templates(hook_name):
+    """
+    Get a list of hook templates for this hook_name.
+
+    Note: for the most part, you access this via a template tag, not
+    this method directly, like so:
+
+      {% template_hook "media_sidebar" %}
+
+    ... which will include all templates for you, partly using this
+    method.
+
+    Returns:
+      A list of strings representing template paths.
+
+    """
+    return PluginManager().get_template_hooks(hook_name)