Merge branch 'master' into autotag

[git.ikiwiki.info.git] / doc / plugins / contrib / getfield.mdwn

diff --git a/doc/plugins/contrib/getfield.mdwn b/doc/plugins/contrib/getfield.mdwn
index 5e6b011139790e9c9f98be6d3c96d493f7a9a0e8..0a92894f1a7cfd1c4e824bc7639455b706f42857 100644 (file)
--- a/doc/plugins/contrib/getfield.mdwn
+++ b/doc/plugins/contrib/getfield.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=getfield author="[[rubykat]]"]]
-[[!tag type/meta]]
+[[!tag type/meta type/format]]
 [[!toc]]
 ## NAME
 
@@ -18,13 +18,13 @@ use per-page structured data, where each page is treated like a record, and the
 structured data are fields in that record.  This can include the meta-data for
 that page, such as the page title.
 
-This plugin is meant to be used in conjunction with the B<field> plugin.
+This plugin is meant to be used in conjunction with the [[field]] plugin.
 
 ### USAGE
 
 One can get the value of a field by using special markup in the page.
 This does not use directive markup, in order to make it easier to
-use the markup inside other directives.  There are two forms:
+use the markup inside other directives.  There are four forms:
 
 * {{$*fieldname*}}
 
@@ -39,6 +39,26 @@ use the markup inside other directives.  There are two forms:
 
        <h1>My Long and Complicated Title With Potential For Spelling Mistakes</h1>
 
+* {{$*pagename*#*fieldname*}}
+
+  This queries the value of *fieldname* for the page *pagename*.
+
+  For example:
+
+  On PageFoo:
+
+    \[[!meta title="I Am Page Foo"]]
+
+    Stuff about Foo.
+
+  On PageBar:
+
+    For more info, see \[[{{$PageFoo#title}}|PageFoo]].
+
+  When PageBar is displayed:
+
+    &lt;p&gt;For more info, see &lt;a href="PageFoo"&gt;I Am Page Foo&lt;/a&gt;.&lt;/p&gt;
+
 * {{+$*fieldname*+}}
 
   This queries the value of *fieldname* for the destination page; that is,
@@ -68,17 +88,43 @@ use the markup inside other directives.  There are two forms:
        <h1>I Am Page B</h1>
        <p>Stuff about A.</p>
 
+* {{+$*pagename*#*fieldname*+}}
+
+  This queries the value of *fieldname* for the page *pagename*; the
+  only difference between this and {{$*pagename*#*fieldname*}} is
+  that the full name of *pagename* is calculated relative to the
+  destination page rather than the source page.
+
+  I can't really think of a reason why this should be needed, but
+  this format has been added for completeness.
+
+### No Value Found
+
+If no value is found for the given field, then the field name is returned.
+
+For example:
+
+On PageFoo:
+
+    \[[!meta title="Foo"]]
+    My title is {{$title}}.
+    
+    My description is {{$description}}.
+
+When PageFoo is displayed:
+
+    <p>My title is Foo.</p>
+    
+    <p>My description is description.</p>
+
+This is because "description" hasn't been defined for that page.
+
 ### More Examples
 
 Listing all the sub-pages of the current page:
 
     \[[!map pages="{{$page}}/*"]]
 
-### LIMITATIONS
-
-One cannot query the values of fields on pages other than the current
-page or the destination page.
-
 ## DOWNLOAD
 
 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/getfield.pm>