title: Hooks
parent: Webber
ctime: 2009-06-26

= At Startup =

== addoptions ==

Can be used by plugins to add their own command line options.

"`params.parser`" contains the "`optparse`" based parser.

Example:

	:::python
	@set_hook("addoptions")
	def test_addoptions(params):
		params.parser.add_option("-V", "--test_verbose", action="count",
			dest="test_verbose", default=0,
			help="print status messages to stdout")

== checkconfig ==

After the command-line options have been processed and incorporated into
config object, this hook is called. Here each plugin can check if the
specified configurations are sane.

* "`params`" is empty, you should use "`cfg`" directly:

Example:

	:::python
	@set_hook("checkconfig")
	def test_checkconfig(params):
		if cfg.test_verbose:
			print "WARNING: I'll be now much more noisy"
		# I could also directly modify the configuration:
		cfg.foo = "mooh"

== start ==

This hook is called just before walking the directory tree.

* "`params`" is empty:

Example:

	:::python
	@set_hook("start")
	def test_start(params):
		print "in start hook"


= While reading source files =

== read ==

Now webber walks the directory tree specified in "`cfg.in_dir"`, excluding
anything from "`cfg.exclude_dir`" and "`cfg.exclude_file"`. For each of the
remaining files this hook is called.

Usually the the "`read_*`" plugins implement this hook. And usually they look
at the file-extension and decide if they the can procecess this file or not.
If they do, the plugin should also set "`file.render`" is normally "`html"`.
However, it can be something else. In this case "`file.render`" specifies a
hook that get's called for this file.

The first hook that returns contents wins, no other hooks will be called.

* "`params.direc`" contains a "`class Directory`" object
* "`params.file`" contains a "`class File`" object

Example:

	:::python
	@set_hook("read")
	def read(params):
		file = params.file
		if file.rel_path.endswith(".html"):
			file.render = "html"
			f = file.read_keywords()
			return f.read()

== filter ==

Any file that got read will be filtered. At this stage the text is still in the
original format.

Currently no webber-supplied plugin implements this.

* "`params.direc`" contains a "`class Directory`" object
* "`params.file`" contains a "`class File`" object
* "`params.contents`" contains the text

Example:

	:::python
	@set_hook("filter")
	def filter(params):
		params.content = params.content.replace("e", "EEEEE")


= After reading files =

At this stage all pages and their meta-information has been read. Now we can
generate additional data, e.g. page hierarchy, tag-clouds, lists of recently
changed files, etc. This is done via the following two hooks.

The webber-supplied plugin [[hierarchy]] uses this
mechanism.

== scan ==

This hook is called once per file with contents:

* "`params.direc`" contains a "`class Directory`" object
* "`params.file`" has a "`class File`" object
* "`params.file.contents`" contains the text

== scan_done ==

Finally one "`scan_done`" hook is called. The plugin [[hierarchy]]
uses this to sort links.

* "`params`" is empty.

= While rendering files =

The following hooks are called for each file that has a rendered in
"`file.render`" set. See the "`read"`-hook in how to set it.

If "`file.render`" is "`html"`, then the hooks "`htmlize"`, "`linkify`" and
"`pagetemplate`" are run in this order. Otherwise the hook specified
in "`file.render`" is called.

== htmlize ==

This hook converts contents into HTML.

The first hook that returns HTML, no other hooks will be called.

* "`params.direc`" contains a "`class Directory`" object
* "`params.file`" has a "`class File`" object
* "`params.file.contents`" contains the text

== linkify ==

This hook should contain any link to html. Implemented by the plugin
[[link]].

* "`params.direc`" contains a "`class Directory`" object
* "`params.file`" has a "`class File`" object
* "`params.file.contents`" contains the HTML for the body text of the page

== pagetemplate ==

The implementation for this is responsible to generate the final html page,
ready to be written. Implemented by [[template_mako]] plugin.

The first hook that returns a finished HTML page, no other hooks will be
called.

* "`params.direc`" contains a "`class Directory`" object
* "`params.file`" has a "`class File`" object
* "`params.file.contents`" contains the HTML for the body text of the page

== copyfile ==

This is one local hook, run instead of the "`htmlize"`, "`linkify`" and
"`pagetemplate`" hooks. It's defined and implemented by the plugin
[[read_copyonly]].

The first hook that returs anything wins, no other hooks will be called.

* "`params.direc`" contains a "`class Directory`" object
* "`params.file`" has a "`class File`" object

= At the end =

Now everythings has been converted to HTML and written out. And we're just
one hook away from finishing webber:

== finish ==

This hook is called at the end of webber's execution. No webber-supplied
plugin uses it currently, but you could use this to save local state into some
file.

* "`params`" is empty
