Fossil Skins Extra: TH1-Hooks

Help

Since Fossil 1.30 it's possible to extend both the CLI and web interface with new pages or commands. Use --with-th1-hooks for compilation and enable the th1-hooks repo setting. Extension callbacks must reside in the th1-setup settings 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 after the URLs 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).

 proc command_hook {} {
 }
 proc command_notify {} {
   if {$::cmd_name eq "push"} {
     puts "PUSHED\n"
   }
 }

The variable names $::cmd_name, $::cmd_args, $::$cmd_flags are in particular useful to implement new and custom fossil mycmd actions.

Transfer scripts

Less general, but there's also Admin > Transfers for setting up some TH1 scripts on specific actions (Push, Commit, Ticket).

Examples in `hooks.th1`

The hooks.th1 feature 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.

TCL binding

For running external commands, Fossil needs to be built with TCL support. Then running external tools becomes as simple as:

tclInvoke exec ./script.sh &

Another common alternative is invoking a CGI handler:

http "http://localhost/cgi-bin/whatever"

TH1-Hooks