TB Wiki

Login

DocProcessors

Problem importing plugins
no macro 'TableOfContents' found

Introduction [edit section]

TBWiki supports two kinds of extension mechanisms: "macros" and "processors".

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

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

Name and Location [edit section]

By convention, the name of a processor is in CamelCase (words strung together 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 with the "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]

A processor is declared on a tbwiki page with the syntax:
{{{#!ProcessorName
argument lines
and content
}} }

The processor name in the declaration must match the first part of the filename for the processor module in the plugin directory. The lines inside the processor block can consist of anything.

Interface from TBWiki to the processor [edit section]

A processor must be an importable python module, and it must have a function with the same name as the processor. Thus, the "FooProcessor.py" module must have a function named "Foo". This is the function TBWiki will call to invoke the processor functionality.

This main processor function must take two arguments, which are the request object and the content.

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

Essentially, the block of processor text inside the page is replaced with the result of executing the processor.

Interface from the processor to TBWiki [edit section]

request object [edit section]

The request object has all the data available to tbwiki about the request for this page. This includes the page_name, the entire tbwiki config, and other 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.add_to_message = a function to add to the status message for the page. This is often usef for debugging purposes, since it appears separately from the page content
  • req.page_filename = filename (including full path) of the requested page
  • req.page_name = name of the requested page
  • req.config.data_dir = location in the local file system where the data pages are located.

tbwiki functions [edit section]

  • tbwiki_engine.make_url
  • tbiki_engine.html_error
  • 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]

The processor function should return a single string consisting of HTML to be output as part of the returned page HTML.

Sample [edit section]

FIXTHIS - add a processor example here

TBWiki engine by Tim Bird