The Jamroom Advanced Charts are part of the Jamroom Bonus Pack - a special collection of programs and features that are available to registered users of Jamroom. The Jamroom Advanced Charts are advanced tracking “charts”, similar to the Jamroom Ranking System, yet more advanced in features. Jamroom tracks the daily chart position for every song in Jamroom, and that data is then used to determine the movement of songs up and down the charts.

The Jamroom charts are extremely modifiable, and can be easily integrated into your existing home page, artists page, etc. They allow you to:

• Chart based on Total Plays (streams + downloads), Streams only, or Downloads Only.
• Chart based on individual Song movement within Genres (total plays).
• Define separate output templates for the “Top Spot” (number one in over-all or Genre - modifiable), Top Ten songs (modifiable) and by quota. What this means is you can have your “premium” artists be represented by bold text, different background, additional artist image, etc. Since each quota can have its own “row” template, you can really create a unique chart that really shows off your artists.
• Since the Jamroom Charts are more system intensive than the Jamroom Ranking System, the output of the charts can be cached (recommended) in the Jamroom cache tables. You can define within the Jamroom Config the length of a time a page will exist in the cache system before it is expired - at that point, the next call to the Jamroom Chart script (newchart.php) will generate a new chart, and that new chart will be cached in place of the older one. This makes the Jamroom Charts ideal for busy systems, especially for those that would like to place a chart on their front page yet receive many thousands of hits a day.
• Access to the Jamroom Charts is controlled via the “Allow Charting” setting in the Jamroom Quota, allowing you to include only the artists you want to include.

The Jamroom Charts consists of a central script “newchart.php” which makes use of “template” files located within the templates/newchart sub directory of the main jamroom directory.

There are several variables located in the "Charts and Ranks" section of the Jamroom Config (Admin Menu → Jamroom Config → Charts and Ranks settings) that affect the way the Jamroom Advanced Charts work:

• Chart Maximum Memory - When the Jamroom Advanced Charts are generating a new chart (which will happen as frequently as defined in the the Cache Expiration setting), the newchart.php script needs to use System Memory (RAM) to hold the data it needs to construct the charts. The Default value of 256 megabytes should be good for even larger systems, but if you are receiving errors that PHP has run out of memory, you can increase the amount of memory the newcharts.php script is allowed to use here. NOTE: This setting does not mean that the newchart.php will use this much memory, but is allowed to use this much memory as its maximum.
• Chart Maximum Songs - This option allows you to define the Maximum number of songs that can appear on the Jamroom Advanced Charts from a single artist. Setting this to 0 disables this function and will show as many songs from each artist on the charts as the artist has loaded in to Jamroom.
• Chart Top-Spot Count - This number defines the number of songs that will be considered the “Top-Spot” on the Jamroom Advanced Charts. Songs that have been designated as being Top-Spot will use the special “topspot” chart template (if defined). Default is 1.
• Chart Top-Ten Count - This number defines the number of songs that will be considered to be in the “Top-Ten” on the Jamroom Advanced Charts. Songs that have been designated as being Top-Ten will use the special “topten” chart template (if defined). Default is 10.
• Chart Days - The Chart Days setting tells Jamroom how many days ago you want to compare with the current rankings to build the current Chart. This is reflected in the movement of songs up and down the chart. Default is “1” meaning that today’s rankings are compared with yesterday’s rankings to determine chart movement. Note that this is the DEFAULT value, and can be overridden with the proper variable passed to the newchart.php from the URL. NOTE: It is recommended to set this value to somewhere between 4 and 7 on large systems to get the “smoothest” movement of songs on the Charts.
• Chart Change - The Chart Change setting tells Jamroom how many places a song must rise or fall in the Charts in order to be considered “hot” or “cool”. Default is 10.

The newchart.php script is called directly from the browser, or can be called using an Apache SSI (server-side include) or the PHP include() (recommended) function. This will allow you to add the output of the newchart.php script to your own pages. Example entries might look like this (in your html):

PHP‘s include() function

<?php include("http://yoursite.com/jamroom/newchart.php?order=1&pagebreak=50&pagenum=1&header_template=chart_1_header.tpl&row_template=chart_1_row.tpl&footer_template=chart_1_footer.tpl"); ?>

Using Apache SSI (Server-Side Includes)

<!--#include virtual="newchart.php?order=1&pagebreak=50&pagenum=1&header_template=chart_1_header.tpl&row_template=chart_1_row.tpl&footer_template=chart_1_footer.tpl"-->

Note the ? between the newchart.php script name and the first variable. This is REQUIRED and must be used in order to get it to work like you expect it to - after the first variable, the ampersand (&) is used between any other variable that might exist in the URL.

There are additional variables that you can pass into the newchart.php script via the URL. Here is how the usage is displayed - a value with parentheses around it i.e. “(number)” indicates a REQUIRED variable. A value with square brackets around it i.e. “[number]” indicates an OPTIONAL variable that is not required.

newchart.php?order=[number]&pagebreak=[number]&pagenum=[number]&show=[number]&genre=[genre]&chart_days=[number]&header_template=[template.tpl]&row_template=[template.tpl]&footer_template=[template.tpl]&topspot_template=[template.tpl]&topten_template=[template.tpl]&chart_topspot=[number]&chart_topten=[number]

Note how every option to newchart.php is OPTIONAL - none are required, but most likely you will be using some combination of the options to get the output you want. Make sure you at LEAST specify a row_template file or your chart won’t produce an output!  By default, if newchart.php is called, it acts like this:

newchart.php?order=1&pagebreak=(system defined page results)&pagenum=1

This could end up producing a very large chart if you have defined your system wide “max page results” (within the Jamroom Config section) to be a large number. It’s best to use a combination of available options to get the results you want. Here are the definitions for the available options:

The templates that are used by newchart.php are where the real power of the Charts come into play. The following instructions may seem a bit confusing at first - read this section carefully though, and you should be customizing your templates in no time.

Within the templates/newchart sub directory you will see a set of sample Smarty template files (.tpl) that are used by the newchart.php script when it generates its output. It is these templates that you will want to customize to suit your site’s look and feel. There are 3 “sets” of templates, with each set corresponding to the order value given to the newchart.php script. A set may look like this:

chart_1_header.tpl
chart_1_row_topspot.tpl
chart_1_row_topten.tpl
chart_1_row.tpl
chart_1_footer.tpl 

These 5 template files are what would be used to construct the “newchart.php?order=1” call to the script. They consist of:

• chart_1_header.tpl - this is the “beginning” of the HTML output page. This is where the you will most likely put some type of text stating what the chart consists of, links to other pages, etc. It is HTML and can include any of the Header and Footer Variables.
• chart_1_row_topspot.tpl - this is a special OPTIONAL template file, that will be used to construct the row of the TOP SONG in your chart. You may want to include special features for this song - maybe the artist or song image, etc. Whatever you want to do, having this separate “Top Spot” template will allow you to reward your top song. Note that if this template is NOT found, the “chart_1_row_topten.tpl” will be used. If it is not found, the regular “chart_1_row.tpl” template file will be used. The regular row template file is required, and the Jamroom Charts will error without it. It is HTML and can include any of the Row Template Variables.
• chart_1_row_topten.tpl - this is another OPTIONAL row template file - use this to define a different look for those songs that are in the “Top Ten” songs on your chart. If this template is NOT found, the regular “chart_1_row.tpl” template file will be used. The regular row template file is required, and the Jamroom Charts will error without it. It is HTML and can include any of the Row Template Variables.
• chart_1_footer.tpl - this is what will be tagged onto the end of the chart, and usually contains the Legend and the Previous and Next page links. It is HTML and can include any of the Header and Footer Variables.

Note that the naming of the templates is up to you, since you can define them at run time by merely passing the names of the templates into the newchart.php call. It is highly recommended that you define a naming convention though (especially on a large system) if you plan on running many charts, since the templates/newchart directory can get quite full of template files.

• Common Variables available in all Chart Templates
• Variables only available in Chart **row** Templates