Calling Hooks

If you are developing an item module then you should allow utility modules to add functionality to the item module. This is carried out through use of the pnModCallHooks() function. This function should be placed wherever a specific action is carried out by the item module, where the current specific actions that the hooks system is able to operate on are:

The hook calls should be made at the appropriate level depending on the action that is being taken. With the current hooks, addition and deletion hooks should be called at the API level, and display hooks should be called at the GUI level.

The pnModCallHooks() function takes a number of parameters, which are explained below:

hookobject

The object for which the hooks are to be called - currently either category, or item, as described above

hookaction

The action for which the hooks are to be called - currently one of create, delete, transform, or display

obid

An ID that, within the scope of the module and object, uniquely defines the entity for which the hook is being called

extrainfo

This is extra information that is required by the hook function, and is dependent on the hook action being called. Information on the information required by each hook is covered below.

• For create hooks a string that can be used in conjunction with the obid as part of a URL to access the object. For example, if your gallery_user_display() function uses a variable picid to define the particular picture that a user wishes to look at then the URL would be something like 'index.php?module=gallery&func=display&picid=4' and the identification part of the URL would be something like 'picid=4' so you would pass 'picid' to this hook.

• For display() hooks a URL that can be used by the hooks to return to a suitable page once they have finished any work that they might have to do. This is normally just the standard display URL for this function.

• For transform() hooks an array of items that contain text-based content that can be transformed. This is normally all text-based items.

The pnModCallHooks() function returns different information depending on value of hookaction. If hookaction is display then the hook will return extra output that should be displayed directly following the display for the item itself. If hookaction is create or delete then the function will return either true or false depending on the success or failure of the hooks. If hookaction is transform then the hook will return an equivalent array to that which was passed in, with the items suitable transformed.

As an example of calling hooks, if you were developing the 'Gallery' module and were displaying a picture, after the display of the picture you would want to call the hooks to add any other functionality available and required by the site administrator. To do this you would use the following lines:

$output->SetInputMode(_PNH_VERBATIMINPUT);
$output->Text(pnModCallHooks('item',
                             'display',
                             $pictureid,
                             pnModURL('gallery',
                                      'user',
                                      'display',
                                      array('pictureid' => $pictureid))));
$output->SetInputMode(_PNH_PARSEINPUT);
       

which would add the verbatim output of the hooks to the current output. It is worth noting again here the from this code it can be seen that the module itself needs no information on what hooks, if any, exist, it just calls the function and lets the PostNuke core deal with what extra output should be added to this item.

One important area to understand is where exactly in your code to call hooks. For example, if you were displaying a thumbnail view of 100 pictures from your Gallery module, should you call an item display hook for each picture? The answer to this is somewhat dependent on the nature of your module, but in general you should only call display hooks when you are displaying the details of a single item rather than an overview of a large number of items (of course, if all of those items are in a single category then you should call a display hook for that category). However, the transform hook should be called whenever you are displaying content regardless of it if is just an overview, as the overview information could require transformation before display.

The annotated Template module in the standard PostNuke distribution contains notes on calling hooks within an item module.