You may have already played around briefly with the included Jamroom Artist / Member Themes (the default theme that comes with Jamroom is called "Cobalt"), or wondered how you could create or modify a Jamroom Theme yourself. This document will help describe how the Jamroom Theme Engine works - that is, how it parses the theme config files and theme template files in order to produce the output you are expecting.

This documentation will make the following assumptions:

1. You are already familiar with HTML and understand how to write your own HTML. (Note that having an understanding of PHP scripting can also help, since the output file type for the theme engine is PHP files, and Jamroom does not limit you to only having HTML in your templates).
2. You are familiar with the Jamroom program itself (most likely from a user perspective) and know how to add songs, messages, generate HTML, etc.
3. You have some patience and some creativity - at first the process for creating a theme may seem quite complex, but after playing with it for a bit you will find that almost any way you can imagine to string HTML (or even PHP, javascript, etc.) together, Jamroom will parse it and create the output for you.

The Jamroom Theme Engine gets the directives (instructions) that it needs to generate an Artist Page from a master “config” file within the Theme’s directory (which is located in jamroom/themes). This config file is always called theme.cfg, and may contain references to other sub-config files or references to template files, as well as the output page those 2 things can belong to. For example, lets say the master theme.cfg file looked like this:

# sample page config file
# comments within config files must begin with a '#'

# main Index section (messages)

     index_header.tpl | index.php
     message_more.cfg | message_more_{MESSAGE_ID}.php
     message_text.cfg | index.php
    common_footer.tpl | index.php

# Music Section

     music_header.tpl | music.php
             song.cfg | music.php
    common_footer.tpl | music.php
song_popup_lyrics.cfg | lyrics_{SONG_ID}.php
  song_popup_info.cfg | info_{SONG_ID}.php

# Store Section

     store_header.tpl | store.php
            store.cfg | store.php
    common_footer.tpl | store.php

# About

     about_header.tpl | about.php
       about_text.tpl | about.php
    common_footer.tpl | about.php

The Jamroom Theme engine will begin parsing this theme.cfg config file from the top down - and will operate on what it finds using this logic:

(template or sub-config file to parse) | (output file to add parsed results to)

Note that the directives on the left side of the theme.cfg file are seperated from the output locations on the right side by the “pipe” symbol ¹⁾.  You must have this pipe seperator there or it will not work! Spaces before and after the pipe symbol are optional (as well as any spaces or indenting at the beginning or end of a line) but can add to the readability of the config file, so are highly recommended.

Within an Artist Theme, there are essentially 2 types of config files:

1. The “Master Theme” config file, which is always called “theme.cfg”. This is the main config file that the Jamroom Theme Parser will open when it begins generating an Artist Theme. Within this config file you will find references to Sub-Config Files and Theme Templates.
2. “Sub-Config” files are special configuration files that tell the Jamroom Theme Parser that you want to loop a set of templates a certain number of times, depending on the number of such items the Artist has loaded in their Jamroom Artist Page. These sub config files are identified by a file extension of “cfg”, as well as certain key-words that are contained within the file name itself. For example, “song.cfg” would be a Song Sub-Config file. “store_items.cfg” would be a Store Sub-Config file, and so on.

One thing to note here: ALL processing of Songs, Store Items, Messages, Radio Stations and Calendar Entries will happen within a Sub-Config file.

The master theme.cfg file is REQUIRED (Jamroom will error without it) and is the primary config file that Jamroom parses in order to see everything it needs to work on. It contains a list of DIRECTIVES on the left hand side and OUTPUT files on the right. Note that the Output files may contain Output File Name Variables in their name to enable the Jamroom Theme parser to create multiple output files of the same “type”, but more on that later (along with a complete list) in the VARIABLES section.

An example of a Master Theme config file is given above, in the Overview section.

Sub-Config files may at first seem a bit confusing, but their use in the generation of an Artist Theme is very important. It is the presence of a Sub-Config file within the Master Theme config file that tells Jamroom it must process the contents of the Sub-Config file once per entry of the type specified by the name of the Sub-Config file. So for example - lets say an Artist had 3 songs in their Jamroom. When Jamroom is generating the output pages for their Artist Site, when it gets to the “song.cfg” file in the Master Theme config file, it will process the contents of the song.cfg file 3 times in a row. So within the song.cfg file you would place the order of templates that you would like parsed for each song. Here the details on the allowed Sub-Config files:

Song config files are identified by the keyword “song” located ANYWHERE within the config file name. That is, you could name your song config file songs_output_1.cfg or cool_song_list.cfg and Jamroom will identify those config files as song config files. Also, you can have as many song config files in a theme.cfg file as you like. Song config files can have A LOT going on in them, so pay close attention to this section since it is within here that Jamroom will be doing most of the work and parsing. First, lets see what a typical song.cfg file might look like:

song_header.tpl
song_hifi_stream.tpl
song_lofi_stream.tpl
song_hifi_download.tpl
song_lofi_download.tpl
song_lyrics.tpl
song_information.tpl
song_footer.tpl

As you can see, there are several template file names within our song.cfg Sub-Config file, and their names suggest their content. However, Jamroom does something unique within the song.cfg file - depending on the name of the template file. There are 6 “keyword templates” that Jamroom is looking for within a Song Sub-Config file:

1. hifi_stream - is there a HiFi version of this song?
2. lofi_stream - Is there a LoFi version of this song?
3. lyrics - Were lyrics entered for this song?
4. information - Was Song Information entered for this song?
5. hifi_download - Have Hifi Downloads been ALLOWED for this song?
6. lofi_download - Have Lofi Downloads been ALLOWED for this song?

If the template filename contains one of these keywords, Jamroom first checks to see if there is data for that type in its database - if so, it parses the template file and adds its output to the output file specified in the theme.cfg file.

However, if there is NO DATA of that type in the database (lets say you never uploaded a LOFI version of one of your songs) then the theme engine checks to see if there is an “ALT file” for that template. An ALT file will be named IDENTICAL to the template file, except it would have an “.alt” filename extension on the end of it - i.e.

song_lofi_download.tpl
song_lofi_download.tpl.alt <- this is the "alternate" template

if the ALT file exists, it is used instead of the regular template file, processed and it’s output placed into the output file specified in the theme.cfg file.

This is how Jamroom can dynamically change the output HTML based on what it comes across in the database.

Song config files have access to the following Jamroom Theme variables:

1. ARTIST VARIABLES
2. SONG VARIABLES
3. MISC VARIABLES

Store Sub-Config files contain the templates that you want parsed for each Store Item by an Artist. If the Jamroom Theme parser sees the keyword “store” anywhere in the file name (i.e. “store_items.cfg”, “store.cfg”), it will treat the file as a Store Sub-Config file.

Store config files have access to the following Jamroom Theme variables:

1. ARTIST VARIABLES
2. STORE VARIABLES
3. MISC VARIABLES

Message Sub-Config files contain the list of templates (or template) that you want parsed for each message the Artist has entered (that is not hidden). If the Jamroom Theme parser sees the keyword “message” anywhere in the file name it treats it as a Message Sub-Config file. Message Sub-Config files do however have 1 thing that is different about them: In order to get the “Read More...” link to work correctly, the Message Sub-Config file for the “message more” page must come BEFORE the config file for the regular message config file. The best way to illustrate this is to look at the sample theme.cfg file, shown at the top of this page:

message_more.cfg | message_more_{MESSAGE_ID}.php
message_text.cfg | index.php

You can see the message_more.cfg file comes BEFORE the message_text.cfg file, and outputs its data to a SEPERATE page (one per message id in this case). Since BOTH are message Sub-Config files, they have access to the entire message, including the message ID, and this is how the Theme engine creates the correct link to the Message More page (via the Read More... link)

Message config files have access to the following Jamroom Theme variables:

1. ARTIST VARIABLES
2. MESSAGE VARIABLES
3. MISC VARIABLES

Radio Sub-Config files contain the templates that you want parsed for each Radio Station by an Artist. If the Jamroom Theme parser sees the keyword “radio” anywhere in the file name (i.e. “radio_list.cfg”, “artist_radio.cfg”), it will treat the file as a Radio Sub-Config file.

Radio config files have access to the following Jamroom Theme variables:

1. ARTIST VARIABLES
2. RADIO VARIABLES
3. MISC VARIABLES

Calendar Sub-Config files contain the templates that you want parsed for each Calendar Entry by an Artist. If the Jamroom Theme parser sees the keyword “calendar” anywhere in the file name (i.e. “calendar_events.cfg”), it will treat the file as a Calendar Sub-Config file.

Calendar config files have access to the following Jamroom Theme variables:

1. ARTIST VARIABLES
2. CALENDAR VARIABLES
3. MISC VARIABLES

Photo Sub-Config files contain the templates that you want parsed for each Photo Gallery entry by an Artist. If the Jamroom Theme parser sees the keyword “photo” anywhere in the file name (i.e. “photos.cfg”), it will treat the file as a Photo Sub-Config file.

Photo config files have access to the following Jamroom Theme variables:

1. ARTIST VARIABLES
2. PHOTO VARIABLES
3. MISC VARIABLES

User Sub-Config files contain the templates that you want parsed for each User Account associated with an Artist or Member Profile. If the Jamroom Theme parser sees the keyword “user” anywhere in the file name (i.e. “users.cfg”), it will treat the file as a User Sub-Config file.

User config files have access to the following Jamroom Theme variables:

1. ARTIST VARIABLES
2. USER VARIABLES
3. MISC VARIABLES

Video Sub-Config files contain the templates that you want parsed for each Video entry by an Artist. If the Jamroom Theme parser sees the keyword “video” anywhere in the file name (i.e. “videos.cfg”), it will treat the file as a Video Sub-Config file.

Video config files have access to the following Jamroom Theme variables:

1. ARTIST VARIABLES
2. VIDEO VARIABLES
3. MISC VARIABLES

Theme template files are defined by the “.tpl” extension on the file name. These template files contain HTML, PHP Code, Jamroom Theme Variables, or pretty much anything you want them to contain - they are parsed by the Jamroom Theme engine, where their output is added to the output page. Jamroom will look for certain “Theme Variables” and replace those variables with the actual text retrieved from the Jamroom database.

For example, say you have a template file called “page_header.tpl” and you wanted Jamroom to parse that file, and place the parsed output into the index.php file (this file will be created in the band’s directory when they Generate HTML). Your entry in the theme.cfg file would be:

page_header.tpl | index.php

Lets say its a simple template file and merely contains this:

<html>
<head>
<title>This is the Title of the Index Page</title>
</head>
 
<body>
Welcome to the <b>{BAND_NAME}</b> Website!
</body>
</html>

Now I know this is an extremely simple html page, but it will show you how it works. Since template files are parsed, the name of the Artist would be placed where the {BAND_NAME} template variable is located. Jamroom parses the template files line by line, and depending on which Theme Variables it has access to, it will search and replace all Theme Variables it encounters.

So with that in mind, it is helpful to remember:

1. All template files are parsed, and any Theme Variables encountered will be replaced with the actual data from the Jamroom database.
2. Config files (ending in .cfg) are used to tell Jamroom the order you want things parsed in. A config file does not contain any text that is output to the finished HTML.
3. The template files are what will make up the bulk of your theme, but also is where you can get creative. The BEST thing to do when first starting out with a theme, is to make a complete copy of an existing theme in ANOTHER directory, and begin to change things around in it and see how it works.

There is a “Master Control” file located within the Theme Directory: config.cfg.php

This file is a control file that Jamroom looks for in order to acquire the theme directives it needs in order to correctly size the theme images, as well as show the theme author, copyright, description, etc. The easiest thing to do with this file is copy the file over from an existing theme and modify it to suit your new theme. ²⁾

There are several settings within the config.cfg.php file that give you control over how the Artist Theme operates ³⁾:

Here’s an example config.cfg.php file (from the “Infra-Red” Artist Theme):

<?php
//--------------------------------------------------------------
// Jamroom "Infra-Red" Artist Theme - config.cfg.php
// copyright 2003 - 2005, Talldude Networks LLC
// bigguy@jamroom.net / http://www.jamroom.net
//--------------------------------------------------------------
 
// theme name - this is the name as it will appear in the
// admin menu.
$themecfg['theme_name'] = 'Infra-Red';
 
// theme author - this is the author's name or email address
// that can be utilized in the output HTML
$themecfg['theme_author'] = '&copy; 2003 - 2005 by
<a href="http://www.jamroom.net">Talldude Networks, LLC.</a> /
bigguy@jamroom.net';
 
// this next settings is used to identify to Jamroom the name
// of the Thumbnail image for this theme.  Note that all images
// must be in the images subdirectory.
$themecfg['thumbnail'] = 'thumbnail.png';
 
// this next settings is for the linked screenshot that a user
// can see if they click on the thumbnail.
$themecfg['screenshot'] = 'screenshot.png';
 
 
// this next part is the theme description.  Feel free to use
// HTML and other markup in this tag as it is what will appear
// in the theme browser window
$themecfg['description'] = "Infra-Red is a multi-styled theme
featuring individual pages for your Artist Messages, Songs, Items,
Events, Photos and Stations. (Click on the thumbnail for a bigger
screenshot)";
 
// smarty_theme - if this is set to "yes", then it means the
// templates used in this theme are Smarty templates
$themecfg['smarty_theme'] = 'yes';
 
// required_version - does this theme require a certain version
// of Jamroom to function correctly.  Note - this setting is the
// MINIMUM version needed.  If left blank then a check will not
// be performed.
$themecfg['required_version'] = '2.50';
 
//--------------------------------------------------------------
// THEME STYLE VALUES
//--------------------------------------------------------------
// CSS styles - you can define here extra styles that will be
// made available to the artist
$themecfg['styles'] = array(
  'style_red'    => 'Red (default)',
  'style_blue'   => 'Blue',
  'style_rwhite' => 'Red and White'
);
 
// and define a default style - this will be the style used by
// default if the artist has not defined a style
$themecfg['default_style'] = 'style_red';
 
//--------------------------------------------------------------
// THEME OPTION VALUES
//--------------------------------------------------------------
// this next text string is used to continue a message post,
// indicating there is more to read.
$themecfg['message_more'] = 'Read More...';
 
// the next 3 values define what the text is for:
// "Total Count" - the total number of streams/downloads
// "Total Streams" - total number of song streams
// "Total Downloads" - total number of song downloads.
$themecfg['c_total'] = "Total Plays";
$themecfg['s_total'] = "Total Streams";
$themecfg['d_total'] = "Total Downloads";
 
// Theme Image height/width declarations
// all values are in pixels
$themecfg['band_img_width']  = 780;
$themecfg['band_img_height'] = 200;
// song images
$themecfg['song_img_width']  = 128;
$themecfg['song_img_height'] = 128;
// item images
$themecfg['item_img_width']  = 128;
$themecfg['item_img_height'] = 128;
 
// Random Number Limits - these numbers define the MIN and MAX
// random number that can be returned for the {RANDOM_NUMBER}
// Theme Variable
$themecfg['random_hi'] = 9;
$themecfg['random_lo'] = 1;
 
// POPUP window width/height
$themecfg['popup_width']  = 450;
$themecfg['popup_height'] = 500;
?>

There is a new feature to Jamroom Artist Themes that became available with the release of Jamroom 2.50 - “User Selectable Styles”. This new feature allows you to create an Artist Theme, as well as create several CSS sheets that can alter the colors, layout, content, etc. of the Artist Theme. Jamroom will then present the Artist a drop-down list of “styles” that they can then apply to the Artist Theme. This allows you to offer an Artist Theme (for example) that features many different color combinations and styles - saving you time by not having to create an individual Artist Theme for each style.

The key to using this new feature are 2 new settings in the config.cfg.php file - the “styles” array, and the “default_style” setting. Here is an example from the “Infrared” theme that comes with Jamroom (we’ll use this as an example):

//--------------------------------------------------------------
// THEME STYLE VALUES
//--------------------------------------------------------------
// CSS styles - you can define here extra styles that will be
// made available to the artist
$themecfg['styles'] = array(
  'style_red'    => 'Red (default)',
  'style_blue'   => 'Blue',
  'style_rwhite' => 'Red and White'
);
 
// and define a default style - this will be the style used by
// default if the artist has not defined a style
$themecfg['default_style'] = 'style_red';

The first thing to notice is that we are NOT using the “.css” extension on any of the names in our configuration settings - it is highly recommended that you do the same. The $themecfg[’styles’] setting is a PHP ARRAY - it is very important that it be in the correct PHP syntax or your theme will not work. Each line should be entered like this:

‘<css sheet without .css extension>’ ⇒ ‘<description artist will see in theme browser>’,

For each line you place in the “style” array, a corresponding entry will be made available to the User in the drop-down menu in the Theme Browser section of the Artist Menu. When the User selects a style, and re-generates their theme, Jamroom will take the css sheet name and place it in the {SITE_STYLE} variable, which can be used in your Artist Theme templates. This means you will want to use {SITE_STYLE} throughout your templates in those places where you need to use the style name that chose (i.e. in linking to the style sheet, linking to style image directories, etc.).

“Out of the Box”, Jamroom comes with many pre-defined variables for your use in the Artist Theme templates.

If however, you would like to add your own custom variables for your use within your Artist Theme templates, there is an easier way to do it then having to modify the Jamroom code to do so. Note it is HIGHLY recommended that you have a general understanding of PHP syntax at this point, since this involves the editing of a PHP file. Any syntax errors in the file will generate errors if you attempt to Generate your Artist Pages.

You will find the “theme_extra.cfg.php” file located in your jamroom/config directory. It is within this file that you will add/remove PHP code, and manipulate the contents of a PHP array to “execute” any code when an Artist Page is generated, or to add additional Artist Theme variables. The default contents of the file look like this:

<?php
#---------------------------------------------------------------
# theme_extra.cfg.php
# This PHP file (it MUST be a valid PHP file) allows you to
# define extra Theme variables for your use in your Jamroom.
# it can also be thought of as a "hook" into the theme generation
# process, whereby any PHP commands entered into here will be
# executed whenever an artist generates their theme. Note that>
# any errors in this file will cause the theme generation to
# BREAK, so be careful what you do here. This file uses PHP's
# include() function to source this file.
#---------------------------------------------------------------
# the extra theme variables MUST be in the $_extras array or they
# will not be included.

$_extras = array(
  'EXTRA_THEME_VARIABLE' => '<font color="#FF0000">This is an extra variable!</font>',
  'EXTRA_THEME_VARIABLE_2' => 'Some other text'
);
?>

You can easily add extra variables to the $_extras PHP array like so:

$_extras = array(
  'EXTRA_THEME_VARIABLE' => '<font color="#FF0000">This is an extra variable!</font>',
  'JAMROOM_OWNER_NAME' => 'bigguy'
);

You can see here we have added a new variable called “JAMROOM_OWNER_NAME”. Now we can use this new Artist Theme variable in any of the theme templates, and wherever “{$JAMROOM_OWNER_NAME}” appears in the templates, it will be replaced with “bigguy” when the Artist Page is generated.

Of course this is a very simple representation of what can be done with this file, but the file is SOURCED (via PHP include()) so any PHP code is EXECUTED that is located within this file. This could allow you to add in an extra “action” when the Artist Page is generated.

• Artist Template Variables
• Song Template Variables
• Message (Blog) Template Variables
• Store Template Variables
• Radio Template Variables
• Calendar Template Variables
• Photo Template Variables  (requires Jamroom Power Pack)
• Video Template Variables  (requires Jamroom Power Pack)
• Miscellaneous Template Variables

Hopefully this document has helped you get a better understanding of how the Jamroom Theme’s work, as well as given you a valuable reference you can use to develop themes of your own. If you do develop a theme of your own, and would like to share it with others, please consider submitting it for inclusion on the Jamroom.net download page. Please send an email to support@jamroom.net if you are interested. Thanks!!

1) shift-backslash
2) Note: WITHOUT the config.cfg.php file, Jamroom will assume your theme is only Jamroom 1.x compliant, and will not offer as many features for you to use in your theme.
3) Note: the config.cfg.php file MUST be a valid PHP file - any PHP errors within the file will cause PHP syntax errors!
4) This feature is supported in Jamroom 2.50 and newer only