ikiwiki/doc/plugins/contrib/ymlfront.mdwn

107 lines
2.9 KiB
Plaintext
Raw Normal View History

2010-01-13 03:20:34 +01:00
[[!template id=plugin name=ymlfront author="[[rubykat]]"]]
[[!tag type/meta]]
[[!toc]]
## NAME
IkiWiki::Plugin::ymlfront - add YAML-format data to a page
## SYNOPSIS
# activate the plugin
add_plugins => [qw{goodstuff ymlfront ....}],
## DESCRIPTION
This plugin provides a way of adding arbitrary meta-data (data fields) to any
2010-08-06 10:12:11 +02:00
page by prefixing the page with a YAML-format document. This also provides
the [[ikiwiki/directive/ymlfront]] directive, which enables one to put
YAML-formatted data inside a standard IkiWiki [[ikiwiki/directive]].
This is a way to create per-page structured data, where each page is
treated like a record, and the structured data are fields in that record. This
can include the meta-data for that page, such as the page title.
2010-01-13 03:20:34 +01:00
This plugin is meant to be used in conjunction with the [[field]] plugin.
## DETAILS
2010-08-06 10:12:11 +02:00
If one is not using the ymlfront directive, the YAML-format data in a page
must be placed at the start of the page and delimited by lines containing
precisely three dashes. The "normal" content of the page then follows.
2010-01-13 03:20:34 +01:00
For example:
---
title: Foo does not work
Urgency: High
Status: Assigned
AssignedTo: Fred Nurk
Version: 1.2.3
---
When running on the Sprongle system, the Foo function returns incorrect data.
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.
### Accessing the Data
2010-08-06 10:12:11 +02:00
There are a few ways to access the given YAML data.
2010-01-13 03:20:34 +01:00
* [[getfield]] plugin
The **getfield** plugin can display the data as individual variable values.
For example:
---
title: Foo does not work
Urgency: High
Status: Assigned
AssignedTo: Fred Nurk
Version: 1.2.3
---
# {{$title}}
**Urgency:** {{$Urgency}}\\
**Status:** {{$Status}}\\
**Assigned To:** {{$AssignedTo}}\\
**Version:** {{$Version}}
When running on the Sprongle system, the Foo function returns incorrect data.
* [[ftemplate]] plugin
The **ftemplate** plugin is like the [[plugins/template]] plugin, but it is also aware of [[field]] values.
For example:
---
title: Foo does not work
Urgency: High
Status: Assigned
AssignedTo: Fred Nurk
Version: 1.2.3
---
\[[!ftemplate id="bug_display_template"]]
When running on the Sprongle system, the Foo function returns incorrect data.
* [[report]] plugin
The **report** plugin is like the [[ftemplate]] plugin, but it reports on multiple pages, rather than just the current page.
2010-01-13 03:20:34 +01:00
* write your own plugin
In conjunction with the [[field]] plugin, you can write your own plugin to access the data.
## PREREQUISITES
IkiWiki
IkiWiki::Plugin::field
YAML::Any
## DOWNLOAD
* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/ymlfront.pm>
* git repo at git://github.com/rubykat/ikiplugins.git