The inline directive is supplied by the inline plugin.

This is a directive that allows including one wiki page inside another. The most common use of inlining is generating blogs and RSS or Atom feeds.

Example:

[[!inline  pages="blog/* and !*/Discussion" limit="10" rootpage="blog"]]

Any pages that match the specified PageSpec (in the example, any SubPage of "blog") will be part of the blog, and the newest 10 of them will appear in the page. Note that if files that are not pages match the PageSpec, they will be included in the feed using RSS enclosures, which is useful for simple podcasting; for fuller-featured podcast feeds, enclose media files in blog posts using meta.

The optional rootpage parameter tells the wiki that new posts to this blog should default to being SubPages of "blog", and enables a form at the top of the blog that can be used to add new items.

If you want your blog to have an archive page listing every post ever made to it, you can accomplish that like this:

[[!inline  pages="blog/* and !*/Discussion" archive="yes"]]

You can even create an automatically generated list of all the pages on the wiki, with the most recently added at the top, like this:

[[!inline  pages="* and !*/Discussion" archive="yes"]]

If you want to be able to add pages to a given blog feed by tagging them, you can do that too. To tag a page, just make it link to a page or pages that represent its tags. Then use the special link() PageSpec to match all pages that have a given tag:

[[!inline  pages="link(life)"]]

Or include some tags and exclude others:

[[!inline  pages="link(debian) and !link(social)"]]

usage

There are many parameters you can use with the inline directive. These are the commonly used ones:

• pages - A PageSpec of the pages to inline.
• limit - Specify the maximum number of matching pages to inline. Default is 10, unless archiving, when the default is to show all. Set to 0 to show all matching pages. In older versions of IkiWiki this parameter was called show, which also still works.
• archive - If set to "yes", only list page titles and some metadata, not full contents.
• title - Sets the title of the rss feed if one is generated. Defaults to the name of the page.
• description - Sets the description of the rss feed if one is generated. Defaults to the name of the wiki.
• skip - Specify a number of pages to skip displaying. Can be useful to produce a feed that only shows archived pages.
• postform - Set to "yes" to enable a form to post new pages to a blog.
• postformtext - Set to specify text that is displayed in a postform.
• rootpage - Enables the postform, and allows controling where newly posted pages should go, by specifiying the page that they should be a SubPage of.

Here are some less often needed parameters:

• actions - If set to "yes" add links to the bottom of the inlined pages for editing and discussion (if they would be shown at the top of the page itself).
• rss - controls generation of an rss feed. If the wiki is configured to generate rss feeds by default, set to "no" to disable. If the wiki is configured to allowrss, set to "yes" to enable.
• atom - controls generation of an atom feed. If the wiki is configured to generate atom feeds by default, set to "no" to disable. If the wiki is configured to allowatom, set to "yes" to enable.
• feeds - controls generation of all types of feeds. Set to "no" to disable generating any feeds.
• emptyfeeds - Set to "no" to disable generation of empty feeds. Has no effect if rootpage or postform is set.
• id - Set to specify the value of the HTML id attribute for the feed links or the post form. Useful if you have multiple forms in the same page.
• template - Specifies the template to fill out to display each inlined page. By default the inlinepage template is used, while the archivepage template is used for archives. Set this parameter to use some other, custom template, such as the titlepage template that only shows post titles or the microblog template, optimised for microblogging. Note that you should still set archive=yes if your custom template does not include the page content.
• raw - Rather than the default behavior of creating a blog, if raw is set to "yes", the page will be included raw, without additional markup around it, as if it were a literal part of the source of the inlining page.
• sort - Controls how inlined pages are sorted. The default is to sort the newest created pages first, and if pages were created in the same commit, sort them by the name of the page (equivalent to sort="age title").
• reverse - If set to "yes", causes the sort order to be reversed.
• feedlimit - Specify the maximum number of matching pages to include in the rss/atom feeds. The default is the same as the limit value above. In older versions of IkiWiki this parameter was called feedshow, which also still works.
• feedonly - Only generate the feed, do not display the pages inline on the page.
• quick - Build archives in quick mode, without reading page contents for metadata. This also turns off generation of any feeds.
• timeformat - Use this to specify how to display the time or date for pages in the blog. The format string is passed to the strftime(3) function.
• feedpages - A PageSpec of inlined pages to include in the rss/atom feeds. The default is the same as the pages value above, and only pages matched by that value are included, but some of those can be excluded by specifying a tighter PageSpec here.
• guid - If a URI is given here (perhaps a UUID prefixed with urn:uuid:), the Atom feed will have this as its <id>. The default is to use the URL of the page containing the inline directive.
• feedfile - Can be used to change the name of the file generated for the feed. This is particularly useful if a page contains multiple feeds. For example, set "feedfile=feed" to cause it to generate page/feed.atom and/or page/feed.rss. This option is not supported if the wiki is configured not to use usedirs.
• pagenames - If given instead of pages, this is interpreted as a space-separated list of absolute page names (LinkingRules are not taken into account), and they are inlined in exactly the order given: the sort and pages parameters cannot be used in conjunction with this one.
• trail - If set to "yes" and the trail plugin is enabled, turn the inlined pages into a trail with next/previous links, by passing the same options to trailitems. The skip and limit options are ignored by the trail, so the next/previous links traverse through all matching pages.

The trailitems directive is supplied by the trail plugin. It adds pages to the trail represented by the current page, without producing any output on that page.

[[!trailitems  pages="posts/*" sort="age"]]

[[!trailitems  pagenames="a b c"]]

Options are similar to inline:

• pages: adds pages that match a PageSpec to the trail (cannot be used with pagenames)

• pagenames: if used instead of pages, this is interpreted as a space-separated list of absolute page names (LinkingRules are not taken into account) to add to the trail

• sort: add the pages matched by pages to the trail in this sorting order (cannot be used with pagenames)

• reverse: reverse the order of sort (cannot be used with pagenames)

The graph directive is supplied by the graphviz plugin.

This directive allows embedding graphviz graphs in a page. Example usage:

[[!graph  src="a -> b -> c; a -> c;"]]

Nodes on the graph can link to external urls using regular graphviz syntax, and a clickable imagemap will be created. As a special extension for ikiwiki, WikiLinks can also be used. For example:

[[!graph  src="""
google [ href="http://google.com/" ]
sandbox [ href=[[SandBox]] ]
help [ href=[[ikiwiki/formatting]] ]
newpage [ href=[[NewPage]] ]

google -> sandbox -> help -> newpage -> help -> google;
"""]]

The graph directive supports the following parameters:

• src - The graphviz source to render.
• file - A file in the wiki containing the graphviz source.
• type - The type of graph to render: graph or digraph. Defaults to digraph.
• prog - The graphviz program to render with: dot, neato, fdp, twopi, or circo. Defaults to dot.
• height, width - Limit the size of the graph to a given height and width, in inches. You must specify both to limit the size; otherwise, graphviz will choose a size, without any limit.

The ymlfront directive is supplied by the ymlfront plugin.

This directive allows the user to define arbitrary meta-data in YAML format.

[[!ymlfront  data="""
 foo: fooness
 bar: The Royal Pigeon
 baz: 2
 """]]

There is one argument to this directive.

• data: The YAML-format data. This should be enclosed inside triple-quotes to preserve the data correctly.

If more than one ymlfront directive is given per page, the result is undefined. Likewise, it is inadvisable to try to mix the non-directive ymlfront format with the directive form of the data.

The xslt directive is supplied by the xslt plugin.

This directive processes an input XML data file with XSLT, and outputs the result in the page where the directive was called.

[[!xslt  file="data1.xml" stylesheet="style1.xsl"]]

There are two arguments to this directive.

• file: The file which contains XML data to be processed. This file must have a .xml extension (filename.xml). This file is searched for using the usual IkiWiki mechanism, thus finding the file first in the same directory as the page, then in the directory above, and so on.

• stylesheet: The file which contains XSLT stylesheet to apply to the XML data. This file must have a .xsl extension (filename.xsl). This file is searched for using the usual IkiWiki mechanism, thus finding the file first in the same directory as the page, then in the directory above, and so on.

It is expected that the XSLT stylesheet will output valid HTML markup.

The report directive is supplied by the report plugin.

This enables one to report on the structured data ("field" values) of multiple pages; the output is formatted via a template. This depends on the ?field plugin.

The pages to report on are selected by a PageSpec given by the "pages" parameter. The template is given by the "template" parameter. The template expects the data from a single page; it is applied to each matching page separately, one after the other.

Additional parameters can be used to fill out the template, in addition to the "field" values. Passed-in values override the "field" values.

There are two places where template files can live. One is in the /templates directory on the wiki. These templates are wiki pages, and can be edited from the web like other wiki pages.

The second place where template files can live is in the global templates directory (the same place where the page.tmpl template lives). This is a useful place to put template files if you want to prevent them being edited from the web, and you don't want to have to make them work as wiki pages.

OPTIONS

template: The template to use for the report.

pages: A PageSpec to determine the pages to report on.

pagenames: If given instead of pages, this is interpreted as a space-separated list of links to pages, and they are shown in exactly the order given: the sort and pages parameters cannot be used in conjunction with this one. If they are used, they will be ignored.

trail: A page or pages to use as a "trail" page.

When a trail page is used, the matching pages are limited to (a subset of) the pages which that page links to; the "pages" pagespec in this case, rather than selecting pages from the entire wiki, will select pages from within the set of pages given by the trail page.

Additional space-separated trail pages can be given in this option. For example:

trail="animals/cats animals/dogs"

This will take the links from both the "animals/cats" page and the "animals/dogs" page as the set of pages to apply the PageSpec to.

start: Start the report at the given page-index; the index starts from zero.

count: Report only on N pages where count=N.

sort: A SortSpec to determine how the matching pages should be sorted.

here_only: Report on the current page only.

This is useful in combination with "prev_" and "next_" variables to make a navigation trail. If the current page doesn't match the pagespec, then no pages will be reported on.

Headers

An additional option is the "headers" option. This is a space-separated list of field names which are to be used as headers in the report. This is a way of getting around one of the limitations of HTML::Template, that is, not being able to do tests such as "if this-header is not equal to previous-header".

Instead, that logic is performed inside the plugin. The template is given parameters "HEADER1", "HEADER2" and so on, for each header. If the value of a header field is the same as the previous value, then HEADER*N* is set to be empty, but if the value of the header field is new, then HEADER*N* is given that value.

Example

Suppose you're writing a blog in which you record "moods", and you want to display your blog posts by mood.

[[!report  template="mood_summary"
pages="blog/*"
sort="Mood Date title"
headers="Mood"]]

The "mood_summary" template might be like this:

<TMPL_IF NAME="HEADER1">
## <TMPL_VAR NAME="HEADER1">
</TMPL_IF>
### <TMPL_VAR NAME="TITLE">
(<TMPL_VAR NAME="DATE">) [[<TMPL_VAR NAME="PAGE">]]
<TMPL_VAR NAME="DESCRIPTION">

Multi-page Reports

Reports can now be split over multiple pages, so that there aren't too many items per report-page.

per_page: how many items to show per report-page.

first_page_is_index: If true, the first page of the report is just an index which contains links to the other report pages. If false, the first page will contain report-content as well as links to the other pages.

Advanced Options

The following options are used to improve efficiency when dealing with large numbers of pages; most people probably won't need them.

maketrail:

Make a trail; if true, then this report is called in "scan" mode and the pages which match the pagespec are added to the list of links from this page. This can be used by another report by setting this page to be a "trail" page in that report.

It is not possible to use "trail" and "maketrail" at the same time. By default, "maketrail" is false.

TEMPLATE PARAMETERS

The templates are in HTML::Template format, just as ?template and ftemplate are. The parameters passed in to the template are as follows:

Fields

The structured data from the current matching page. This includes "title" and "description" if they are defined.

Common values

Values known for all pages:

• page (the current page)
• destpage (the destination page)
• basename (the base name of the page)
• recno (N if the page is the Nth page in the report)

Prev_Page And Next_Page

The "prev_page" and "next_page" variables will give the value of the previous page in the matching pages, or the next page in the matching pages. This is mainly useful for a "here_only" report.

Passed-in values

Any additional parameters to the report directive are passed to the template; a parameter will override the matching "field" value. For example, if you have a "Mood" field, and you pass Mood="bad" to the report, then that will be the Mood which is given for the whole report.

Generally this is useful if one wishes to make a more generic template and hide or show portions of it depending on what values are passed in the report directive call.

For example, one could have a "hide_mood" parameter which would hide the "Mood" section of your template when it is true, which one could use when the Mood is one of the headers.

Headers

See the section on Headers.

First and Last

If this is the first page-record in the report, then "first" is true. If this is the last page-record in the report, then "last" is true.

The jssearchfield directive is supplied by the jssearchfield plugin.

This enables one to search the structured data ("field" values) of multiple pages. A search form is constructed, and the searching is done with Javascript, which means that the entire thing is self-contained. This depends on the plugins/contrib/field plugin.

The pages to search are selected by a PageSpec given by the "pages" parameter. The fields to search are given by the "fields" parameter. By default, the field name is given, and the user can type the search parameter for that field into a text input field.

OPTIONS

pages: A PageSpec to determine the pages to search through.

fields: The fields to put into the search form, and to display in the results.

tagfields: Display the given fields as a list of tags that can be selected from, rather than having a text input field. Every distinct value of that field will be listed, so it is best used for things with short values, like "Author" rather than long ones like "Description". Note that "tagfields" must be a subset of "fields".

sort: A SortSpec to determine how the matching pages should be sorted; this is the "default" sort order that the results will be displayed in. The search form also gives the option of "random" sort, which will display the search results in random order.

SEARCHING

The search form that is created by this directive contains the following:

• for each search field, a label, plus either a text input field, or a list of checkboxes with values next to them if the field is also a tagfield. Note that the lists of checkboxes are initially hidden; one must click on the triangle next to the label to display them.
• a "sort" toggle. One can select either "default" or "random".
• A "Search!" button, to trigger the search if needed (see below)
• A "Reset" button, which will clear all the values.

The searching is dynamic. As soon as a value is changed, either by tabbing out of the text field, or by selecting or de-selecting a checkbox, the search results are updated. Furthermore, for tagfields, the tagfield lists themselves are updated to reflect the current search results.

The ftemplate directive is supplied by the ftemplate plugin.

This is like the template directive, with the addition that one does not have to provide all the values in the call to the template, because ftemplate can query structured data ("fields") using the ?field plugin.

Templates are files that can be filled out and inserted into pages in the wiki, by using the ftemplate directive. The directive has an id parameter that identifies the template to use.

Additional parameters can be used to fill out the template, in addition to the "field" values. Passed-in values override the "field" values.

There are two places where template files can live. One is in the /templates directory on the wiki. These templates are wiki pages, and can be edited from the web like other wiki pages.

The second place where template files can live is in the global templates directory (the same place where the page.tmpl template lives). This is a useful place to put template files if you want to prevent them being edited from the web, and you don't want to have to make them work as wiki pages.

EXAMPLES

Example 1

PageA:

[[!meta  title="I Am Page A"]]
[[!meta  description="A is for Apple."]]
[[!meta  author="Fred Nurk"]]
[[!ftemplate  id="mytemplate"]]

Template "mytemplate":

# <TMPL_VAR NAME="TITLE">
by <TMPL_VAR NAME="AUTHOR">

**Summary:** <TMPL_VAR NAME="DESCRIPTION">

This will give:

<h1>I Am Page A</h1>
<p>by Fred Nurk</p>
<p><strong>Summary:</strong> A is for Apple.

Example 2: Overriding values

PageB:

[[!meta  title="I Am Page B"]]
[[!meta  description="B is for Banana."]]
[[!meta  author="Fred Nurk"]]
[[!ftemplate  id="mytemplate" title="Bananananananas"]]

This will give:

<h1>Bananananananas</h1>
<p>by Fred Nurk</p>
<p><strong>Summary:</strong> B is for Banana.

Example 3: Loops

(this example uses the ?ymlfront plugin)

Page C:

---
BookAuthor: Georgette Heyer
BookTitle: Black Sheep
BookGenre:
  - Historical
  - Romance
---
[[ftemplate id="footemplate"]]

I like this book.

Template "footemplate":

# <TMPL_VAR BOOKTITLE>
by <TMPL_VAR BOOKAUTHOR>

<TMPL_IF BOOKGENRE>(
<TMPL_LOOP GENRE_LOOP><TMPL_VAR BOOKGENRE>
<TMPL_UNLESS __last__>, </TMPL_UNLESS>
</TMPL_LOOP>
)</TMPL_IF>

This will give:

<h1>Black Sheep</h1>
<p>by Georgette Heyer</p>

<p>(Historical, Romance)</p>

<p>I like this book.</p>

LIMITATIONS

One cannot query the values of fields on pages other than the current page. If you want to do that, check out the ?report plugin.

[[!template Error: failed to process template <span class="createlink"><a href="/ikiwiki.cgi?do=create&amp;from=ikiwiki%2Fdirective%2Ffield&amp;page=%2Ftemplates%2Fplugin" rel="nofollow">?</a>plugin</span> template plugin not found ]]

NAME

IkiWiki::Plugin::field - front-end for per-page record fields.

SYNOPSIS

# activate the plugin
add_plugins => [qw{goodstuff field ....}],

# simple registration
field_register => [qw{meta}],

# simple registration with priority
field_register => {
meta => 'last'
foo => 'DD'
},

# allow the config to be queried as a field
field_allow_config => 1,

# flag certain fields as "tags"
field_tags => {
BookAuthor => '/books/authors',
BookGenre => '/books/genres',
MovieGenre => '/movies/genres',
}

DESCRIPTION

This plugin is meant to be used in conjunction with other plugins in order to provide a uniform interface to access 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.

Plugins can register a function which will return the value of a "field" for a given page. This can be used in a few ways:

• In page templates; all registered fields will be passed to the page template in the "pagetemplate" processing.
• In PageSpecs; the "field" function can be used to match the value of a field in a page.
• In SortSpecs; the "field" function can be used for sorting pages by the value of a field in a page.
• By other plugins, using the field_get_value function, to get the value of a field for a page, and do with it what they will.

CONFIGURATION OPTIONS

The following options can be set in the ikiwiki setup file.

field_allow_config

field_allow_config => 1,

Allow the $config hash to be queried like any other field; the keys of the config hash are the field names with a prefix of "CONFIG-".

field_register

field_register => [qw{meta}],

field_register => {
meta => 'last'
foo => 'DD'
},

A hash of plugin-IDs to register. The keys of the hash are the names of the plugins, and the values of the hash give the order of lookup of the field values. The order can be 'first', 'last', 'middle', or an explicit order sequence between 'AA' and 'ZZ'. If the simpler type of registration is used, then the order will be 'middle'.

This assumes that the plugins in question store data in the %pagestatus hash using the ID of that plugin, and thus the field values are looked for there.

This is the simplest form of registration, but the advantage is that it doesn't require the plugin to be modified in order for it to be registered with the "field" plugin.

field_tags

field_tags => {
BookAuthor => '/books/authors',
BookGenre => '/books/genres',
MovieGenre => '/movies/genres',
}

A hash of fields and their associated pages. This provides a faceted tagging system.

The way this works is that a given field-name will be associated with a given page, and the values of that field will be linked to sub-pages of that page, the same way that the [[!tag ]] directive does.

This also provides a field with the suffix of -tagpage which gives the name of the page to which that field-value is linked.

For example:

BookGenre: SF

will link to "/books/genres/SF", with a link-type of "bookgenre".

If one was using a template, then the following template:

Genre: <TMPL_VAR BOOKGENRE>
GenrePage: <TMPL_VAR BOOKGENRE-TAGPAGE>
GenreLink: [[<TMPL_VAR BOOKGENRE-TAGPAGE>]]

would give:

Genre: SF
GenrePage: /books/genres/SF
GenreLink: <a href="/books/genres/SF/">SF</a>

PageSpec

The field plugin provides a few PageSpec functions to match values of fields for pages.

• field
  • field(name glob)
  • field(bar Foo*) will match if the "bar" field starts with "Foo".
• destfield
  • destfield(name glob)
  • as for "field" but matches against the destination page (i.e when the source page is being included in another page).
• field_item
  • field_item(name glob)
  • field_item(bar Foo) will match if one of the values of the "bar" field is "Foo".
• destfield_item
  • destfield_item(name glob)
  • as for "field_item" but matches against the destination page.
• field_null
  • field_null(name)
  • matches if the field is null, that is, if there is no value for that field, or the value is empty.
• field_tagged
  • field_tagged(name glob)
  • like tagged, but this uses the tag-bases and link-types defined in the field_tags configuration option.
• destfield_tagged
  • destfield_tagged(name glob)
  • as for "field_tagged" but matches against the destination page.

SortSpec

The "field" SortSpec function can be used to sort a page depending on the value of a field for that page. This is used for directives that take sort parameters, such as inline or report.

field(name)

For example:

sort="field(bar)" will sort by the value og the "bar" field.

Additionally, the "field_natural" SortSpec function will use the Sort::Naturally module to do its comparison (though it will fail if that module is not installed).

FUNCTIONS

field_register

field_register(id=>$id);

Register a plugin as having field data. The above form is the simplest, where the field value is looked up in the %pagestatus hash under the plugin-id.

Additional Options:

call=>&myfunc

A reference to a function to call rather than just looking up the value in the %pagestatus hash. It takes two arguments: the name of the field, and the name of the page. It is expected to return (a) an array of the values of that field if "wantarray" is true, or (b) a concatenation of the values of that field if "wantarray" is not true, or (c) undef if there is no field by that name.

sub myfunc ($$) {
my $field = shift;
my $page = shift;

...

return (wantarray ? @values : $value);
}

first=>1

Set this to be called first in the sequence of calls looking for values. Since the first found value is the one which is returned, ordering is significant. This is equivalent to "order=>'first'".

last=>1

Set this to be called last in the sequence of calls looking for values. Since the first found value is the one which is returned, ordering is significant. This is equivalent to "order=>'last'".

order=>$order

Set the explicit ordering in the sequence of calls looking for values. Since the first found value is the one which is returned, ordering is significant.

The values allowed for this are "first", "last", "middle", or a two-character ordering-sequence between 'AA' and 'ZZ'.

field_get_value($field, $page)

my $value = field_get_value($field, $page);

my $value = field_get_value($field, $page, foo=>'bar');

Returns the value of the field for that page, or undef if none is found. It is also possible to override the value returned by passing in a value of your own.

DOWNLOAD

• browse at GitHub: http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/field.pm
• git repo at git://github.com/rubykat/ikiplugins.git