Customizing the Jamroom Control Panel Templates

With the release of Jamroom 3.3 it became possible to fully customize the Jamroom Control Panel for the first time (beyond simply changing the colors and layout via CSS).  In order to accomplish this, a new set of templates was developed that creates the Control Panel layout, so it now has become fully customizable to suit your needs.

Template Location

Jamroom expects to find the Control Panel templates within the "cp" directory within the active skin - i.e.

    jamroom/skins/Flashback/cp

However, if you are running the "Classic Control Panel", you'll find the Control Panel templates are located at:

    jamroom/templates/cp

It is recommended that if you are going to customize the Control Panel templates that you use the Skin Control Panel - not the Classic Control panel.

The Control Panel Templates

Within the control panel template directory, you will find several template files - these files control the display of information within the Jamroom Control Panel - only a few are actually required:

• header.tpl - the header.tpl file is the main "header" template file - this is the first file that Jamroom will process when displaying a page in the Control Panel.  This is often the location of the site logo, log out links, etc.

• form.tpl - this control panel template is the main "workhorse" for the Control Panel - it is where all of the actual page and form information that is shown in the Control Panel is generated from.  It contains all the small HTML snippets for creating the actual forms and different control panel pages.

• footer.tpl - similar to the header.tpl file, the footer.tpl file is the last template processed by Jamroom, and creates the "footer" section within the Control Panel.

• update.tpl - within Jamroom there are several tools and checks (i.e. when rebuilding Jamroom Profiles) that pop up a small wnidow that shows a numerical "update" - the update.tpl file is that small window.

• update_line.tpl - there are tools within Jamroom that will show a "status update" when they are running - i.e. a bit of text that tells you what Jamroom is currently doing (i.e. in the Jamroom Integrity Check) - this small template controls the look and feel of that line.

• dashboard.tpl - this special template constructs the Jamroom Dashboard.

• graphs.tpl - this special template constructs the historical graphs you can find the Jamroom Dashboard.

• menu_xxx.tpl - the "menu" templates are special templates - there may be only one "menu.tpl", or there may be multiple menu templates - these templates are what Jamroom uses to create menus within the Jamroom Control Panel of available sections for the user.  These templates are processed by the {jr_admin_menu} template function calls that will be placed in your header.tpl (or other control panel templates).

Control Panel Config files

Within the Control Panel directory you will also see some Config files (.cfg) - these files pass extra information about the Control Panel to Jamroom.  They include:

• form.cfg - this optional config file can be created to make it easier to "hide" specific form fields from the control panel interface, instead of having to add exceptions in the form.tpl file.

• editor.cfg - This is a are required template file that contains the JavaScript used by the WYSIWYG editor within Jamroom.  Jamroom uses the Tiny MCE editor - if you need to add additional configuration options to the editor, this is where you would do it.  Note that in Jamroom 3 this file may be called "editor.tpl".

• popup.cfg - (Jamroom 4 only) - this config file tells Jamroom the width and height values to use when creating a popup window within the Jamroom Control panel.

Advanced: Modifying form.tpl to have separate templates for Control Panel sections

In order to keep the number of templates needed in the Jamroom Control Panel to a minimum, the form.tpl file handles all of the "heavy lifting" internally, so you do not have to have a separate template file for each "page" in the Jamroom Control panel (which would literally number in the many hundreds if you created a template for each page).

However, if you find that you want to customize a specific page in the Control Panel beyond what can be done by modifying the look and feel of the entries in the form.tpl (i.e. you want the page layout to be completely different), then you'll want to do the following to setup this type of structure:

• The first step is to create a sub directory within the cp directory to store our new forms - this will keep things more organized.  We'll call this new directory "forms" - i.e.

jamroom/skins/Skin_Name/cp/forms

Of course replace "Skin_Name" the name of the active skin you are curently using.

• Next we need to modify the form.tpl file to tell Jamroom that for a specific page in the Control Panel, instead of "looping" through the entries in the form.tpl file, we are instead going to load and display an external template file that is located in our "forms" directory.  We can do this by adding this to the TOP of our form.tpl file (under the {config_load} line and BEFORE the {foreach} loop):

{if is_file("`$JAMROOM_DIR`/skins/Nova/cp/forms/`$JR_SCRIPT_NAME`_`$smarty.request.mode`.tpl")}

  {include file="`$JAMROOM_DIR`/skins/Nova/cp/forms/`$JR_SCRIPT_NAME`_`$smarty.request.mode`.tpl"}

{else}

And at the VERY BOTTOM of the form.tpl file you would add:

{/if}

To close the large if/else statement.

• Next we're going to create our custom Control Panel template page exactly as we want it to look, and save it to a file with the proper name:

jamroom/skins/Skin_Name/cp/forms/SCRIPTNAME_MODE.tpl

where "SCRIPTNAME" is the name of the script (i.e. "song.php") and "MODE" is the Control Panel mode you want to replace (i.e. "song_add") - so using our example we would end up with:

jamroom/skins/Skin_Name/cp/forms/song.php_song_add.tpl

And this template would contain our ENTIRE form and display (minus header and footer) for that page.

It is VERY important to note the following if you are going to be replacing Jamroom forms in your Control Panel:

• The actual form MUST be correct in order to work!
• Your best bet here is to view the source of the unchanged form before you change it and then modify it to suit your needs.
• Make sure and use a {jr_form_token} template function to generate the anti-CSRF token for your Jamroom forms or you will receive an error when you submit the form.

That's it - following these steps you should be able to fully customize any section of the Jamroom Control Panel you wish.