Introduction [edit section]

{{TableOfContents}}= Introduction =TBWiki supports two kinds of extension mechanisms:  "macros" and "processors".

There are a few builtin macros, but add-on macros and processorscan be created and are "run" when a page is parsed and sent by TBWiki.

The function of both of these extension mechanisms (or plugins) isto allow for dynamic creation of page content at the time a pageis read by a user.  Thus, these act like a kind of embedded CGI-scriptinside of the TBWiki framework.

In general, Macros are used for simple transformations of contentor for page-related content creation.  Processors are for doingmore complicated processing of page or wiki data, possibly requiringconfiguration settings or multiple interactions with the user.

Name and Location [edit section]

= Name and Location =By convention, the name of a processor is in CamelCase (words strungtogether with the first letter of each word capitalized).

Plugin processors are placed in the ``data/plugin``directory.  They are python files and must have a filename starting withthe "Processor", then the processor name, and ending in the extension".py".  For example the  "Foo" processor would have the path and filename``/data/plugin/ProcessorFoo.py``

Declaration in a TBWiki Page [edit section]

= Declaration in a TBWiki Page =A processor is declared on a tbwiki page with the syntax:{{{{{{#!Fooconfiguration linesand content lines}} }}}}

The processor name in the declaration must match thename part of the filename for the processor modulein the plugin directory.  The lines inside the processorblock can consist of anything, and are parsed and processedby the processor itself.  (That is, they are not interpretedby TBWiki engine, and are specific to the processor being invoked.)

Interface from TBWiki to the processor [edit section]

= Interface from TBWiki to the processor =A processor must be an importable python module, with some specifically-namedfunction definitions.  The TBWiki calls functions in the processor to performactions, usually resulting the transformation or creation of new content thatwill be returned to the user as part of the page where the processor isdeclared.

main() function [edit section]

== main() function ==A processor must define a function called "main()".  As a page is rendered by TBWIKI, when the processor definition is encountered in the wiki page, TBWikicalls the 'main' function to invoke the processor functionality.

This "main" function takes two arguments, which arethe request object and the content block string.

The processor operates on (i.e. processes) the content data, possibly using theinformation and functions provided in the request object, andreturns a string of HTML data, for output as part of the returned page.

The block containing the processor declaration inside the page isreplaced by TBWiki with the result of executing the processor.

help() function [edit section]

== help() function ==If a processor defines the special function "help()", then the system canprovide online help for the processor, for a page displaying the SystemInfo.This function is accessed via a URL with the name: <page_url>?action=<processor_name>.help

other functions ("action" functions) [edit section]

== other functions ("action" functions) ==In general, any of the functions in the processor can be accessed usinga URL that includes the name of a page that declares the processor, theprocessor name, and the function name.  So if a page "Some_Page" hada declaration of processor "Foo" on it, that defined a function "bar", thenthe URL for causing the invocation of that function would be:

   ../SomePage?action=Foo.bar}}}

{{{   ../SomePage?action=Foo.bar}}}

These are referred to as "action functions" (or just "actions"), in thisdocumentation.

Action functions are used to implement state machines or complexprocessors, which require multiple interactions with the user, orto display multiple pages in sequence (such as a blog or an image gallery).

See the [[#Actions]] section below for more details.

Interface from the processor to TBWiki [edit section]

= Interface from the processor to TBWiki === request object ==The request object has all the data available to tbwiki about the requestfor this page.  This includes the page_name, the entire tbwiki config, andother stuff.

Here are some pertinent data fields that some processors use:

• req.form = the CGI form data for the request (in the format provided by the python cgi module)

 * req.form = the CGI form data for the request (in the format provided by the python cgi module)

• req.page_filename = filename (including full path) of the requested page * req.page_name = name of the requested page * req.config = configuration settings for the wiki * req.config.data_dir = location in the local file system where the data pages are located. * req.data = data values (and data value functions) for this wiki * req.data.version - version of the tbwiki engine * req.data.timestamp - timestamp string for the current time * and many more

 * req.page_filename = filename (including full path) of the requested page * req.page_name = name of the requested page * req.config = configuration settings for the wiki   * req.config.data_dir = location in the local file system where the data     pages are located. * req.data = data values (and data value functions) for this wiki   * req.data.version - version of the tbwiki engine   * req.data.timestamp - timestamp string for the current time   * and many more

req functions [edit section]

== req functions == * req.add_to_message() - a function to add to the status message for the page.      This is often used for debugging purposes, since it appears separately from   the page content * req.html_error() - show a string in red on the page * req.block_to_html() - convert a block of text from tbwiki markup to HTML * req.parse_conf() - used to parse configuration items from a block of text

tbwiki functions [edit section]

== tbwiki functions =In some cases, it is necessary to load the tbwiki_engine module itselfinto the processor module, in order to access global module functionsor data.  Here are some tbwiki_engine functions or data that might be usefulfor a processor: * tbwiki_engine.make_url() * tbiki_engine.parse_state = state used for processing lines during page parsing * tbiki_engine.show_line() = function used to parse a line of TBWIKI-format text and convert it into HTML output (which is printed by show_line)

return value [edit section]

== return value ==The processor's main() function should return a string consisting of HTMLto be output as part of the returned page HTML.

If you want markup processed in the content string, you must process ityourself.  Usually, this means you would do whatever processing on thecontent is appropriate for your processor, then callreq.block_to_html(content), and return the result of that.

Example Processor - FooReplace [edit section]

= Example Processor - FooReplace =Here is sample code for a very simple processor:

FooReplace processor code [edit section]

== FooReplace processor code ==This would be in the file ProcessorFooReplace.py{{{import re

def main(req, content):        result = re.sub("foo", "bar", content)        return result}}}

FooReplace processor invocation [edit section]

== FooReplace processor invocation ==To use this processor, a user would place the following block on a page: