doc/plugins/contrib/ymlfront.mdwn

   1 [[!template id=plugin name=ymlfront author="[[rubykat]]"]]
   2 [[!tag type/meta]]
   3 [[!toc]]
   4 ## NAME
   5
   6 IkiWiki::Plugin::ymlfront - add YAML-format data to a page
   7
   8 ## SYNOPSIS
   9
  10     # activate the plugin
  11     add_plugins => [qw{goodstuff ymlfront ....}],
  12
  13     # configure the plugin
  14     ymlfront_delim => [qw(--YAML-- --YAML--)],
  15
  16 ## DESCRIPTION
  17
  18 This plugin provides a way of adding arbitrary meta-data (data fields) to any
  19 page by prefixing the page with a YAML-format document.  This also provides
  20 the [[ikiwiki/directive/ymlfront]] directive, which enables one to put
  21 YAML-formatted data inside a standard IkiWiki [[ikiwiki/directive]].
  22
  23 This is a way to create per-page structured data, where each page is
  24 treated like a record, and the structured data are fields in that record.  This
  25 can include the meta-data for that page, such as the page title.
  26
  27 This plugin is meant to be used in conjunction with the [[field]] plugin.
  28
  29 ## DETAILS
  30
  31 There are three formats for adding YAML data to a page.  These formats
  32 should not be mixed - the result is undefined.
  33
  34 1. ymlfront directive
  35
  36    See [[ikiwiki/directive/ymlfront]] for more information.
  37
  38 2. default YAML-compatible delimiter
  39
  40    By default, the YAML-format data in a page is placed at the start of
  41    the page and delimited by lines containing precisely three dashes.
  42    This is what YAML itself uses to delimit multiple documents.
  43    The "normal" content of the page then follows.
  44
  45    For example:
  46
  47         ---
  48         title: Foo does not work
  49         Urgency: High
  50         Status: Assigned
  51         AssignedTo: Fred Nurk
  52         Version: 1.2.3
  53         ---
  54         When running on the Sprongle system, the Foo function returns incorrect data.
  55
  56    What will normally be displayed is everything following the second line of dashes.  That will be htmlized using the page-type of the page-file.
  57
  58 3. user-defined delimiter
  59
  60    Instead of using the default "---" delimiter, the user can define,
  61    in the configuration file, the **ymlfront_delim** value, which is an
  62    array containing two strings. The first string defines the markup for
  63    the start of the YAML data, and the second string defines the markip
  64    for the end of the YAML data. These two strings can be the same, or
  65    they can be different. In this case, the YAML data section is not
  66    required to be at the start of the page, but as with the default, it
  67    is expected that only one data section will be on the page.
  68
  69    For example:
  70
  71         --YAML--
  72         title: Foo does not work
  73         Urgency: High
  74         Status: Assigned
  75         AssignedTo: Fred Nurk
  76         Version: 1.2.3
  77         --YAML--
  78         When running on the Sprongle system, the Foo function returns incorrect data.
  79
  80    What will normally be displayed is everything outside the delimiters,
  81    both before and after.  That will be htmlized using the page-type of the page-file.
  82
  83 ### Accessing the Data
  84
  85 There are a few ways to access the given YAML data.
  86
  87 * [[getfield]] plugin
  88
  89   The **getfield** plugin can display the data as individual variable values.
  90
  91   For example:
  92
  93         ---
  94         title: Foo does not work
  95         Urgency: High
  96         Status: Assigned
  97         AssignedTo: Fred Nurk
  98         Version: 1.2.3
  99         ---
 100         # {{$title}}
 101
 102         **Urgency:** {{$Urgency}}\\
 103         **Status:** {{$Status}}\\
 104         **Assigned To:** {{$AssignedTo}}\\
 105         **Version:** {{$Version}}
 106
 107     When running on the Sprongle system, the Foo function returns incorrect data.
 108
 109 * [[ftemplate]] plugin
 110
 111   The **ftemplate** plugin is like the [[plugins/template]] plugin, but it is also aware of [[field]] values.
 112
 113   For example:
 114
 115         ---
 116         title: Foo does not work
 117         Urgency: High
 118         Status: Assigned
 119         AssignedTo: Fred Nurk
 120         Version: 1.2.3
 121         ---
 122         \[[!ftemplate id="bug_display_template"]]
 123
 124         When running on the Sprongle system, the Foo function returns incorrect data.
 125
 126 * [[report]] plugin
 127
 128   The **report** plugin is like the [[ftemplate]] plugin, but it reports on multiple pages, rather than just the current page.
 129
 130 * write your own plugin
 131
 132   In conjunction with the [[field]] plugin, you can write your own plugin to access the data.
 133
 134 ## PREREQUISITES
 135
 136     IkiWiki
 137     IkiWiki::Plugin::field
 138     YAML::Any
 139
 140 ## DOWNLOAD
 141
 142 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/ymlfront.pm>
 143 * git repo at git://github.com/rubykat/ikiplugins.git