Home | Trees | Index | Help |
---|
Package docs :: Module ReadMeForPlugins |
|
README
for Plugins and Plugin writing
Inside the contrib/
directory, you'll see the
plugins/
directory. To install a given plugin, move the
plugin file you want from the contrib/
directory to the
Pyblosxom/plugins/
directory of your installation.
Some plugins take effect immediately, like the
conditionalhttp.py
and the statusnotfound.py
.
Some plugins require some setup before they work. Read the plugin file in
a text editor to see what installation steps are required.
Below is documentation for plugin developers detailing the standard callbacks that they can use to implement plugins.
Implementing a callback in a plugin
If you want to implement a callback, you add a function corresponding to the callback name to your plugin module. For example, if you wanted to modify theRequest
object just before rendering, you'd
implement cb_prepare something like this:
def cb_prepare(args): pass
Each callback passes in arguments through a single dictionary. Each callback passes in different arguments and expects different return values. Consult the documentation for the callback you're seeking before implementing it in your code to understand what it does and how to use it.
The BlosxomRenderer plugin callbacks
The BlosxomRenderer
plugins are based on the blosxom 2.0
callbacks. The names of the arguments are different, but the callbacks
are called at the same points that the blosxom 2.0 callbacks are called
and serve the same function.
cb_head
(corresponds to blosxom 2.0
head)
cb_date_head
(corresponds to blosxom
2.0 date)
cb_story
(corresponds to blosxom 2.0
story)
cb_foot
(corresponds to blosoxm 2.0
foot)
cb_filelist
cb_prepare
cb_prepare
See the callback documentation below for more details.
verify_installation
As of PyBlosxom 0.9, the pyblosxom.cgi is able to test your PyBlosxom installation. It verifies certain items in your config file and also loads all the plugins and lets them verify their configuration as well.
At the prompt, you would run:./pyblosxom.cgi
It tells you your Python version, OS name, and then proceeds to verify your config properties (did you specify a valid datadir? does it exist?...) and then initializes all your plugins and executes verify_installation(request) on every plugin you have installed that has the function.
As a plugin developer, you should add a verify_installation function to your plugin module. Something like this (taken from pycategories):def verify_installation(request): config = request.getConfiguration() if not config.has_key("category_flavour"): print "missing optional config property 'category_flavour' which allows " print "you to specify the flavour for the category link. refer to " print "pycategory plugin documentation for more details." return 1
Basically this gives you (the plugin developer) the opportunity to walk the user through configuring your highly complex, quantum-charged, turbo plugin in small baby steps without having to hunt for where their logs might be.
So check the things you need to check, print out error messages (informative ones), and then return a 1 if the plugin is configured correctly or a 0 if it's not configured correctly.
This is not a substitute for reading the installation instructions. But it should be a really easy way to catch a lot of potential problems without involving the web server's error logs and debugging information being sent to a web-browser and things of that nature.Function Summary | |
---|---|
dict |
The date_head callback is called before a date_head flavour template is rendered. |
None |
The start callback allows plugins to execute teardown/cleanup code, save any data that hasn't been saved, clean up temporary files, and otherwise return the system to a normal state. |
dict |
The entryparser callback allows plugins to register the entryparsers they have. |
list |
The filelist callback allows plugins to generate the list of entries to be rendered. |
dict |
The filestat callback allows plugins to override the mtime of the entry. |
dict |
The foot callback is called before the variables in the entry are substituted into the foot template. |
dict |
The head callback is called before a head flavour template is rendered. |
None |
The logrequest callback is used to notify plugins of the current PyBlosxom request for the purposes of logging. |
None |
The pathinfo callback allows plugins to parse the HTTP PATH_INFO item. |
The postformat callback allows plugins to make further modifications to entry text. | |
string |
The preformat callback acts in conjunction with the entryparser that handled the entry to do a two-pass formatting of the entry. |
None |
The prepare callback is called in the default blosxom handler after we've figured out what we're rendering and before we actually go to the renderer. |
object instace |
The renderer callback allows plugins to specify a renderer to use by returning a renderer instance to use. |
None |
The start callback allows plugins to execute startup/initialization code. |
dict |
The story callback gets called before the entry is rendered. |
dict |
The story_end callback is is called after the variables in the entry are substituted into the template. |
Function Details |
---|
cb_date_head(args)The date_head callback is called before a date_head flavour template is rendered.
Blosxom 2.0 calls this callback 'date'. Functions that implement this callback will get an args dict containing:
|
cb_end(args)The start callback allows plugins to execute teardown/cleanup code, save any data that hasn't been saved, clean up temporary files, and otherwise return the system to a normal state. Examples of usage:
Functions that implement this callback don't need to return anything. Note: The cb_end callback is called for every PyBlosxom request regardless of whether it's handled by the default blosxom handler. This is slightly different than blosxom.
|
cb_entryparser(entryparsingdict)The entryparser callback allows plugins to register the entryparsers they have. Entry parsers are linked with a filename extension. For example, the default blosxom text entry parser will be used for any file ending in ".txt". Functions that implement this callback will get the entryparser dict consisting of file extension -> entry parsing function pairs. Functions that implement this callback should return the entryparser dict after modifying it. A bit about entry parsing functions Entry parsing functions take in a filename and the
import os def cb_entryparser(entryparsingdict): """ Register self as plain file handler """ entryparsingdict['plain'] = parse return entryparsingdict def parse(filename, request): """ We just read everything off the file here, using the filename as title """ entryData = {} entryData['title'] = os.path.basename(filename) entryData['story'] = open(filename).read() return entryData
|
cb_filelist(args)The filelist callback allows plugins to generate the list of entries
to be rendered. Entries should be
|
cb_filestat(args)The filestat callback allows plugins to override the mtime of the entry. One of the contributed plugins uses this to set the mtime to the time specified in the entry's filename. Functions that implement this callback will get an args dict containing:
|
cb_foot(args)The foot callback is called before the variables in the entry are substituted into the foot template. This is the place to modify the foot template based on the entry content. You have access to all the content variables via entry. Blosxom 2.0 calls this callback 'foot'. Functions that implement this callback will get an args dict containing:
|
cb_head(args)The head callback is called before a head flavour template is rendered.
Blosxom 2.0 calls this callback 'head'. Functions that implement this callback will get an args dict containing:
Functions that implement this callback must return the input args dict whether or not they adjust anything in it. Example in which we add the number of entries being rendered to the $blog_title variable:def cb_head(args): request = args["request"] config = request.getConfiguration() data = request.getData() num_entries = len(data.get("entry_list", [])) config["blog_title"] = config.get("blog_title", "") + ": %d entries" % num_entries return args
|
cb_logrequest(args)The logrequest callback is used to notify plugins of the current PyBlosxom request for the purposes of logging. Functions that implement this callback will get an args dict containing:
Functions that implement this callback can return whatever they want--it doesn't affect the callback chain. cb_logrequest is called after rendering and will contain all the
modifications to the {'filename': filename, 'return_code': '200', 'request': Request()}
|
cb_pathinfo(args)The pathinfo callback allows plugins to parse the HTTP PATH_INFO item. This item is stored in the http dict of theRequest
object. Functions would parse this as they desire, then set the
following variables in the data dict of the Request
object:
'bl_type' (dir|file) 'pi_bl' typically the same as PATH_INFO 'pi_yr' yyyy 'pi_mo' (mm|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) 'pi_da' dd 'root_datadir' full path to the entry folder or entry file on filesystem 'flavour' The flavour gathered from the URLFunctions that implement this callback will get an args dict containing:
|
cb_postformat(args)The postformat callback allows plugins to make further modifications to entry text. It typically gets called after a preformatter by the entryparser. It can also be used to add additional properties to entries. The changes from postformat functions are saved in the cache (if the user has caching enabled). As such, this shouldn't be used for dynamic data like comment counts. Examples of usage:
'entry_data' dict are done
in place.
|
cb_preformat(args)The preformat callback acts in conjunction with the entryparser that handled the entry to do a two-pass formatting of the entry. Functions that implement cb_preformat are text transformation tools. Once one of them returns a transformed entry, then we stop processing. Functions that implement this callback will get an args dict containing:
Functions that implement this callback should return None if they didn't modify the story or a single story string. A typical preformat plugin look like:def cb_preformat(args): if args['parser'] == 'linebreaks': return parse(''.join(args['story'])) def parse(text): # A preformatter to convert linebreak to its HTML counterpart text = re.sub('\n\n+','</p><p>',text) text = re.sub('\n','<br />',text) return '<p>%s</p>' % text
|
cb_prepare(args)The prepare callback is called in the default blosxom handler after we've figured out what we're rendering and before we actually go to the renderer. Plugins should implement cb_prepare to modify the data dict which is
in the
Functions that implement this callback can return whatever they want--it doesn't affect the callback chain. Example of acb_prepare function in a plugin:
def cb_prepare(args): """ This plugin shows the number of entries we are going to render and place the result in $countNoOfEntries. """ request = args['request'] data = request.getData() config = request.getConfiguration() # Can anyone say Ternary? :) IF = lambda a,b,c:(a() and [b()] or [c()])[0] num_entry = config['num_entries'] entries = len(data['entry_list']) data['countNoOfEntries'] = IF(num_entry > entries, num_entry, entries)
|
cb_renderer(args)The renderer callback allows plugins to specify a renderer to use by returning a renderer instance to use. If no renderer is specified, we use the default blosxom renderer. Functions that implement this callback will get an args dict containing:
|
cb_start(args)The start callback allows plugins to execute startup/initialization code. Use this callback for any setup code that your plugin needs, like:
Note: The cb_start callback is slightly different than in blosxom in that cb_start is called for every PyBlosxom request regardless of whether it's handled by the default blosxom handler. In general, it's better to delay allocating resources until you absolutely know you are going to use them. Functions that implement this callback will get an args dict containing:
|
cb_story(args)The story callback gets called before the entry is rendered. The template used is typically the story template, but we allow entries to override this if they have a "template" property. If they have the "template" property, then we'll use that template instead.
Blosxom 2.0 calls this callback 'story'. Functions that implement this callback will get an args dict containing:
|
cb_story_end(args)The story_end callback is is called after the variables in the entry are substituted into the template. You have access to all the content variables via entry. Functions that implement this callback will get an args dict containing:
|
Home | Trees | Index | Help |
---|
Generated by Epydoc 2.1 on Wed Apr 6 19:17:06 2005 | http://epydoc.sf.net |