Hooks in Mercury
Mercury modules are written to be self-contained. They are also written to be accomodate situations where one module wants to execute some code at a certain point within the execution of another module. Examples of when this might occur are: when a new user account is created, when a user logs in, when an order is place in the online store, when a user comment is made. A custom module might need to insert some rows into a table when a new user is created or load some variables into the session scope when a user logs in. A custom module might push an online order to another server when an order is made. A custom module might check to make sure that user comments don't contain bad language. In all of these cases the original modules can accomodate these requests without even knowing what calls need to be made. All they have to do is say that "hey, something might want to happen here".
This is accomplished through the use of hooks.
How Does a Module Prepare for Hooks?
Mercury contains a function h( ) that on its own does nothing. Call it like this:
h("module/filename/conditional", $variable);
When this function is executed Mercury looks in two locations to see if any files are waiting to be called. The first is html/mercury/hooks/module/filename/conditional/ and the second is mercury/hooks/module/filename/conditional/. Most of the time these locations will contain no files and nothing will happen.
If one or more files exist in one of those locations Mercury will first check to see if the specific file SHOULD be executed and, if so, will execute it. How does Mercury determine if the hook should be executed? All files will be named according to modules. To see if a file called mymodule.php should be executed when found in a hook location Mercury will check for the existance of a file called html/mercury/mymodule/.enabled and if it finds it the file will execute. The reason that hook files are not automatically executed is inspired by the admin module. Most sites will not need admin controls for every single core module. The navigation for the admin area is built using hooks and it is easy for a developer to control which modules show up in admin for a given site simply by controlling the .enabled files.
What Should a Module Pass into a Hook as a Variable?
It's hard to say. If a module has just created a new user then the variable passed into the hook will likely be either the new user id or an array containing user information. If the hook occurs at the end of a successful ecommerce order then the variable might be the order id. In most cases the composition of the variable that gets passed will be completely obvious. It is the responsibility of the original module to insert hooks and it is the responsibility of the original module to pass data that makes sense.