Modifying and Customizing the Jamroom Control Panel
Jamroom 3.3 supports the ability for Jamroom Admins to modify or customize the Jamroom Control Panel using Smarty templates. With this feature, the look of your Jamroom is now 100% customizable.
Configuration
A Custom Control Panel will be used by Jamroom if Jamroom finds a directory named "cp" inside your active skin directory (i.e. jamroom/skins/Cobalt3/cp). If Jamroom does not find the "cp" directory, then it will use the Classic Control Panel.
If the "cp" directory is found, Jamroom Admins can allow their users to use either the "Classic" Control Panel, the Custom Control Panel, or allow their users to choose from either option. A new setting can be found in the "General" tab of the Modify Quota screen (jamroom config > Jamroom Quotas > Modify) for "Allow Classic Control Panel":
- If this option is set to "yes," then Jamroom users can decide which control panel they would like to use in their "Profile" (or "Account Info") by checking/un-checking the "Use Classic Control Panel" option.
- If this option is set to "no," then Jamroom users will only be able to use the Custom Control Panel.
Control Panel Templates
The Smarty templates used by your Control Panel will be found in one of two directories:
- jamroom/skins/(skin_name)/cp/ - the directory for your Custom Control Panel templates, where (skin_name) is the name of your Active Skin directory
- jamroom/templates/cp/ - the directory for the Classic Control Panel templates
The following is a list of common templates that all control panel directories are required to have (both Custom Control Panels and the Classic Control Panel):
- header.tpl - this is the header template. It is the first template called for every control panel page.
- form.tpl - this is, perhaps, the most powerful of all of the control panel templates. It contains the logic for generating every form element (as well as many page elements) found throughout the control panel
- footer.tpl - this is the footer template. It is the last template called for every control panel page.
- dashboard.tpl - this is the template that displays the content of the Jamroom Dashboard (between the header and footer templates).
- update.tpl - this is the template that is used to display all pages that are dynamically updated by Jamroom through an <iframe> (i.e. site regeneration, etc.)
- update_line.tpl - this is the template that is used to display all pages that are dynamically updated by Jamroom (i.e. Jamroom Integrity Check, etc.)
- menu.tpl - this is the template for displaying all of the menus in the control panel. Although it is not "technically" a required control panel template (as it can be overridden with the "template" parameter of {jr_admin_menu} function), it is considered "best practice" to have it in your control panel directory.
Apart from these templates, you can also add any other template to your control panel directory and include it within these templates using the normal template inclusion methods.
 |
Note: It is highly recommended that you look through the directory and template structure of one of your current skins (i.e. Cobalt3, Sage, Flashback, etc.), particularly the templates mentioned above, to find out how the templates are used before creating a Custom Control Panel from "scratch." You can even copy the "cp" directory from one of your current control panels to your custom skin and use it as a "base" for customizing to avoid running into significant errors. |
Available Template Variables
The following is a list of available Smarty template variables for Jamroom Control Panel templates:
| VARIABLE |
DESCRIPTION |
| {$_USER} |
The {$_USER} array contains an array of data for the user viewing the page. This array is the same array available in skin templates. |
| {$_LANGUAGE} |
The {$_LANGUAGE} array is an array of language strings for the control panel, taken from the language files in the jamroom/languages/ directory (i.e. english.lang.php). |
| {$PAGE_TITLE} |
The {$PAGE_TITLE} variable contains the title of the control panel page. |
| {$SHOW_MAIN_MENU} |
The {$SHOW_MAIN_MENU} is a special variable that can be used to determine whether the "main" admin menu (i.e. jamroom config, jamroom tools, etc.) should be displayed. Possible values will be "1" to show the main admin menu, and "0" to hide it. |
| {$SHOW_ACTION_MENU} |
The {$SHOW_ACTION_MENU} is a special variable that can be used to determine whether the "action" menu (i.e. profile, cart, my files, etc.) should be displayed. Possible values will be "1" to show the action menu, and "0" to hide it. |
| {$JR_SCRIPT_NAME} |
The {$JR_SCRIPT_NAME} variable contains the file name of the script being called, i.e. admin.php |
| {$JR_MENU_ELEMENTS} |
Only available in the menu.tpl file and other templates used by the {jr_admin_menu} function, the {$JR_MENU_ELEMENTS} array contains an array of elements that can be used to create admin menus. |
| {$JR_MENU_SECTION_COUNT} |
Only available in the menu.tpl file and other templates used by the {jr_admin_menu} function, the {$JR_MENU_SELECTION_COUNT} variable contains the numeric value of the number of "sections" in the menu. |
| {$JR_PAGE_ELEMENTS} |
Only available in the form.tpl file, the {$JR_PAGE_ELEMENTS} array contains an array of page/form elements for the current control panel page. This array contains a large amount of data, which can be viewed using a {debug output="html"} function in your form.tpl file (for testing purposes). |
| {$smarty.session.MENU_LEVEL} |
The {$smarty.session.MENU_LEVEL} is a special smarty session variable that can be used to track which control panel menu the user is viewing. Possible values are "admin" (for the master admin menu), "artist" (for the artist menu), and "member" (for the member menu). |
|
Note: To see a list of all available variables in your control panel templates, you can use a {debug output="html"} function. Note, however, that the output of this function contains highly sensitive data, and, therefore, it is not recommended that it be used on a "live" system. |
Tips for Customizing your Control Panel
One thing that many Jamroom Admins often wish to do is to exclude certain elements from being displayed to end users. By default, all Jamroom.net-provided skins have a form.cfg config file (which is loaded in the form.tpl file), which allows Jamroom Admins to exclude elements from being loaded into the Jamroom forms. The default config file contains the following code:
form.cfg
# Default Control Panel Form Config file
# Copyright 2008 by Talldude Networks, LLC.
# All comments must begin with a '#'
# Disabled Fields - enter each form name you
# would like to disable, separated by commas - i.e.
# song_history,song_lyrics
disabled_form_fields = "" |
Elements added to the disabled_form_fields config variable, as stated in the file, will not be displayed in the form.tpl file (if using a control panel that has this functionality built into it). If your control panel does not support the form.cfg method, you can use the following code to exclude individual elements in the form.tpl file:
form.tpl
|
{if is_array($JR_PAGE_ELEMENTS)}
{foreach from=$JR_PAGE_ELEMENTS item='_element'}
{if $_element.name == 'form_name'}
{php}continue;{/php}
{/if}
{* continue with other form elements *}
{/foreach}
{/if}
|
Where form_name is the name of the element you want to exclude, i.e. song_history, song_lyrics, etc.
|
