The Hooks Admin Tool is where you create and change hooks, or event triggers. Hooks are associated with events in Scoop, such as when a comment is posted or somebody creates a new account, and trigger some code that will do something based on what the event was. This provides similar but different functionality to the Cron Admin Tool (A.14), the difference being that cron items are run on a timed basis, while hooks are run based on the activities of users and administrators.
The hooks included with Scoop are all disabled, but are set up as an example. Each row in the hooks table displays the event that will trigger an action and the function or box that performs that action.
The table has five columns, with one row for each hook definition. The last row contains form elements where you can define new hooks. Below the table is a list of actions that can be performed on the hook definitions.
The first column is a checkbox, used to select existing hooks for an action as described below.
The second column is the event the hook is bound to. The list of available hooks is in the variable hooks. Hooks cannot be added arbitrarily to this list; a corresponding run_hook command must be present at the appropriate place in the code.
The third column is the name of the function or box run when the event in the second column happens. This can be a built-in function, such as the log_activity function used in the included hooks, or it can be a box which you write yourself.
The fourth column indicates whether or not the function named in the third column is a box or not.
The fifth column indicates whether or not the hook is enabled. A disabled hook will be skipped when the event it's associated with occurs.
The actions are:
A given event may have as many functions or boxes associated with it as you like, but the functions should not depend on each other because you have no control over the order in which the functions are run.
Each event passes different parameters to the function or box that handles it. These parameters are listed beside the event name in both the variable hooks and in the drop-down box in the Hooks Admin Tool table. Although not listed explicitly, the name of the event is always the first parameter given to the function or box. This allows one function to handle several hooks, as the log_activity function does, by tailoring its response to the hook which triggered it.
When writing a box to handle a hook, then, the first line should be, using comment_new(sid,cid) as an example:
my ($hookname, $sid, $cid) = @ARGS;
The arguments are used to identify exactly what has happened. For comment_new, the sid (story ID) and cid (comment ID) uniquely identify every comment ever posted.
For more information on writing boxes, see section 5.