Fossil SCM

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

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button