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=somepage cgi parameter

• Page 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).

• Konstrukt::Plugin::wiki::markup::definition

• Konstrukt::Plugin::wiki::markup::headline

• Konstrukt::Plugin::wiki::markup::hr

• Konstrukt::Plugin::wiki::markup::list

• Konstrukt::Plugin::wiki::markup::paragraph

• Konstrukt::Plugin::wiki::markup::pre

• Konstrukt::Plugin::wiki::markup::quote

Inline Markup:

All these plugins are derived from the same base class (Konstrukt::Plugin::wiki::inlineplugin).

• Konstrukt::Plugin::wiki::markup::acronym

• Konstrukt::Plugin::wiki::markup::basic

• Konstrukt::Plugin::wiki::markup::htmlescape

• Konstrukt::Plugin::wiki::markup::link

• Konstrukt::Plugin::wiki::markup::replace

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.

• Konstrukt::Plugin::wiki::backend::article::DBI

Images:

Will handle all images (JPEG, PNG, GIF, ...).

The image backends implement the Konstrukt::Plugin::wiki::backend::image interface.

• Konstrukt::Plugin::wiki::backend::image::DBI

Files:

Will handle all other files.

The file backends implement the Konstrukt::Plugin::wiki::backend::file interface.

• Konstrukt::Plugin::wiki::backend::file::DBI

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 pre quote headline hr list definition paragraph
        wiki/inline_plugins link acronym basic replace htmlescape

Note 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 image

You also may specify the backend type to use. Currently only 'DBI' is available, which is also the default:

        wiki/backend_type DBI
        

The 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.html

If no page, that should be displayed, is specified, a default page will be used:

        wiki/default_page index

You 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 0

Rendered 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 75

For further configuration of some submodules take a look at

• "CONFIGURATION" in Konstrukt::Plugin::wiki::markup::link

• "CONFIGURATION" in Konstrukt::Plugin::wiki::markup::replace

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.

convert_markup_string

Will convert a string containing wiki markup into another markup (usually HTML).

Returns a containter node, that in turn contains nodes with the converted markup.

Parameters:

• $markup - The string containing the markup to convert.

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.

SEE ALSO

Konstrukt::Plugin, Konstrukt::Plugin, Konstrukt

cpanm Konstrukt

perl -MCPAN -e shell
install Konstrukt