rest2web: Building Websites Across the Known Universe

- rest2web
- >
- Reference
- >
- Plugins

# The rest2web plugin System

## Roll Your Own Features

# Plugins

Note

The plugin system is not yet production ready.

The main problem is that plugins currently have to return encoded byte strings in the same encoding as the content. This is fine so long as you can gurantee that the output of your plugin can always be expressed in the encoding of your content !

I also haven't implemented support for global plugins.

- XXXX __init__ should call start !
- XXXX document that changes to uservalues will have inconsistent results - don't do it !

The plugin system allows you to integrate your own functionality into rest2web. You can use this to implement plugins that process pages or generate their output in ways too complex for the templates.

Plugins can either be global, or just applied to individual pages.

You create plugins by writing a class that inherits from `rest2web.PluginClass.PluginClass`, place it in a module in the plugins directory, and configure your pages/site to use it.

An example of a plugin that works for individual pages would be a gallery - creating pages from directories of images.

An example of a global plugin could be a sitemap generator or a search engine that indexes every page.

## The Basic Principle

Your plugin name is the module name. So `gallery.py` is the `gallery` plugin. You module must contain a class called `Plugin` - this will be imported when it is first used.

Your plugin class only needs to implement the relevant methods. For a global plugin this will include the `start` and `end` methods. For a normal plugin you might only need to implement the `page` method.

Note

You shouldn't override the `__init__` method. Use `start` instead.

Each page specifies which normal plugins are being used (in the restindex). Each of the plugins (which may not be any of course), plus all the global ones, are called for every page.

What this means is that the `page` method of your `Plugin` class is called - and passed the parameters :

    page(self, content, encoding, filepath, targetr, estindex, uservalues)

This means that if you want to pass values or settings from the page to the plugin, they can be specified in the uservalues.

The page method (when it has done it's work) should return a tuple of :

    (content, encoding, newvalues)

newvalues is a dictionary that is used to update the uservalues. The values you return here can be used as variables in your page.

When it is first initialised, every plugin is given a reference to the processor object and the original config file. You can access this from within your plugin methods using :

processor = self.processor
config = self.config
#
# config is a dictionary like object
value = config['value']

This means two things :

1. Global plugins can have universal settings in the site config file.

2. You can access the processor attributes like `dir`, `dir_as_url`, etc.

       dir = self.processor.dir

## Global Plugins

When you run rest2web, global plugins are initialised (and their `start` method is called). They are then called for every page.

A global plugin can implement any of the `start`, `page`, and `end` methods. You only need to implement the methods you are using.

from rest2web.PluginClass import PluginClass
class Plugin(PluginClass):
def start(self):
"""
Called when the plugin is initialised.
For global plugins, this is when rest2web starts up.
"""
pass
def end(self):
"""
Called after the last page has been rendered.
Only for global plugins.
"""
pass
def page(self, content, filepath, target, encoding, restindex, uservalues):
"""
Called for every page with globals.
"""
newvalues = {}
return (content, encoding, newvalues)

## Normal Plugins

A normal plugin will only be used for individual pages. You specify plugins to use on a page with the `plugins` keyword in the restindex :

    plugins: gallery, plugin2

Normal plugins can implement the `start` and `page` methods.

from rest2web.PluginClass import PluginClass
class Plugin(PluginClass):
def start(self):
"""
Called when the plugin is initialised.
For normal plugins, this is when they are first used.
"""
pass
def page(self, content, encoding, filepath, target, restindex, uservalues):
"""
Called only for pages using the plugin.
"""
newvalues = {}
return (content, encoding, newvalues)

For an example of this kind of plugin, have a look at the gallery plugin.

# The Page Method

Todo....

# Encoding Issues

Todo...

Return to Top
Part of the rest2web Docs
Page last modified Mon Apr 3 19:30:38 2006.

- Index Page
- Pages
- Smilies
- uservalues
- Encodings
- Plugins
- TODO/ISSUES
- indextree
- Gallery
- changelog