|
1
|
TH1 Hooks |
|
2
|
========= |
|
3
|
|
|
4
|
<big><big><big><font color="red">** DRAFT **</font></big></big></big> |
|
5
|
|
|
6
|
The **TH1 hooks** feature allows <a href="th1.md">TH1</a> scripts to be |
|
7
|
configured that can monitor, create, alter, or cancel the execution of |
|
8
|
Fossil commands and web pages. |
|
9
|
|
|
10
|
This feature requires the TH1 hooks feature to be enabled at compile-time. |
|
11
|
Additionally, the "th1-hooks" repository setting must be enabled at runtime |
|
12
|
in order to successfully make use of this feature. |
|
13
|
|
|
14
|
TH1 Hook Related User-Defined Procedures |
|
15
|
---------------------------------------- |
|
16
|
|
|
17
|
In order to activate TH1 hooks, one or more of the following user-defined |
|
18
|
procedures should be defined, generally from within the "th1-setup" script |
|
19
|
(setting) for a repository. The following bullets summarize the available |
|
20
|
TH1 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
|
|
|
27
|
TH1 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
|
|
|
34
|
TH1 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
|
|
|
51
|
For commands that are not included in the Fossil binary, allowing their |
|
52
|
execution will cause the standard "unknown command" error message to be |
|
53
|
generated, which will typically exit the process. Therefore, adding a |
|
54
|
new 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
|
|
|
66
|
For web pages that are not included in the Fossil binary, allowing their |
|
67
|
rendering will cause the standard "Not Found" error message to be generated, |
|
68
|
which will cause an HTTP 404 status code to be sent. Therefore, adding a |
|
69
|
new 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
|
|
|
85
|
This user-defined procedure, if present, is called just before the |
|
86
|
execution of a command. The name of the command being executed will |
|
87
|
be stored in the "cmd\_name" global variable. The arguments to the |
|
88
|
command being executed will be stored in the "cmd\_args" global variable. |
|
89
|
The associated CMDFLAG value will be stored in the "cmd\_flags" global |
|
90
|
variable. Before exiting, the procedure should trigger the return |
|
91
|
<a href="#cmdReturnCodes">code</a> that corresponds to the desired action |
|
92
|
to take next. |
|
93
|
|
|
94
|
<a id="command_notify"></a>TH1 command_notify Procedure |
|
95
|
--------------------------------------------------------- |
|
96
|
|
|
97
|
* command\_notify |
|
98
|
|
|
99
|
This user-defined procedure, if present, is called just after the |
|
100
|
execution of a command. The name of the command being executed will |
|
101
|
be stored in the "cmd\_name" global variable. The arguments to the |
|
102
|
command being executed will be stored in the "cmd\_args" global variable. |
|
103
|
The associated CMDFLAG value will be stored in the "cmd\_flags" global |
|
104
|
variable. Before exiting, the procedure should trigger the return |
|
105
|
<a href="#cmdReturnCodes">code</a> that corresponds to the desired action |
|
106
|
to take next. |
|
107
|
|
|
108
|
<a id="webpage_hook"></a>TH1 webpage_hook Procedure |
|
109
|
----------------------------------------------------- |
|
110
|
|
|
111
|
* webpage\_hook |
|
112
|
|
|
113
|
This user-defined procedure, if present, is called just before the |
|
114
|
rendering of a web page. The name of the web page being rendered will |
|
115
|
be stored in the "web\_name" global variable. The arguments to the |
|
116
|
web page being rendered will be stored in the "web\_args" global variable. |
|
117
|
The associated CMDFLAG value will be stored in the "web\_flags" global |
|
118
|
variable. Before exiting, the procedure should trigger the return |
|
119
|
<a href="#webReturnCodes">code</a> that corresponds to the desired action |
|
120
|
to take next. |
|
121
|
|
|
122
|
<a id="webpage_notify"></a>TH1 webpage_notify Procedure |
|
123
|
--------------------------------------------------------- |
|
124
|
|
|
125
|
* webpage\_notify |
|
126
|
|
|
127
|
This user-defined procedure, if present, is called just after the |
|
128
|
rendering of a web page. The name of the web page being rendered will |
|
129
|
be stored in the "web\_name" global variable. The arguments to the |
|
130
|
web page being rendered will be stored in the "web\_args" global variable. |
|
131
|
The associated CMDFLAG value will be stored in the "web\_flags" global |
|
132
|
variable. Before exiting, the procedure should trigger the return |
|
133
|
<a href="#webReturnCodes">code</a> that corresponds to the desired action |
|
134
|
to take next. |
|
135
|
|