* Add templatefile hook.

* Add pagetemplate plugin, which allows changing the template used for
  a page. (Not to be confused with the hook of the same name..)

4 files changed, 39 insertions, 7 deletions

diff --git a/doc/plugins/pagetemplate.mdwn b/doc/plugins/pagetemplate.mdwn
new file mode 100644
index 000000000..192322d72
--- /dev/null
+++ b/doc/plugins/pagetemplate.mdwn
@@ -0,0 +1,16 @@
+[[template id=plugin name=pagetemplate author="[[Joey]]"]]
+[[tag type/chrome]]
+
+This plugin allows a page to be created using a different
+[[template|wikitemplate]]. The page text is inserted into the template, so
+the template controls the overall look and feel of the wiki page. This is
+in contrast to the [[template]] plugin, which allows inserting templates
+_into_ the body of a page.
+
+This plugin can only use templates that are already installed in
+/usr/share/ikiwiki/templates (or wherever ikiwiki is configured to look for
+them). You can choose to use any .tmpl files in that directory. Example:
+
+	\[[pagetemplate template=my_fancy.tmpl]]
+	
+[[pagetemplate template=my_fancy.tmpl]]
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 870b3c451..a122845af 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -128,17 +128,28 @@ return the htmlized content.
 
 	hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
-[[Templates]] are filled out for many different things in ikiwiki, like
-generating a page, or part of a blog page, or an rss feed, or a cgi. This
-hook allows modifying those templates. The function is passed named
-parameters. The "page" and "destpage" parameters are the same as for a
-preprocess hook. The "template" parameter is a [[cpan HTML::Template]]
-object that is the template that will be used to generate the page. The
-function can manipulate that template object.
+[[Templates|wikitemplate]] are filled out for many different things in
+ikiwiki, like generating a page, or part of a blog page, or an rss feed, or
+a cgi. This hook allows modifying the variables available on those
+templates. The function is passed named parameters. The "page" and
+"destpage" parameters are the same as for a preprocess hook. The "template"
+parameter is a [[cpan HTML::Template]] object that is the template that
+will be used to generate the page. The function can manipulate that
+template object.
 
 The most common thing to do is probably to call `$template->param()` to add
 a new custom parameter to the template.
 
+### templatefile
+
+	hook(type => "templatefile", id => "foo", call => \&templatefile);
+
+This hook allows plugins to change the [[template|wikitemplate]] that is
+used for a page in the wiki. The hook is passed a "page" parameter, and
+should return the name of the template file to use, or undef if it doesn't
+want to change the default ("page.tmpl"). Template files are looked for in
+/usr/share/ikiwiki/templates by default.
+
 ### sanitize
 
 	hook(type => "sanitize", id => "foo", call => \&sanitize);
diff --git a/doc/todo/Allow_per-page_template_selection.mdwn b/doc/todo/Allow_per-page_template_selection.mdwn
index 4d3041d2a..231ccf502 100644
--- a/doc/todo/Allow_per-page_template_selection.mdwn
+++ b/doc/todo/Allow_per-page_template_selection.mdwn
@@ -39,3 +39,5 @@ could be accepted upstream. Joey, what do you think? And would a
 proper patch be helpful (it really just adds those lines to the right
 place).
 
+> Fully implemented as a templatefile hook and a [[plugins/pagetemplate]]
+> plugin. --[[Joey]] [[done]]
diff --git a/doc/wikitemplates.mdwn b/doc/wikitemplates.mdwn
index 5e2eb8a37..4fc163599 100644
--- a/doc/wikitemplates.mdwn
+++ b/doc/wikitemplates.mdwn
@@ -34,5 +34,8 @@ located in /usr/share/ikiwiki/templates by default.
 * `searchform.tmpl` - Used by the [[plugins/search]] plugin to add a search
   form to wiki pages.
 
+The [[plugins/pagetemplate]] plugin can allow individual pages to use a
+different template than `page.tmpl`.
+
 The [[plugins/template]] plugin also uses templates, though those
 [[templates]] are stored in the wiki.