![]() |
The rest2web plugin SystemRoll Your Own FeaturesPluginsNote 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.
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 PrincipleYour 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 :
Global PluginsWhen 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 PluginsA 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 MethodTodo.... Encoding IssuesTodo... Return to Top |