Using Jamroom Mode Hooks in your Jamroom Module

With the release of Jamroom 4.0.11, a new feature was added in to the Jamroom Module support - "Mode Hooks".  Mode Hooks are an advanced (and optional) function that may never need to be used by your module, but if needed, they provide a very powerful way to "hook" into the various stages of the process flow within Jamroom.

If you have spent much time using Jamroom, you may have noticed that the Jamroom PHP scripts usually accept a "mode" URL parameter - so in the URL location bar of your browser, you may see a URL like this:

http://demo.jamroom.net/song.php?mode=song_edit&band_id=74

The "mode" in this URL would be "song_edit" (since that is the value of mode).  Most Jamroom scripts operate with a "mode" parameter, and it is this parameter that we are going to hook into to allow us to perform actions between Jamroom modes.

Using our example URL from above, the "mode" of the URL is "song_edit".  This happens to be the screen that you are presented with in the Control Panel if you click on "Song Modify", select a song to modify, then press "Modify Song".  You are then presented with a the screen for updating the information and related files for a Jamroom song.

For our example, we are going to tap in to this "mode" (song_edit) using a Mode Hook, and log the song_id the user is going to be modifying to the Activity Log.  While this is not something you would probably want to do on your real Jamroom site, it will highlight how we can tap into a Jamroom mode (and related information) before it gets processed by Jamroom.

New Module file: hooks.php

The first step in creating our new Mode Hook is to create our new module file called "hooks.php".  This PHP script must be located in the same directory as your other module scripts such as include.php, etc..  So as an example, our file would be located at:

jamroom/modules/Module_Name/hooks.php

It is within this hooks.php script that we will define the Mode Hook functions that we want processed.

Naming your Mode Hook functions

In order for Jamroom to properly "see" your Mode Hooks, you must name them in a very specific way within your hooks.php script.  Here is the small "hooks.php" file (simplified) used in our example:

<?php
/**
 * Jamroom Example Mode Hooks
 * @copyright 2009 by Talldude Networks LLC
 * @author Brian Johnson - bigguy@jamroom.net
 */
defined('IN_JAMROOM') or exit();

function Module_Name_song_song_edit()
{
    // inside of your function, you can access the posted
    // form variables in $_REQUEST

    // Our Logic
    jmLogger(0,'INF',"Modifying song_id {$_REQUEST['song_id']}");
}
?>

 It is VERY important that your function be named properly - it must consist of:

MODULENAME_SCRIPTNAME_MODE

note that SCRIPTNAME does NOT include the ".php" extension.  So our function name consists of:

Module_Name (Name of Module) song (name of script - song.php) song_edit (script mode)

This allows Mode Hooks to be defined by different Modules for different scripts, even if the "mode" is named the same.  Once Jamroom sees a function defined by your module that is named properly, it will be executed BEFORE the associated Jamroom mode is run.  This gives your Mode Hook a chance to "check out" the $_REQUEST PHP superglobal and modify (or log) anything as needed.

You can define as many different Mode Hook functions within your hooks.php file as you would like.

Getting User Information into your Mode Hook

By default, the Mode Hook is the FIRST thing executed on the respective mode "load", so at the time your function is executed, the Jamroom $_user array will not be loaded for your use.  However, you can gain access to user information by simply placing this line as the first line of your function:

$_user = sessionCheck();

Then you will have access to all of the viewing user's information within the $_user array.  Jamroom is smart enough to see that if the User Session has already been established (as it would now be in your Mode Hook), it will use the existing session instead of trying to establish a new one.

Hopefully this simple example demonstrates the Mode Hook functionality, and gives you an idea of what might be possible - it's up to your imagination to figure out what you can do between "modes" in Jamroom ;)