Jamroom Module Guide: include.php

The "include.php" script is the only required script in a Jamroom module - every other script and directory is optional, although you'll likely end up having several of these other scripts and directories unless your module is extremely simple.  For our example (jrYouTube), the include.php script will not be very big, but will do the following:

• Define the Module Name as it will appear in the Jamroom Control Panel to the Master Admin

• Define the Module Version.  This is important, since if we want Jamroom to be able to track when a new version of our module has been installed and prompt the Master Admin to run an Integrity Check, we must include a module version.  Jamroom does not apply any standard to versioning, meaning all of the following versions are acceptable:
  • 1.0.0
  • 1
  • 1.0.1.234a
  • 1dot0dotbeta1

However, it is HIGHLY recommended that you use a 3 digit versioning scheme like Jamroom uses:

MAJOR_RELEASE.MINOR_RELEASE.BUG_FIX_RELEASE

So the first release of your module would be "1.0.0".  If you fix some bugs it would go to "1.0.1".  If you add some small new features it would go to "1.1.0", and if you add some major new features it could go to "2.0.0".  Note that the difference between versions and version number changes is up to you - we just recommend you be consistent.

• Add any custom Jamroom Database names into the master $jamroom_db array.  If your module will be using its own Jamroom database table, then you will define the database table names within the include.php script, by adding them into the global $jamroom_db array.  This gives you access to these database tables throughout all of the scripts and allows your database tables to be prefixed with the correct Jamroom database table prefix as was set by the user during Jamroom install.

The following is our include.php script for our new jrYouTube module:

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

// Define module name as a variable
$jrYouTube = "YouTube";

// Our version
$config['jrYouTube_version']     = '1.0.0';
$config['jrYouTube_developer']   = 'Talldude Networks, LLC., ©'. strftime('%Y');
$config['jrYouTube_description'] = 'This is the description in the Module Manager.';
$config['jrYouTube_support_url'] = 'http://www.jamroom.net/phpBB2';

// Define custom database tables
$jamroom_db['jrYouTubeVideos'] = $config['db_prefix'].'jrYouTubeVideos';
?>

As you can see it is very small, but does the following:

/**
 * Jamroom jrYouTube Module includer
 * @copyright 2009 by Talldude Networks LLC
 * @author Brian Johnson - bigguy@jamroom.net
 */
defined('IN_JAMROOM') or exit();

This first part of the code needs to be included in EVERY module.  This sets the header comment with our information on who developed the module, as well as includes the important line:

defined('IN_JAMROOM') or exit();

It is VERY important that this line be at the top of your PHP scripts in your module directory - this ensures that the PHP script cannot be executed directly, which could lead to unexpected issues or even potential security vulnerabilities, so MAKE SURE it is included at the top of the PHP scripts in your module directory!

The next part:

// Define module name as a variable
$jrYouTube = "YouTube";

defines the NAME of the module as it will appear in the Jamroom Quota config - i.e. what the Master Admin will see in their list of modules.  You can call it whatever you like as long as the PHP variable is the SAME NAME as your module directory.

 The next part:

// Our version
$config['jrYouTube_version']     = '1.0.0';
$config['jrYouTube_developer']   = 'Talldude Networks, LLC., ©'. strftime('%Y');
$config['jrYouTube_description'] = 'This is the description in the Module Manager.';
$config['jrYouTube_support_url'] = 'http://www.jamroom.net/phpBB2';

Defines the Module Version - in this case it is being set to "1.0.0".  Note that the version is being added to Jamroom's $config global array, which means it will be available throughout Jamroom.  Note too that the INDEX name for the version variable must be:

ModuleDirectory_version

Where "ModuleDirectory" is the name of your module's directory (in our example this is "jrYouTube").  If you do not name the version string correctly, Jamroom will not see it.

And finally, we define our custom database table name:

// Define custom database tables
$jamroom_db['jrYouTubeVideos'] = $config['db_prefix'].'jrYouTubeVideos';

Note that the actual database SCHEMA for the table (the table column definitions) will be set in the schema.php file, but in our include.php script we must add the database table NAME to the global $jamroom_db array.  Note that the variable $config['db_prefix'] is placed in the front of our database name - this ensures our database table will be created with the proper table prefix as was set during Jamroom install.

Again here you can see that coming up with a unique module name is important, since how Jamroom interacts with the module depends on it being unique.