- Introduction
- Defining the extensions
- code-span
- code-break
- edit-question
- render-bottom-div
- render-bottom-span
- Example
- Properties passed to extensions
- Functions available for extensions
Introduction
Svnwiki lets users extend the functionality it provides by the means of extensions. Extensions are Scheme files that are copied to the extensions/ directory of the data directories of the wikis they are enabled on. This document describes the programming interface for creating extensions.
Defining the extensions
Your extensions file needs to define the *extensions* symbol. It should be bound to an alist, where the car is a name and the cdr is itself an alist with properties associated to the name.
Example:
(define *extensions*
`((foo ,properties-foo)
(bar ,properties-bar)))Each entry in the list corresponds to one particular extension. The name (foo and bar in the example) is used to identify the extension. The properties alist defines functions for your extension. The car in the entries in the alist should be one type of extension (code-span, code-break, edit-question, render-bottom-div, render-bottom-span) and the cadr should be the function.
For example, if your foo extension wants to have function foo-function called to produce content right after a page from the wiki is rendered, you would do:
(define *extensions* `((foo (render-bottom-span ,foo-function))))
code-span
code-break
edit-question
render-bottom-div
render-bottom-span
Example
The following extension would translate a string of the form <example> ... </example> into <enscript highlight=scheme> ... </enscript> and have the results parsed recursively.
(require-extension stream-ext srfi-40 format-modular)
(define (example params text props)
((cadr (assoc 'parse props))
(stream-append
(string->stream "
")
text
(string->stream "
"))))
(define *extensions*
`((example (code-span ,example))
(comment (code-span ,(constantly stream-null)))))code-span
Defines a function that will be called by svnwiki whenever it finds an opening tag with the name given followed by some text and its associated closing tag. For example, if the extension has
(define *extensions* `((foo (code-span ,some-function))))
and svnwiki comes across the text
<foo bar=yes>example</foo> ,
it will call some-function. The values for code-span must always be procedures receiving the following three arguments:
- params
- An assoc list with the parameters found in the opening tag. In this list names are passed as symbols and values as streams of characters. In the example above, it would be ((bar (stream #\y #\e #\s))).
- text
- A stream of characters with the text found between the opening and closing tags ("example", in the example above).
- props
- An assoc list with a table of useful procedures that the extension can use. Its contents are described in #Properties passed to extensions.
The procedure must return a stream of characters it wants to replace the text (and the opening and closing tags) with. Keep in mind that functions will not only get called to generate HTML output but also other formats; as such, they shouldn't output HTML tags directly (but rather call the functions that generate output for the current format).
update
Defines a function that will be called by svnwiki whenever a file changes inside a directory that has the svnwiki:handler property set to the name given. For example, if the extension has
(define *extensions* `((gallery (update ,some-function))))
and a file changes in a directory where svnwiki:handler set to gallery, svnwiki will call some-function. The values for update must always be procedures receiving a props argument, which is an assoc list with the contents described in #Properties passed to extensions.
The return value of this procedure is ignored.
Properties passed to extensions
The props argument passed to procedures in extensions is an assoc list with the objects described in this section. To obtain one of them, you'd usually use:
(cadr (assoc 'object props))
parse
Procedure that receives a stream of characters and parses it recursively, looking for wiki markup and converting it into its equivalent stream (in the current output format).
path-in
Path to a directory with a local copy with the repository for the wiki.
path-out
Path to the directory where the HTML output is being rendered to.
base
path
user
password
db
linktypes
extensions
Functions available for extensions
svnwiki-make-pathname
write-file-with-tmp
render-template
render-file-contents
Last update: 2007-02-27 (Rev 10706)