doc/plugins/contrib/getfield.mdwn

   1 [[!template id=plugin name=getfield author="[[rubykat]]"]]
   2 [[!tag type/meta type/format]]
   3 [[!toc]]
   4 ## NAME
   5
   6 IkiWiki::Plugin::getfield - query the values of fields
   7
   8 ## SYNOPSIS
   9
  10     # activate the plugin
  11     add_plugins => [qw{goodstuff getfield ....}],
  12
  13 ## DESCRIPTION
  14
  15 This plugin provides a way of querying the meta-data (data fields) of a page
  16 inside the page content (rather than inside a template) This provides a way to
  17 use per-page structured data, where each page is treated like a record, and the
  18 structured data are fields in that record.  This can include the meta-data for
  19 that page, such as the page title.
  20
  21 This plugin is meant to be used in conjunction with the [[field]] plugin.
  22
  23 ### USAGE
  24
  25 One can get the value of a field by using special markup in the page.
  26 This does not use directive markup, in order to make it easier to
  27 use the markup inside other directives.  There are four forms:
  28
  29 * \{{$*fieldname*}}
  30
  31   This queries the value of *fieldname* for the source page.
  32
  33   For example:
  34
  35         \[[!meta title="My Long and Complicated Title With Potential For Spelling Mistakes"]]
  36         # {{$title}}
  37
  38   When the page is processed, this will give you:
  39
  40         <h1>My Long and Complicated Title With Potential For Spelling Mistakes</h1>
  41
  42 * \{{$*pagename*#*fieldname*}}
  43
  44   This queries the value of *fieldname* for the page *pagename*.
  45
  46   For example:
  47
  48   On PageFoo:
  49
  50     \[[!meta title="I Am Page Foo"]]
  51
  52     Stuff about Foo.
  53
  54   On PageBar:
  55
  56     For more info, see \[[\{{$PageFoo#title}}|PageFoo]].
  57
  58   When PageBar is displayed:
  59
  60     &lt;p&gt;For more info, see &lt;a href="PageFoo"&gt;I Am Page Foo&lt;/a&gt;.&lt;/p&gt;
  61
  62 * \{{+$*fieldname*+}}
  63
  64   This queries the value of *fieldname* for the destination page; that is,
  65   the value when this page is included inside another page.
  66
  67   For example:
  68
  69   On PageA:
  70
  71         \[[!meta title="I Am Page A"]]
  72         # {{+$title+}}
  73
  74         Stuff about A.
  75
  76   On PageB:
  77
  78         \[[!meta title="I Am Page B"]]
  79         \[[!inline pagespec="PageA"]]
  80
  81   When PageA is displayed:
  82
  83         <h1>I Am Page A</h1>
  84         <p>Stuff about A.</p>
  85
  86   When PageB is displayed:
  87
  88         <h1>I Am Page B</h1>
  89         <p>Stuff about A.</p>
  90
  91 * \{{+$*pagename*#*fieldname*+}}
  92
  93   This queries the value of *fieldname* for the page *pagename*; the
  94   only difference between this and \{{$*pagename*#*fieldname*}} is
  95   that the full name of *pagename* is calculated relative to the
  96   destination page rather than the source page.
  97
  98   I can't really think of a reason why this should be needed, but
  99   this format has been added for completeness.
 100
 101 ### Escaping
 102
 103 Getfield markup can be escaped by putting a backwards slash `\`
 104 in front of the markup.
 105 If that is done, then the markup is displayed as-is.
 106
 107 ### No Value Found
 108
 109 If no value is found for the given field, then the field name is returned.
 110
 111 For example:
 112
 113 On PageFoo:
 114
 115     \[[!meta title="Foo"]]
 116     My title is {{$title}}.
 117
 118     My description is {{$description}}.
 119
 120 When PageFoo is displayed:
 121
 122     <p>My title is Foo.</p>
 123
 124     <p>My description is description.</p>
 125
 126 This is because "description" hasn't been defined for that page.
 127
 128 ### More Examples
 129
 130 Listing all the sub-pages of the current page:
 131
 132     \[[!map pages="{{$page}}/*"]]
 133
 134 ## DOWNLOAD
 135
 136 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/getfield.pm>
 137 * git repo at git://github.com/rubykat/ikiplugins.git