D 2015-02-09T02:48:55.946
L TH1-Hooks
N text/x-markdown
P c1f97dfec07d2d75739326b758d7a6ae7b7c81b0
U mario
W 2451
Since Fossil 1.30 it's possible to extend both the CLI and web interface with new functionality / or gimmicks. Use `--with-th1-hooks` for compilation and the `th1-hooks` repo setting. Extension callbacks must reside in the <kbd>th1-setup</kbd> setting field .
## Web hooks
Simply craft a `webpage_hook` function.
proc webpage_hook {} {
puts $::web_name;
continue;
}
The global var `$::web_name` is populated with the currently requested pagename. It can be one of the built-in functions (wiki, index, home, artifact, etc) or a new custom name. It should preferrably only engage for custom URL paths of course.
An accompanying `webpage_notify` can be defined, which would be called *after* page processing.
proc webpage_notify {} {
# Everything went well
}
#### Order
* `webpage_hook` is always invoked first.
* Fossils built-in pages thereafter, if no `break` was used or `TH_ERROR` caused.
* `webpage_notify` runs last, when `continue`, `return` or `TH_OK` were returned from the `_hook` callback.
#### Vars
* The vars `$::web_args` and `$::web_flags` are seldomly useful here, as they and just inherit `fossil server/ui/cgi` startup args.
* Use `set name [getParameter name ""]` instead to get URL params. (The first path info argument to after URL command name will be applied, or a `?name=` param looked up.)
## CLI command hooks
The same process applies to `command_hook` (called first) and `command_notify` (called after internal command processing). The variable names `$::cmd_name`, `$::cmd_args`, `$::$cmd_flags` are in particular useful to implement new and custom `fossil mycmd` stuff.
## Examples in <kbd>hooks.th1</kbd>
The [hooks.th1 feature](wiki/features) setup script currently defines three web hooks:
* `/changelog` will output a NEWS-style timeline/changelog.
* `/cat/filename` ought to output the latest checkin with the given filename. It's intended as simpler alternative to `/raw/fn?name=uuid`. It doesn't work yet due to `CONTENT()` being inavailable in TH1 queries for security reasons.
* `/uri-list` instead outputs local paths for each filename to `/raw/fn?name=uuid`.
To apply them for testing, use:
fossil setting th1-setup "$(cat *.th1)"
(Or copy it in per Admin UI > Settings. Note that fossil ui/server needs to be restarted, because the th1-setup code is only evaluated once.)
Z ad4e4cd60d285ae1a1bba18fe46ecb4c