Creating new sections in the Jamroom Control Panel

For our jrYouTube module, we want to allow the user (when logged in) access to a form to create and delete YouTube videos from their profile.  In order to accomplish this we're going to create a Control Panel PHP script to handle the menu options that we want to make available in the Control Panel.  Depending on whether you want your menu options to be made available to Members, Artists (or both), you will need to name your PHP script with the proper prefix keyword.  So for our jrYouTube module, we only want the menu options to be be available to Artist Quotas, so we would use the "artist" prefix, and name our file:

    artist_jrYouTubeMenu.php

Note that the "name" of the function (jrYouTubeMenu) is up to you, although we suggest you name it based on your module.  If we had decided instead to make this option available to only Member Profiles, we would have done:

    member_jrYouTubeMenu.php

And if we wanted it available to both Artists and Members:

    all_jrYouTubeMenu.php

For Admin Menu (Master admin only), you would use:

    admin_jrYouTubeMenu.php

However, since we're only doing this for Artist Profiles, ours will begin with "artist".

Note:  The name of the PHP Control Panel function inside, MUST be named the same as the PHP script, minus the .php extension and the artist/member/admin/all prefix.

<?php
/**
 * Jamroom jrYouTube Control Panel options plugin
 * @copyright 2008 by Talldude Networks LLC.
 * @author Brian Johnson - bigguy@jamroom.net
 */
defined('IN_JAMROOM') or exit();

function jrYouTubeMenu(&$_user)
{
    if (!isset($GLOBALS['JR_MENU_SECTIONS']['section_jrYouTubeMenu'])) {
        return(true);
    }
    if ($_user['quota_id'] < 0 || $_user['quota_jryoutube_access'] != 'yes') {
        return(false);
    }
    jmTextBanner('YouTube Videos','false','false','false','section_jrYouTubeMenu');
    jmButton('Create Video','jrYouTube.php?mode=create','youtube_create');
    jmButton('Delete Video','jrYouTube.php?mode=delete','youtube_delete');
    jmTextBannerEnd();
    return(true);
}
?>

You can have more then one Control Panel PHP script in the cp directory, but for most modules you'll only need one.  Some important parts of the function are:

    if (!isset($GLOBALS['JR_MENU_SECTIONS']['section_jrYouTubeMenu'])) {
        return(true);
    }

This first part checks the status of the "JR_MENU_SECTIONS" Global array.  It is very important that you test that the CP function is part of this array - if it is not, then the function should simply return.  This allows the Skin designer full control over which elements appear in what area, and is needed for proper Control Panel layout.

Secondly, we check to be sure the user's quota allows access:

    if ($_user['quota_id'] < 0 || $_user['quota_jryoutube_access'] != 'yes') {
        return(false);
    }

This way we do not show the option to user's who do not have access to the jrYouTube module based on their quota setting.  In this case we test the user's quota_id (less than 0 is a member quota), and then we also check to be sure the module access is set to yes in the their quota.

    jmTextBanner('YouTube',false,false,'false','section_jrYouTubeMenu');

This next line tells Jamroom to start a new Control Panel "section".

A Control Panel section is an area of the Control Panel that the user will find "options" in.  For example, in Jamroom, when you click on "songs" and see "Create Song", "Modify Song" and "Delete Songs", that is a section.  Each section in Jamroom must begin with the jmTextBanner function call (the reason it is called jmTextBanner makes more sense when you think about the Jamroom Classic Control Panel - that's where it started at).  For details on the jmTextBanner() function, make sure and check out the Jamroom Function Reference page on it.

This call to the jmtextBanner function will create a new Control Panel "section" for us called "section_jrYouTubeMenu".  The name of the section of the Control Panel (i.e. the button or menu entry) will be "YouTube".

The next section:

    jmButton('Create Video','jrYouTube.php?mode=create','youtube_create');
    jmButton('Delete Video','jrYouTube.php?mode=delete','youtube_delete');

Creates 2 Menu entries within our "YouTube" section - one for creating a new YouTube Video entry, and one for deleting a YouTube entry.

For the sakes of keeping this module as simple as possible we have not added any code in to check to see if there are alrady existing entries added in by the user - to make the module more "friendly" we might consider adding in an SQL query that checks the YouTube video database table and gets the number of YouTube videos already created by this user - that way, we would not show the "Delete Video" option if no videos existed to delete.  But for now we'll leave it like it is since it makes it simpler.

For details on the parameters to use with the jmButton() function, make sure and check out the Jamroom Function Reference.

Finally we wrap up the function with the last 2 lines:

    jmTextBannerEnd();
    return(true);

Since we have an "open" jmTextBanner function (at the top of the function), we must now "close" the Control Panel section via the jmtextBannerEnd() function call.  We then return true to let Jamroom know the function exited properly.

That's it - you've now created a new "section" in the Jamroom Control Panel that can be shown to your Jamroom users.