]> sipb.mit.edu Git - ikiwiki.git/blob - doc/plugins/contrib/ymlfront.mdwn
ymlfront: backend for structured data
[ikiwiki.git] / 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 three 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 * write your own plugin
87
88   In conjunction with the [[field]] plugin, you can write your own plugin to access the data.
89
90 ## PREREQUISITES
91
92     IkiWiki
93     IkiWiki::Plugin::field
94     YAML::Any
95
96 ## DOWNLOAD
97
98 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/ymlfront.pm>
99 * git repo at git://github.com/rubykat/ikiplugins.git