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