comment

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

diff --git a/doc/plugins/contrib/getfield.mdwn b/doc/plugins/contrib/getfield.mdwn
index ed03dc4394fbb5bed9da7ba5c2e69a0dedda6b20..61e80c58a76989e393850c640551da471a89c6c2 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,15 +18,15 @@ 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*}}
+* \{{$*fieldname*}}
 
   This queries the value of *fieldname* for the source page.
 
@@ -39,7 +39,27 @@ use the markup inside other directives.  There are two forms:
 
        <h1>My Long and Complicated Title With Potential For Spelling Mistakes</h1>
 
-* {{+$*fieldname*+}}
+* \{{$*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,
   the value when this page is included inside another page.
@@ -68,18 +88,50 @@ 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.
+
+### Escaping
+
+Getfield markup can be escaped by putting a backwards slash `\`
+in front of the markup.
+If that is done, then the markup is displayed as-is.
+
+### 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/field.pm>
+* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/getfield.pm>
 * git repo at git://github.com/rubykat/ikiplugins.git