Contrib plugin created_in_future

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

diff --git a/doc/plugins/contrib/getfield.mdwn b/doc/plugins/contrib/getfield.mdwn
index 929f704855cbaadca3f1bc0a2be50287dc711f5b..61e80c58a76989e393850c640551da471a89c6c2 100644 (file)
--- a/doc/plugins/contrib/getfield.mdwn
+++ b/doc/plugins/contrib/getfield.mdwn
@@ -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.
 
 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 **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
 
 ### 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.
 
 
   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>
 
 
        <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.
 
   This queries the value of *fieldname* for the destination page; that is,
   the value when this page is included inside another page.


@@ -68,17 +88,49 @@ use the markup inside other directives.  There are two forms:
        <h1>I Am Page B</h1>
        <p>Stuff about A.</p>
 
        <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}}/*"]]
 
 ### 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>
 ## DOWNLOAD
 
 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/getfield.pm>