Jamroom Module Guide: quota.php

If your module is going to provide a new set of features for Jamroom Users, it is a good idea to give the Jamroom owner the flexibility of enabling/disabling your module (or set of features) on a per Jamroom Quota basis.  Since most features in Jamroom allow this flexibility, it is recommended that you do the same for your module.

The quota.php script consists of 2 properly named PHP functions that will be executed by Jamroom when the Quota config is displayed, as well as when the quota information is saved - this allows you to perform error checking on the received values, and respond with appropriate error messages if an invalid option or values is selected or entered.

Here is the quota.php script for our jrYouTube module - details on what each function and part does will follow:

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

// Which tab are we part of?
// Valid tabs are:
// General, Payments, Media Access, Media Support
// Site Features, Extra Features, Site Themes
$jrYouTube_quota_tab = 'Media Support';

/**
 * The _config function is used to display the Config options for the given quota.
 * @param array Full quota information for the quota being modified
 * @return bool Returns true
 */
function jrYouTube_quota_config($quota)
{
    // Allow jrYouTube to be turned on/off per Artist quota
    if (isset($quota['quota_type']) && $quota['quota_type'] == 'artist') {
        jmSpanCell('YouTube Videos','Quota Settings for the YouTube Videos Module');
        jmYesNo('YouTube Videos','quota_jryoutube_access','If this is set to yes, then profiles
          in this quota will be allowed to create embedded YouTube videos.',
          $quota['quota_jryoutube_access']);
        return(true);
    }
    return(false);
}

/**
 * The _verify function is used to validate the entries received in the _config function
 * @param array Posted results for form.
 * @return mixed returns bool true on success, array on failure
 */
function jrYouTube_quota_verify($_post)
{
    // Verify we get a yes/no
    if (!checkType($_post['quota_jryoutube_access'],'yesno')) {
        $_tmp['error_text']  = 'You have entered an invalid value for the YouTube Video Access
          setting - please select either Yes or No';
        $_tmp['error_field'] = 'quota_jryoutube_access';
        return($_tmp);
    }
    return(true);
}
?>

 Let's look at each section of the quota.php script now so we can cover in details the required elements.

Header

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

The header section of our script sets up the header comment as well as adds our "IN_JAMROOM" check - this check is required at the top of your module - don't forget it!

Jamroom Quota Config tab location

// Which tab are we part of?
// Valid tabs are:
// General, Payments, Media Access, Media Support
// Site Features, Extra Features, Site Themes
$jrYouTube_quota_tab = 'Media Support';

The _quota_tab variable tells Jamroom the "tab" that the Jamroom Quota options will be placed on.  In the case of our example, we want the options to be available on the "Media Support" tab.  Our options will appear at the bottom of the Media Options form page in the Jamroom Control Panel.  Note that the naming of the variable MUST be:

    $Module_Name_quota_tab

Where $Module_Name is the same name as your module directory.  If you do not name the variable correctly, Jamroom will ignore it.

Module quota_config function

/**
 * The _config function is used to display the Config options for the given quota.
 * @param array Full quota information for the quota being modified
 * @return bool Returns true
 */
function jrYouTube_quota_config($quota)
{
    // Allow jrYouTube to be turned on/off per Artist quota
    if (isset($quota['quota_type']) && $quota['quota_type'] == 'artist') {
        jmSpanCell('YouTube Videos','Quota Settings for the YouTube Videos Module');
        jmYesNo('YouTube Videos','quota_jryoutube_access','If this is set to yes, then profiles
          in this quota will be allowed to create embedded YouTube videos.',
          $quota['quota_jryoutube_access']);
        return(true);
    }
    return(false);
}

The quota_config function is our first REQUIRED function.  This function creates the form elements that will appear in the Jamroom Quota config (on the tab specified).  Jamroom will supply ONE function parameter for your use - the $quota array.  The $quota array will contain all of the current data for the Jamroom Quota that the admin is currently working on.  This allows you to place the already configured value into your form element, or place a default value if no value has been selected.

The naming of this function is important in order for Jamroom to see it - it must be named:

    $Module_Name_quota_config

Where $Module_Name is the same name as your module directory.  If you do not name the variable correctly, Jamroom will ignore it.

For details on the different Control Panel form functions that you can use in your quota_config function, make sure and check out the "Control Panel Form Funtions" section of the Jamroom Function Reference.

For our example, all we are going to create is a simple "yes" or "no" option to allow the You Tube section to be turn on or off on a per Jamroom Quota basis.  This is accomplished by:

• First we check the $quota['quota_type'] variable to see that it is an "artist" quota - we're only going to allow the You Tube module to be shown on the Media Support tab for Artist Quotas (alternately we could have used "member" or "visitor", or not checked at all to make the option appear on all 3).

• If the quota is an artist quota, we next:
  • Show a jmSpanCell() function - this creates the small "section" divider that will separate our yes/no setting from the other settings that are already on the Media Support tab.
  • use a jmYesNo() function to create our Yes/No form field for the Master Admin to select whether the You Tube module is going to be active for this Jamroom Quota.  IMPORTANT:  The name you provide for your form element MUST begin with "quota"!

• Lastly, we return TRUE so Jamroom knows we are successfully leaving the function, but ONLY if we actually showed the options - otherwise we "fall through" and return false (which lets Jamroom know that no form elements were displayed).

That's all there is to it - now, when the Master Admin views the "Media Support" tab in their Jamroom Quota config for an Artist Quota, the "YouTube Videos" section and Yes/No option will appear at the bottom of the Media Support form.

Module quota_verify function

/**
 * The _verify function is used to validate the entries received in the _config function
 * @param array Posted results for form.
 * @return mixed returns bool true on success, array on failure
 */
function jrYouTube_quota_verify($_post)
{
    // Verify we get a yes/no
    if (!checkType($_post['quota_jryoutube_access'],'yesno')) {
        $_tmp['error_text']  = 'You have entered an invalid value for the YouTube Video Access
          setting - please select either Yes or No';
        $_tmp['error_field'] = 'quota_jryoutube_access';
        return($_tmp);
    }
    return(true);
}

The last function in our quota.php script is the "quota_verify" function.  This function is called so you can verify that the values entered into the Quota Config form are of the allowed type.  Jamroom will pass in as the only function parameter the posted form values (from $_REQUEST).

If the function determines that a value entered is incorrect, then an error can be sent back to the form without the Jamroom Quota settings being saved.

To help in your testing of values, Jamroom provides a handy checkType() function - this function allows you to test a given value to ensure it matches a specified "type".  In our example here, we are using the "yesno" parameter - this ensures the value that was entered in the Quota config form must either be "yes" or "no" - no other values will be accepted:

    if (!checkType($_post['quota_jryoutube_access'],'yesno')) {

It is VERY important that you always verify the posted values that are going to be saved for your module.  As you can see, we are testing the value of $_post['quota_jr_youtube_access'] - this is the name of the quota variable that we set in our quota_config function above.

If the value entered by the Admin is "yes" or "no", we have no problem and we simply return TRUE - this tells Jamroom no errors were encountered and Jamroom can continue saving the quota information.  However, if the value received in the $_post['quota_jr_youtube_access'] variable is NOT a yes or no, we need to have a way to tell the Admin that the value that was entered is incorrect.  We do this by creating a small array with 2 values in it - the field that is in error, and error text to display:

$_tmp['error_text']  = 'You have entered an invalid value for the YouTube Video Access
  setting - please select either Yes or No';
$_tmp['error_field'] = 'quota_jryoutube_access';
return($_tmp);

When Jamroom sees that the value returned from the function is an array, it will refresh the Quota Config page, highlight the field that is in error, and display the error message to the admin.

That's all there is to the quota.php script - of course you are not limited to only providing a single quota option - your quota_config function can generate many different fields for configuration if needed.  However, you will need to ensure that the jamroom_quota database table has been prepared properly to accept your settings - that is where our next script comes into play - the schema.php file.