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 ## DESCRIPTION
  14
  15 This plugin provides a way of adding arbitrary meta-data (data fields) to any
  16 page by prefixing the page with a YAML-format document.  This also provides
  17 the [[ikiwiki/directive/ymlfront]] directive, which enables one to put
  18 YAML-formatted data inside a standard IkiWiki [[ikiwiki/directive]].
  19
  20 This is a way to create per-page structured data, where each page is
  21 treated like a record, and the structured data are fields in that record.  This
  22 can include the meta-data for that page, such as the page title.
  23
  24 This plugin is meant to be used in conjunction with the [[field]] plugin.
  25
  26 ## DETAILS
  27
  28 If one is not using the ymlfront directive, the YAML-format data in a page
  29 must be placed at the start of the page and delimited by lines containing
  30 precisely three dashes.  The "normal" content of the page then follows.
  31
  32 For example:
  33
  34     ---
  35     title: Foo does not work
  36     Urgency: High
  37     Status: Assigned
  38     AssignedTo: Fred Nurk
  39     Version: 1.2.3
  40     ---
  41     When running on the Sprongle system, the Foo function returns incorrect data.
  42
  43 What will normally be displayed is everything following the second line of dashes.
  44 That will be htmlized using the page-type of the page-file.
  45
  46 ### Accessing the Data
  47
  48 There are a few ways to access the given YAML data.
  49
  50 * [[getfield]] plugin
  51
  52   The **getfield** plugin can display the data as individual variable values.
  53
  54   For example:
  55
  56         ---
  57         title: Foo does not work
  58         Urgency: High
  59         Status: Assigned
  60         AssignedTo: Fred Nurk
  61         Version: 1.2.3
  62         ---
  63         # {{$title}}
  64
  65         **Urgency:** {{$Urgency}}\\
  66         **Status:** {{$Status}}\\
  67         **Assigned To:** {{$AssignedTo}}\\
  68         **Version:** {{$Version}}
  69
  70     When running on the Sprongle system, the Foo function returns incorrect data.
  71
  72 * [[ftemplate]] plugin
  73
  74   The **ftemplate** plugin is like the [[plugins/template]] plugin, but it is also aware of [[field]] values.
  75
  76   For example:
  77
  78         ---
  79         title: Foo does not work
  80         Urgency: High
  81         Status: Assigned
  82         AssignedTo: Fred Nurk
  83         Version: 1.2.3
  84         ---
  85         \[[!ftemplate id="bug_display_template"]]
  86
  87         When running on the Sprongle system, the Foo function returns incorrect data.
  88
  89 * [[report]] plugin
  90
  91   The **report** plugin is like the [[ftemplate]] plugin, but it reports on multiple pages, rather than just the current page.
  92
  93 * write your own plugin
  94
  95   In conjunction with the [[field]] plugin, you can write your own plugin to access the data.
  96
  97 ## PREREQUISITES
  98
  99     IkiWiki
 100     IkiWiki::Plugin::field
 101     YAML::Any
 102
 103 ## DOWNLOAD
 104
 105 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/ymlfront.pm>
 106 * git repo at git://github.com/rubykat/ikiplugins.git