Jamroom Module Guide: theme.php

If the module you are creating provides "items" that can be shown on a profile, then you'll want to create a theme.php script so Jamroom's Profile Generator can "hook" into your module and integrate it as another available sub-config file in the Jamroom Profile Theme's theme.cfg file:

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

/**
 * The _theme_items function retrieves valid items for the profile.
 * @param array Full array of profile information
 * @return mixed Returns array on success, false on failure
 */
function jrYouTube_theme_items($_band)
{
    global $jamroom_db;
    $req = "SELECT *
              FROM {$jamroom_db['jrYouTubeVideos']}
             WHERE youtube_band_id = '{$_band['band_id']}'";
    $_rt = dbQuery($req,'NUMERIC');
    if (isset($_rt) && is_array($_rt)) {
        return($_rt);
    }
    return(false);
}

/**
 * The _replace function is used for theme filename replacement variables
 * @param array Full array of current item information
 * @return array Returns array of filename replacement strings
 */
function jrYouTube_theme_replace($_item)
{
    $_out = array(
      '{YOUTUBE_VIDEO_ID}' => $_item['youtube_video_id']
    );
    return($_out);
}
?>

This is a simple function that looks in the YouTube database table, grabs all of the YouTube videos for the profile, and returns it as an array.  There is no need to do any work on the array before returning it, as Jamroom will uppercase the array keys and make the array available in the theme sub config file.

In the case of our jrYouTube module, if we want to add the YouTube videos to a profile template, we would first create a theme.cfg "sub config" file (for more details on using Sub Config files, make sure and check out the Jamroom Theme Designer guide) called "jrYouTube_list.cfg".  When Jamroom sees the keyword "jrYouTube" (the module name) in a config file's name (i.e. it ends with .cfg), that file will be a theme Sub Config file, and Jamroom will "loop" over the templates inside once per item found.

The theme.php script in more detail:

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

This top part, like all of our other Module scripts, is the comment header and "IN_JAMROOM" check - this part is required.

The theme_items function

/**
 * The _theme_items function retrieves valid items for the profile.
 * @param array Full array of profile information
 * @return mixed Returns array on success, false on failure
 */
function jrYouTube_theme_items($_band)
{
    global $jamroom_db;
    $req = "SELECT *
              FROM {$jamroom_db['jrYouTubeVideos']}
             WHERE youtube_band_id = '{$_band['band_id']}'";
    $_rt = dbQuery($req,'NUMERIC');
    if (isset($_rt) && is_array($_rt)) {
        return($_rt);
    }
    return(false);
}

This next part is the required PHP function needed in our theme.php script.  The function MUST be named:

    Module_Name_theme_items

If it is not named properly, Jamroom will not see it.  The purpose of this function is to get the "items" from the module database and return them to the Jamroom Theme Generator for processing.  note the following section:

    global $jamroom_db;

In order to have access to the global $jamroom_db database array, the PHP keyword "global" is used to make it available within the function.

The theme_replace function

/**
 * The _replace function is used for theme filename replacement variables
 * @param array Full array of current item information
 * @return array Returns array of filename replacement strings
 */
function jrYouTube_theme_replace($_item)
{
    $_out = array(
      '{YOUTUBE_VIDEO_ID}' => $_item['youtube_video_id']
    );
    return($_out);
}

The Jamroom Theme generator has the ability to do "filename replacement variables" inside of the main theme.cfg file or a sub config file.  If you would like to provide filename replacement variables, then you can define a "theme_replace" function that creates an array of filename replacement variables.

Creating the Profile Theme templates

Just like other "items" in Jamroom, you will need to create a Profile Theme sub-config file for your items, as well as any templates that you want to use to integrate the new items into your Jamroom Profile theme.   For more details on how to work with Profile Theme templates, and how to use the master theme.cfg config file as well as sub-config files, make sure and check out the Theme Designer Guide.