Hooks - Extending the Framework Core

revIgniter's hooks feature provides a means to tap into and modify the inner workings of the framework without hacking the core files. When revIgniter runs it follows a specific execution process, diagramed in the Application Flow page. There may be instances, however, where you'd like to cause some action to take place at a particular stage in the execution process. For example, you might want to run a script right before your controllers get loaded, or right after, or you might want to trigger one of your own scripts in some other location.

Enabling Hooks

The hooks feature can be globally enabled/disabled by setting the following item in the application/config/config.lc file:

put TRUE into gConfig["enableHooks"]

Defining a Hook

Hooks are defined in the application/config/hooks.lc file. Each hook is specified as an array with this prototype:

	put "MyHandler" into gHooks["preController"]["handler"]
	put "MyScript.lc" into gHooks["preController"]["filename"]
	put "hooks" into gHooks["preController"]["filepath"]
	put "beer" into gHooks["preController"]["params"][1]
	put "wine" into gHooks["preController"]["params"][2]
	put "snacks" into gHooks["preController"]["params"][3]

Notes:
The array index correlates to the name of the particular hook point you want to use. In the above example the hook point is preController. A list of hook points is found below. The following items should be defined in your associative hook array:

handler The handler name you wish to call. If you call a function, append a pair of brackets to the name like: "MyHandler()".
filename The file name containing your handler.
filepath The name of the directory containing your script. Note: Your script must be located in a directory INSIDE your application folder, so the file path is relative to that folder. For example, if your script is located in application/hooks, you will simply use hooks as your filepath. If your script is located in application/hooks/utilities you will use hooks/utilities as your filepath. No trailing slash.
params Any parameters you wish to pass to your script. This item is optional.

Multiple Calls to the Same Hook

If you want to use the same hook point with more then one script, simply make your array declaration multidimensional, like this:

	put "MyHandler" into gHooks["preController"][1]["handler"]
	put "MyScript.lc" into gHooks["preController"][1]["filename"]
	put "hooks" into gHooks["preController"][1]["filepath"]
	put "beer" into gHooks["preController"][1]["params"][1]
	put "wine" into gHooks["preController"][1]["params"][2]
	put "snacks" into gHooks["preController"][1]["params"][3]

	put "MyOtherHandler" into gHooks["preController"][2]["handler"]
	put "MyOtherScript.lc" into gHooks["preController"][2]["filename"]
	put "hooks" into gHooks["preController"][2]["filepath"]
	put "red" into gHooks["preController"][2]["params"][1]
	put "yellow" into gHooks["preController"][2]["params"][2]
	put "blue" into gHooks["preController"][2]["params"][3]

This permits you to have the same hook point with multiple scripts. The order you define your array will be the execution order.

Hook Points

The following is a list of available hook points.

preSystem
Called very early during system execution. Only the benchmark and hooks library have been loaded at this point. No routing or other processes have happened.
preController
Called immediately prior to any of your controllers being called. All base libraries, routing, and security checks have been done.
postControllerConstructor
Called immediately after your controller is loaded, but prior to any handler calls happening.
postController
Called immediately after your controller is fully executed.
displayOverride
Overrides the _rigDisplay command, used to send the finalized page to the web browser at the end of system execution. This permits you to use your own display methodology. The finalized data will be available by calling rigGetOutput()
cacheOverride
Enables you to call your own handler instead of the _rigOutDisplayCache() function in the output library. This permits you to use your own cache display mechanism.
scaffoldingOverride
Permits a scaffolding request to trigger your own script instead.
postSystem
Called after the final rendered page is sent to the browser, at the end of system execution after the finalized data is sent to the browser.

Hook Example Using displayOverride as Hook Point to Minify Output

Let's say you want revIgniter to automatically minify the HTML output just before it is displayed. This can easily be accomplished with the help of revIgniter's hooks feature.

First you need a script which removes all comments and whitespace from the output. Here is the script which is included since version 1.3.21b and is located in system/application/hooks for your convenience:

<?rev
put gBASEPATH into gBASEPATH

if gBASEPATH is "gBASEPATH" then
	put "No direct script access allowed."
	exit to top
end if



/*----------------------------------------------------------------------
--| COMMAND rigMinifyOutput
--|
--| Author: rabit
--| Version:  1.1
--| Created: 13-05-2011
--| Last Mod: 29-06-2011
--| Requires: rigGetOutput(), rigPregReplace(), rigSetOutput, _rigDisplay
--|
--| Summary: Minifies HTML output.
--| 
--| Format:  rigMinifyOutput	
--|
--| Parameters: --
--|
--| Return: void
----------------------------------------------------------------------*/

command rigMinifyOutput
	put rigGetOutput() into tRawHTML

	# REMOVE COMMENTS
	put "(?s)(\<!--\s*[^\s\[\>\<].*?--\>)" into tRegEx
	put " " into tReplacement
	put rigPregReplace(tRawHTML, tRegEx, , tReplacement) into tMinifiedHTML

	# REMOVE WHITESPACE
	put "(?s)(\>\s+\<)" into tRegEx
	put "><" into tReplacement
	put rigPregReplace(tMinifiedHTML, tRegEx, , tReplacement) into tMinifiedHTML

	put "(?s)((\s)+)" into tRegEx
	put " " into tReplacement
	put rigPregReplace(tMinifiedHTML, tRegEx, , tReplacement) into tMinifiedHTML

	# DISPLAY HTML
	rigSetOutput tMinifiedHTML
	_rigDisplay
end rigMinifyOutput




--| END OF overrideOutput.lc
--| Location:  ./system/application/hooks/overrideOutput.lc
----------------------------------------------------------------------

The next step is to add the following lines to your hooks.lc file in system/application/config:

# MINIFY OUTPUT
put "rigMinifyOutput" into gHooks["displayOverride"]["handler"]
put "overrideOutput.lc" into gHooks["displayOverride"]["filename"]
put "hooks" into gHooks["displayOverride"]["filepath"]

Now enable hooks in system/application/config/config.lc and your are done. You don't need to care anymore about how much overhead there is due to comments and whitespace in your view files as revIgniter, by using this hook, sends solely relevant data to the client. This works with cached output too.