NAME
Konstrukt::Plugin::wiki - Plugin to convert wiki markup and manage wiki content
SYNOPSIS
<& wiki &>
= Headline
some text
<& / &>
<& wiki page="FooBar" / &>DESCRIPTION
This plugin will render given wiki markup into an other format (e.g. HTML).
The markup may come from several sources, which are checked in this order:
Content between
<& wiki &> and<& / &>Page passed through
?wiki_page=somepagecgi parameterPage specified in the tag attribute:
<& wiki page="somepage" / &>Default page set in wiki/default_page
Markup Plugins
The markup will be handled by the markup plugins. An overview of the syntax can be found at Konstrukt::Plugin::wiki::syntax. Below are links to the detailed documentation of each markup plugin.
Block Markup:
All these plugins are derived from the same base class (Konstrukt::Plugin::wiki::blockplugin).
Inline Markup:
All these plugins are derived from the same base class (Konstrukt::Plugin::wiki::inlineplugin).
Backend Plugins
The data will be stored and accessed through various backend plugins. Take a look at their documentation for more information about them (e.g. configuration).
All backend plugins are derived from the base class Konstrukt::Plugin::wiki::backend, which explains what requirements must be fulfilled to build an own backend plugin.
Articles:
Will handle any wiki articles.
The article backends implement the Konstrukt::Plugin::wiki::backend::article interface.
Images:
Will handle all images (JPEG, PNG, GIF, ...).
The image backends implement the Konstrukt::Plugin::wiki::backend::image interface.
Files:
Will handle all other files.
The file backends implement the Konstrukt::Plugin::wiki::backend::file interface.
Note on page titles
You might want to use something like
<title><& param key="wiki_page" &><+$ title $+>(default title)<+$ / $+><& / &></title>in your page layout template to get the title of the wiki pages as your page title. If no wiki_page-param is defined it will default to the title-template value (this may of course vary in your template) supplied for page. If even no title-template value has been specified, the title will default to (default title).
CONFIGURATION
You may (but usually don't want to) configure the processing order of the markup plugins:
#defaults
wiki/block_plugins code quote headline hr list definition paragraph
wiki/inline_plugins link acronym basic replace htmlescapeNote that the block plugins will be executed one after another for each block until one plugin returns a true value, which indicates, that this block plugin handles the passed block. No other block plugin will then handle the block.
The inline plugins will always be executed first to last on the whole text.
You may define more specific configuration for each markup plugin. Take a look at the documentation of those.
To define which backends you want to use, use the following setting. There are several backends (article, image, file, ...), which may be implemented in several types (DBI, file, ...). Each backend has to define, for which action (passed with the action CGI parameter) it is responsible. Take a look at the Konstrukt::Plugin::wiki::backend::*-modules. The default backends which are queried for their action responsibilities are:
wiki/backends article file imageYou also may specify the backend type to use. Currently only 'DBI' is available, which is also the default:
wiki/backend_type DBIThe page, which will be used to display the wiki article, may also be specified. This file is just a plain html file (with konstrukt tags) that must contain a wiki tag:
<& wiki / &>This tag will then be replaced by the wiki page that should be displayed. The default path to this file is:
wiki/base /wiki.htmlIf no page, that should be displayed, is specified, a default page will be used:
wiki/default_page indexYou may also specify the user level, that is required to to write/edit wiki articles. Default:
#every registered user may edit/write articles
wiki/userlevel_write 0Rendered wiki articles get cached to speed up the display. To prevent a collision between other file names and the names of wiki pages in the cache, you can specify a pseudo directory which will be prefixed to the cache names of the wiki pages. Default:
wiki/cache_prefix wiki_article_cache/This plugin uses templates to display forms and messages. The path to these templates can be customized (and should end with a slash). Default:
wiki/template_path /templates/wiki/If you use the image- and file-plugin you must create a file, which returns the content of the file, for each plugin. Actually you can choose any filename you like (e.g. /wiki/file/index.html and /wiki/image/index.html) as it will be referenced in the file and image info template (usually /templates/wiki/layout/file_info.template and image_info.template). These files must only consist of:
<& wiki::backend::image / &>Respectively
<& wiki::backend::file / &>and no other characters (no newlines, no whitespaces)!
The image backend automatically generates resized versions of the images if a specified width is requested. You may specify the quality (0-100, 100 = best) of the compressed (jpeg, mng, png) image. Default:
wiki/image_quality 75For further configuration of some submodules take a look at
For further configuration of the backend modules take a look at the documentation of those.
METHODS
init
Initialization. Will only be used internally.
install
Installs the stylesheet.
Parameters:
none
prepare_again
Yes, this plugin may generate new tag nodes in the prepare run.
execute_again
Yes, this plugin may generate new tag nodes in the execute run.
prepare
This plugin will process static content in the prepare-run.
Parameters:
$tag - Reference to the tag (and its children) that shall be handled.
execute
Finally process the wiki content
Parameters:
$tag - Reference to the tag (and its children) that shall be handled.
convert_markup
Will convert the wiki markups in the child nodes of a given node into another markup (usually HTML).
The input child nodes will be replaced by the converted markup.
Parameters:
$tag - Reference to the tag (and its children) that shall be handled.
postprocess_output
Will run "prepare_templates", "separate_nowiki" and "merge_similar_neighbours" on the passed node.
Parameters:
$node - Node with children to process
prepare_templates
This sub takes a node with some child nodes an recursively prepares all template nodes.
Parameters:
$node - Node with children to process
separate_nowiki
Find <nowiki>...</nowiki>-areas and create separate nodes for them, that will not be processed.
Parameters:
$tag - Reference to the tag (and its children) that shall be handled.
split_into_blocks
Walk over the tree and separate it into blocks (which are separated by at least one empty line).
Each block will be moved under a "block node".
The passed tagnode will only have block nodes below it after this step.
Parameters:
$tag - Reference to the tag (and its children) that shall be handled.
merge_similar_neighbours
Your plugin may/should/must use this method if it splits the text into many nodes that may be of similar type (e.g. two plaintext nodes that are not finally parsed.). The splitted text may lead into wrong/missing recognition of markup and in a little slower processing speed.
So if your plugin puts out many nodes of the same type you may want to use this method to consolidate your output.
It is used by the basic-plugin and the link plugin that do much splitting.
Actually this method merges all plaintext nodes that have the same wiki_finished state. It will not recurse into nodes having children.
This one is quite similar to "merge_similar_neighbours" in Konstrukt::Parser, but it will not recurse, it will care about the wiki_finished flag and it will not care about comment nodes.
Parameters:
$parent - The node whose children should be processed
AUTHOR
Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.
This document is free software. It is distributed under the same terms as Perl itself.