Jamroom Logo Jamroom 5 Core
is now Open Source!
Follow Jamroom on Twitter!

This document applies to Jamroom 2 only!
For current Jamroom 4 Documentation, visit the main Jamroom Documentation section.

Now that you have had some time to use and understand how Jamroom works, the next (likely) item on your list is going to be how you can begin customizing Jamroom to suit your needs, as well as integrate Jamroom into your current design and style (if you already have an existing web site). Before undertaking the steps necessary for customization, it is recommended that you have some skills in the following area:

  1. HTML - having a good understanding of HTML is really helpful. You’ll be customizing the Jamroom templates, which are HTML and Smarty templates. The more you know about HTML the better you will be able to customize the templates to suit your needs.
  2. Smarty - Smarty is a fantastic and very powerful “templating” system. Templates give you the ability to define your HTML (or javascript, etc.) in a single file, then use it where ever you would like on your site. It also provides the ability to use logic within your templates, which makes them very powerful.
  3. CSS - Understanding how to use CSS (Cascading Style Sheets) can be a big help in customizing Jamroom, since most of Jamroom’s look and feel (including Artist Sites) is controlled via CSS files.
  4. PHP - while not really required, having a basic understanding of PHP can also help, as there are some PHP functions you can use in some of your web pages to “include” the output of another program directly into your page - in essence “embedding” content directly into a page.
  5. Patience - Jamroom is an extremely flexible program, and can likely do almost anything you need it to do. The flip side of having this much flexibility is that some custom configuration can take a while to implement, so don’t try to take it too fast. The more time you spend working on Jamroom, the more you will see common patterns emerge that will help you get where you want to go.

Note: It is not necessary to ever edit any of the main Jamroom PHP files - the look and feel of Jamroom can be customized using the template files and the CSS sheets. Making custom modifications to the actual Jamroom code will make it much harder to keep up with Jamroom updates, as you will have to re-code your changes over and over.

Understanding the Jamroom Directory Structure

Within your Jamroom install you will find several sub-directories. These sub-directories are there for a specific purpose, and are named according to what is contained within them:

  • bands - When a new Artist Account is created within your Jamroom, a numerical sub directory (which corresponds to the Artist’s unique band_id) will be created within the “bands” directory. This is the location of all of your Artist’s sites, and the PHP files that make up their Artist Sites.
  • songs - When a new Artist Account is created in your Jamroom, a numerical sub directory is also created in the “songs” directory. This directory will be used to hold all of the Artist’s media files. The “songs” sub directory contains a special .htaccess web server directive file, which prevents web users from “browsing” the directory structure.
  • uploads - When a new Artist Account is created in your Jamroom, a numerical sub directory is created in here as well. If you are allowing “imports” into your Jamroom, this is the directory the artist’s media files will be located in before importing. After being imported the media files can be removed.
  • config - The Jamroom Advanced Config file (settings.cfg.php) is stored within this directory, as well as few other config files and post_user plugins.
  • logs - If you have enabled the “Audit Log” for tracking song and video streams and downloads, your daily audit log is written in CSV format to this directory.
  • include - The Jamroom library files are stored within this directory. The library files contain common functions used throughout Jamroom by the PHP scripts.
  • templates - Smarty template files used by the various Jamroom scripts are located in sub directories within the templates directory.
  • compile - When a Smarty template is rendered, it is first “processed” by Smarty into an intermediate PHP code file. Those cached files are stored in the “compile” directory to speed up the Smarty based templates. These are temporary files, and if deleted, Jamroom will rebuild them as necessary.
  • sample - On a new Jamroom install, a “Sample Artist” can be created to give you an artist account to test with. This sub directory contains the image and MP3 file for use by the Sample artist. This directory can be deleted after installation.
  • language - The language sub directory contains the PHP files for the different languages that Jamroom supports. It is within these files that you would want to modify the text strings to have the User Menu contain the text as you want it to be.
  • themes - This directory contains all of the different “Artist Themes” that are available for your use in your Jamroom. Each Artist Theme will be located within a sub directory within this directory.
  • styles - This directory contains the different “Admin Skins” that control the User Menu and Admin Menu style. You will find CSS sheets for each of the installed Admin Skins located inside, along with a sub directory for each style that contains that style’s images.

For the purposes of customizing the look and feel of your Jamroom, you will be spending the majority of your time in the “templates”, “styles”, “themes” and “language” directories, modifying the files within to suit your needs.

Jamroom's Index Generator

After you have first installed Jamroom, if you load up the Jamroom directory into your web browser, without specifying a file name - i.e.:


You will be presented with the Jamroom index. This index file is one of the first Smarty templates you are going to want to modify. You can find the Smarty template file for the Jamroom index in the “jamroom/templates/index” directory:

templates/index/default_index.tpl templates/index/default_index.css

The “default_index.tpl” is the file that contains the actual HTML code for the front page (as well as Smarty variables and syntax), so to modify how the page layout looks, you’ll want to edit this file. You can also modify (or create a new one if you wish) the default_index.css file, which contains the CSS for styling the index page.

The main index file for Jamroom is generated by the “index.php” script which is located in the Jamroom directory. This script can also be used as a “generic” Smarty template parser. Simply pass the name of the template you wish to display, and the index.php script will generate it. i.e.:


This would make the index.php look for the “new_template.tpl” file in the jamroom/templates/index directory (it must be located in the index directory or it will not work!) The script will then parse the file, and display it. Once you see how powerful Smarty is, and all the features you can do within the template files, using the index.php as a generic Smarty template processor becomes a very valuable option to generating other pages for your site.

Jamroom Script Templates

Many of the scripts that are included with Jamroom are capable of generating custom output - the Jamroom Ranking System (ranking.php), Jamroom Ratings (rating.php), etc. You have full control over how this output looks by modifying the appropriate Smarty template files. All of the template files for the various scripts are located within the jamroom/templates directory, and are organized by Script name. For example, if you wanted to customize the look of a Jamroom Ranking System “Spotlight” call, you would modify the templates in the jamroom/templates/ranking directory. Note that Jamroom verifies that the given template files are actually located in the proper directory - this is done for security reasons. If you were (for example) running the following ranking.php script command:


the “custom_spotlight.tpl” file must be located in the jamroom/templates/ranking directory. If the file does not exists, Jamroom will report an error and exit. If the file does exist (and it is readable by the web user), the ranking.php script will use this template to display the results of the spotlight call.

You will notice that most Jamroom scripts can be passed a “template” parameter - this allows you to define different “looks” for the different pages within your Jamroom. It’s as easy as creating a new template file, and you can change the appearance.

Jamroom Artist Themes

Within the jamroom/themes directory you will find all of your Jamroom’s “Artist Themes”. The Artist Themes are the templates that are used by your Jamroom artists to create their own mini site. There are many different Artist Themes available, and each one can be customized to suit your needs.

Please reference the Jamroom Theme Designers Guide for full information on creating, modifying and customizing Jamroom Artist Themes.

Jamroom "Admin Skins"

Within the jamroom/styles directory you will find the CSS files that are called “Admin Skins”. These CSS (Cascading Style Sheets) files are what give the Jamroom User Menu and Admin Menu their look and feel. If you would like to customize and create your own Admin Skin, you’ll want to make a copy of one of the current CSS files and begin modifying it. For example, you can use the “Jamroom_Default.css” as a baseline, then change the colors, fonts and images to suit your sites unique look. Note that the name of the Admin Skin will be whatever you call the file - so “New_Admin_Skin.css” would be shown as “New Admin Skin” in the interface.

Add Jamroom content to an existing site

You may already be running an existing CMS (Content Management System), or are simply looking for a way to integrate many of the Jamroom features (i.e. rankings, spotlights, charts, etc.) into your existing site. If that is the case, then it is fairly simple to do using PHP‘s “include()” function, or “fetch” as it is called in a Smarty template. The {fetch} function allows you to “embed” the output of a script or page directly into another page (without the need to use frames). So for example, let’s say you want to create a include a top 10 list of “Hard Rock” songs into your Jamroom index page. The Jamroom index page (as shown above) is located at jamroom/templates/index/default_index.tpl. You would modify this file and determine where you would like the list to appear, then put a line like this inside:

{fetch file="http://www.sample.com/jamroom/ranking.php?mode=song&order=5&genre=Hard+Rock&limit=10&row_template=hard_rock_row.tpl"}

Wherever this line is placed in your template file, that is the location it will appear when viewed. The “{fetch}” function places a call to PHP, and out the output of the ranking.php call (in this case using the “hard_rock_row.tpl” template) would be inserted into your index page. You will need to ensure the “hard_rock_row.tpl” file exists in your jamroom/templates/ranking directory or it won’t work. Using {fetch}, you can “pull” Jamroom content into your existing site easily, allowing you to create dynamic content on any page you would like.

Solutions Products Support Community Company
Social Media Platform
Social Networking Software
Musician Website Manager
Community Builder
Jamroom 5
Jamroom 5 Modules
Jamroom Marketplace
Support Forum
Support Center
Contact Support
Community Forum
Member Sites
About Us
Contact Us
Privacy Policy
©2003 - 2024 The Jamroom Network