1TH1 Hooks
2=========
3
4<big><big><big><font color="red">** DRAFT **</font></big></big></big>
5
6The **TH1 hooks** feature allows <a href="th1.md">TH1</a> scripts to be
7configured that can monitor, create, alter, or cancel the execution of
8Fossil commands and web pages.
9
10This feature requires the TH1 hooks feature to be enabled at compile-time.
11Additionally, the "th1-hooks" repository setting must be enabled at runtime
12in order to successfully make use of this feature.
13
14TH1 Hook Related User-Defined Procedures
15----------------------------------------
16
17In order to activate TH1 hooks, one or more of the following user-defined
18procedures should be defined, generally from within the "th1-setup" script
19(setting) for a repository.  The following bullets summarize the available
20TH1 hooks:
21
22  *  command\_hook -- _Called before execution of a command._
23  *  command\_notify -- _Called after execution of a command._
24  *  webpage\_hook -- _Called before rendering of a web page._
25  *  webpage\_notify -- _Called after rendering of a web page._
26
27TH1 Hook Related Variables for Commands
28---------------------------------------
29
30  *  cmd\_name -- _Name of command being executed._
31  *  cmd\_args -- _Current command line arguments._
32  *  cmd\_flags -- _Bitmask of CMDFLAG values for the command being executed._
33
34TH1 Hook Related Variables for Web Pages
35----------------------------------------
36
37  *  web\_name -- _Name of web page being rendered._
38  *  web\_args -- _Current web page arguments._
39  *  web\_flags -- _Bitmask of CMDFLAG values for the web page being rendered._
40
41<a id="cmdReturnCodes"></a>TH1 Hook Related Return Codes for Commands
42-----------------------------------------------------------------------
43
44  *  TH\_OK -- _Command will be executed, notification will be executed._
45  *  TH\_ERROR -- _Command will be skipped, notification will be skipped,
46                  error message will be emitted._
47  *  TH\_BREAK -- _Command will be skipped, notification will be skipped._
48  *  TH\_RETURN -- _Command will be executed, notification will be skipped._
49  *  TH\_CONTINUE -- _Command will be skipped, notification will be executed._
50
51For commands that are not included in the Fossil binary, allowing their
52execution will cause the standard "unknown command" error message to be
53generated, which will typically exit the process.  Therefore, adding a
54new command generally requires using the TH_CONTINUE return code.
55
56<a id="webReturnCodes"></a>TH1 Hook Related Return Codes for Web Pages
57------------------------------------------------------------------------
58
59  *  TH\_OK -- _Web page will be rendered, notification will be executed._
60  *  TH\_ERROR -- _Web page will be skipped, notification will be skipped,
61                  error message will be emitted._
62  *  TH\_BREAK -- _Web page will be skipped, notification will be skipped._
63  *  TH\_RETURN -- _Web page will be rendered, notification will be skipped._
64  *  TH\_CONTINUE -- _Web page will be skipped, notification will be executed._
65
66For web pages that are not included in the Fossil binary, allowing their
67rendering will cause the standard "Not Found" error message to be generated,
68which will cause an HTTP 404 status code to be sent.  Therefore, adding a
69new web page generally requires using the TH_CONTINUE return code.
70
71<a id="triggerReturnCodes"></a>Triggering TH1 Return Codes from a Script
72--------------------------------------------------------------------------
73
74  *  TH\_OK -- _This is the default return code, nothing special needed._
75  *  TH\_ERROR -- _Use the **error** command._
76  *  TH\_BREAK -- _Use the **break** command._
77  *  TH\_RETURN -- _Use the **return -code 5** command._
78  *  TH\_CONTINUE -- _Use the **continue** command._
79
80<a id="command_hook"></a>TH1 command_hook Procedure
81-----------------------------------------------------
82
83  *  command\_hook
84
85This user-defined procedure, if present, is called just before the
86execution of a command.  The name of the command being executed will
87be stored in the "cmd\_name" global variable.  The arguments to the
88command being executed will be stored in the "cmd\_args" global variable.
89The associated CMDFLAG value will be stored in the "cmd\_flags" global
90variable.  Before exiting, the procedure should trigger the return
91<a href="#cmdReturnCodes">code</a> that corresponds to the desired action
92to take next.
93
94<a id="command_notify"></a>TH1 command_notify Procedure
95---------------------------------------------------------
96
97  *  command\_notify
98
99This user-defined procedure, if present, is called just after the
100execution of a command.  The name of the command being executed will
101be stored in the "cmd\_name" global variable.  The arguments to the
102command being executed will be stored in the "cmd\_args" global variable.
103The associated CMDFLAG value will be stored in the "cmd\_flags" global
104variable.  Before exiting, the procedure should trigger the return
105<a href="#cmdReturnCodes">code</a> that corresponds to the desired action
106to take next.
107
108<a id="webpage_hook"></a>TH1 webpage_hook Procedure
109-----------------------------------------------------
110
111  *  webpage\_hook
112
113This user-defined procedure, if present, is called just before the
114rendering of a web page.  The name of the web page being rendered will
115be stored in the "web\_name" global variable.  The arguments to the
116web page being rendered will be stored in the "web\_args" global variable.
117The associated CMDFLAG value will be stored in the "web\_flags" global
118variable.  Before exiting, the procedure should trigger the return
119<a href="#webReturnCodes">code</a> that corresponds to the desired action
120to take next.
121
122<a id="webpage_notify"></a>TH1 webpage_notify Procedure
123---------------------------------------------------------
124
125  *  webpage\_notify
126
127This user-defined procedure, if present, is called just after the
128rendering of a web page.  The name of the web page being rendered will
129be stored in the "web\_name" global variable.  The arguments to the
130web page being rendered will be stored in the "web\_args" global variable.
131The associated CMDFLAG value will be stored in the "web\_flags" global
132variable.  Before exiting, the procedure should trigger the return
133<a href="#webReturnCodes">code</a> that corresponds to the desired action
134to take next.
135