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 gHooksA["preController"]["handler"]
  put "MyScript.lc" into gHooksA["preController"]["filename"]
  put "hooks" into gHooksA["preController"]["filepath"]
  put "beer" into gHooksA["preController"]["params"][1]
  put "wine" into gHooksA["preController"]["params"][2]
  put "snacks" into gHooksA["preController"]["params"][3]

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:

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 gHooksA["preController"][1]["handler"]
  put "MyScript.lc" into gHooksA["preController"][1]["filename"]
  put "hooks" into gHooksA["preController"][1]["filepath"]
  put "beer" into gHooksA["preController"][1]["params"][1]
  put "wine" into gHooksA["preController"][1]["params"][2]
  put "snacks" into gHooksA["preController"][1]["params"][3]

  put "MyOtherHandler" into gHooksA["preController"][2]["handler"]
  put "MyOtherScript.lc" into gHooksA["preController"][2]["filename"]
  put "hooks" into gHooksA["preController"][2]["filepath"]
  put "red" into gHooksA["preController"][2]["params"][1]
  put "yellow" into gHooksA["preController"][2]["params"][2]
  put "blue" into gHooksA["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.

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 only stack 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 application/hooks/overrideOutput.livecodescript for your convenience:

script "overrideOutput"

global gRigA

local sStackInUse

 --| COMMAND libraryStack
 --| Author: rabit
 --| Version:  1.0
 --| Created: 2018-12-09
 --| Last Mod: --
 --| Requires: --
 --| Summary:  Run security check.
 --| Parameters: --
 --| Return: empty
on libraryStack
  if (gRigA is not an array) and (the environment is "server") then
    put "No direct script access allowed."
    exit to top
  end if

  if the short name of the target = the short name of me then 
    if sStackInUse <> TRUE then
      put TRUE into sStackInUse
    end if
    pass libraryStack
  end if -- if the short name of the target = the short name of me
end libraryStack

--| 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

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

  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

  rigSetOutput tMinifiedHTML
end rigMinifyOutput

--| END OF overrideOutput.livecodescript
--| Location:  ./application/hooks/overrideOutput.livecodescript

Note: All revIgniter script only stack files use "livecodescript" as file extension. This convention you should keep in mind when you build hooks, models, libraries, helpers etc.

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

put "rigMinifyOutput" into gHooksA["displayOverride"]["handler"]
put "overrideOutput.lc" into gHooksA["displayOverride"]["filename"]
put "hooks" into gHooksA["displayOverride"]["filepath"]

Now enable hooks in 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.