Artifact 01090d9200962b10c5068bd32a9de39f5972db651270040441f4ff7fd030641b:
- File
www/th1-hooks.md
— part of check-in
[93cee1f5]
at
2021-09-17 02:02:44
on branch trunk
— Converted all uses of the obsolete
named anchor feature from HTML before 4.0 to use fragment identifiers
instead. (www/* subtree only.)
Where possible, changed constructs like
<a name="foo"></a><h3>
to<h3 id="foo">
Also fixed a few cases where the link target came after a header so the browser would scroll the header off the screen when visiting the targeted section.
Added a 50em pad at the bottom of one such edited doc to allow the intra-doc link targets to be useful since it's a short enough doc that on sufficiently tall browser windows, scrolling isn't possible, so using those anchors has no visible effect. (user: wyoung size: 6278) [more...]
TH1 Hooks ========= <big><big><big><font color="red">** DRAFT **</font></big></big></big> The **TH1 hooks** feature allows <a href="th1.md">TH1</a> scripts to be configured that can monitor, create, alter, or cancel the execution of Fossil commands and web pages. This feature requires the TH1 hooks feature to be enabled at compile-time. Additionally, the "th1-hooks" repository setting must be enabled at runtime in order to successfully make use of this feature. TH1 Hook Related User-Defined Procedures ---------------------------------------- In order to activate TH1 hooks, one or more of the following user-defined procedures should be defined, generally from within the "th1-setup" script (setting) for a repository. The following bullets summarize the available TH1 hooks: * command\_hook -- _Called before execution of a command._ * command\_notify -- _Called after execution of a command._ * webpage\_hook -- _Called before rendering of a web page._ * webpage\_notify -- _Called after rendering of a web page._ TH1 Hook Related Variables for Commands --------------------------------------- * cmd\_name -- _Name of command being executed._ * cmd\_args -- _Current command line arguments._ * cmd\_flags -- _Bitmask of CMDFLAG values for the command being executed._ TH1 Hook Related Variables for Web Pages ---------------------------------------- * web\_name -- _Name of web page being rendered._ * web\_args -- _Current web page arguments._ * web\_flags -- _Bitmask of CMDFLAG values for the web page being rendered._ <a id="cmdReturnCodes"></a>TH1 Hook Related Return Codes for Commands ----------------------------------------------------------------------- * TH\_OK -- _Command will be executed, notification will be executed._ * TH\_ERROR -- _Command will be skipped, notification will be skipped, error message will be emitted._ * TH\_BREAK -- _Command will be skipped, notification will be skipped._ * TH\_RETURN -- _Command will be executed, notification will be skipped._ * TH\_CONTINUE -- _Command will be skipped, notification will be executed._ For commands that are not included in the Fossil binary, allowing their execution will cause the standard "unknown command" error message to be generated, which will typically exit the process. Therefore, adding a new command generally requires using the TH_CONTINUE return code. <a id="webReturnCodes"></a>TH1 Hook Related Return Codes for Web Pages ------------------------------------------------------------------------ * TH\_OK -- _Web page will be rendered, notification will be executed._ * TH\_ERROR -- _Web page will be skipped, notification will be skipped, error message will be emitted._ * TH\_BREAK -- _Web page will be skipped, notification will be skipped._ * TH\_RETURN -- _Web page will be rendered, notification will be skipped._ * TH\_CONTINUE -- _Web page will be skipped, notification will be executed._ For web pages that are not included in the Fossil binary, allowing their rendering will cause the standard "Not Found" error message to be generated, which will cause an HTTP 404 status code to be sent. Therefore, adding a new web page generally requires using the TH_CONTINUE return code. <a id="triggerReturnCodes"></a>Triggering TH1 Return Codes from a Script -------------------------------------------------------------------------- * TH\_OK -- _This is the default return code, nothing special needed._ * TH\_ERROR -- _Use the **error** command._ * TH\_BREAK -- _Use the **break** command._ * TH\_RETURN -- _Use the **return -code 5** command._ * TH\_CONTINUE -- _Use the **continue** command._ <a id="command_hook"></a>TH1 command_hook Procedure ----------------------------------------------------- * command\_hook This user-defined procedure, if present, is called just before the execution of a command. The name of the command being executed will be stored in the "cmd\_name" global variable. The arguments to the command being executed will be stored in the "cmd\_args" global variable. The associated CMDFLAG value will be stored in the "cmd\_flags" global variable. Before exiting, the procedure should trigger the return <a href="#cmdReturnCodes">code</a> that corresponds to the desired action to take next. <a id="command_notify"></a>TH1 command_notify Procedure --------------------------------------------------------- * command\_notify This user-defined procedure, if present, is called just after the execution of a command. The name of the command being executed will be stored in the "cmd\_name" global variable. The arguments to the command being executed will be stored in the "cmd\_args" global variable. The associated CMDFLAG value will be stored in the "cmd\_flags" global variable. Before exiting, the procedure should trigger the return <a href="#cmdReturnCodes">code</a> that corresponds to the desired action to take next. <a id="webpage_hook"></a>TH1 webpage_hook Procedure ----------------------------------------------------- * webpage\_hook This user-defined procedure, if present, is called just before the rendering of a web page. The name of the web page being rendered will be stored in the "web\_name" global variable. The arguments to the web page being rendered will be stored in the "web\_args" global variable. The associated CMDFLAG value will be stored in the "web\_flags" global variable. Before exiting, the procedure should trigger the return <a href="#webReturnCodes">code</a> that corresponds to the desired action to take next. <a id="webpage_notify"></a>TH1 webpage_notify Procedure --------------------------------------------------------- * webpage\_notify This user-defined procedure, if present, is called just after the rendering of a web page. The name of the web page being rendered will be stored in the "web\_name" global variable. The arguments to the web page being rendered will be stored in the "web\_args" global variable. The associated CMDFLAG value will be stored in the "web\_flags" global variable. Before exiting, the procedure should trigger the return <a href="#webReturnCodes">code</a> that corresponds to the desired action to take next.