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.
- 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
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)
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.
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:
Jamroom Charts URL variables
||the order argument (default is 1) relates to one of the list-orders that the newchart.php script can do. The available order numbers are 1,2 and 3. 1 is to chart by Total Plays (streams + downloads), 2 is to chart by Streams Only and 3 is to chart by Downloads only. The default is “1” so you actually only need to define the order=(number) option if using order 2 or 3.
||this OPTIONAL parameter will “paginate” the results for you into pages. So for example, if you did “newchart.php?order=1&pagebreak=20&pagenum=1”, if your Jamroom had over 20 songs in it it would break them up into pages of 20 songs each.
||this variable tells the newchart.php script to START on that page. This must be used in conjunction with the pagebreak=[number] variable. Usually you will use pagenum=1 here.
||the OPTIONAL show value can be used to LIMIT the number of entries shown - it is optional, and it’s value will be overridden if a pagebreak value has been given on the same URL.
||this optional argument is used to generate a chart for a specific song genre or group of song genres - that is, only songs that are part of that song genre will be included in the chart (with their rankings adjusted to suit). NOTE: the Genre provided MUST be a valid Genre that is configured in your Jamroom, and it MUST be urlencoded if it contains non-alphanumeric characters or spaces. (use a ‘+’ instead of a space). If the newchart.php is unable to determine if it is a valid Genre, it will be ignored. If you are only providing a single genre, you can use the following syntax: &genre=genre+name. However, if you want to create a chart from multiple genres, use the following syntax: &genre=Hard+Rock&genre=Classic+Rock&genre=Punk+Rock, etc. Note that the brackets () are required for the newchart.php script to see the multiple genres.
||This optional number can be used to over-ride the system defined “Chart Days”. The Chart Days tell the Jamroom Charts how many days to look back in history for the comparison chart. The default is 1, meaning that a songs movement up and down the charts is compared with yesterday’s chart position of that same song to determine it’s movement. Using this variable allows you to create “weekly” or even “monthly” charts. Note that if Jamroom is unable to find history for the number of days previous you are requesting, all songs will appear as “new” in the charts.
||This optional number will cause the script to over-ride the “chart_maxsongs” setting in the jamroom/config/settings.cfg.php. The number given will allow the first [number] number of songs on a per-artist basis, with extra songs by the same artist ignored. This can be used to customize the charts on a per-chart basis.
||The band_id option allows you to pull the chart for a specific band_id (or range of band_id’s if more than 1 band_id is given as a band_id array - i.e. “&band_id=5&band_id=7&band_id=9”)
||This variable tells the newchart.php script the name of the template file (must be located in the templates/newchart directory) to use for the HEADER section of the output (i.e. before the rows).
||This variable tells the newchart.php script the name of the template file (must be located in the templates/newchart directory) to use for the ROW sections of the output.
||This variable tells the newchart.php script the name of the template file (must be located in the templates/newchart directory) to use for the TOPSPOT section(s) of the output. Note that NUMBER of times this template is used is directly based on the chart_topspot variable.
Note: It is not necessary to use this template - it is recommended to use "logic" within the row_template to define the top spot behavior. See the default row_template that comes with Jamroom for an example of usage.
||This variable tells the newchart.php script the name of the template file (must be located in the templates/newchart directory) to use for the TOPTEN section(s) of the output. Note that NUMBER of times this template is used is directly based on the chart_topten variable (and you can always do more or less than “ten” spots!)
Note: It is not necessary to use this template - it is recommended to use "logic" within the row_template to define the top ten behavior. See the default row_template that comes with Jamroom for an example of usage.
||This allows you to pass in a different template name that will be used when processing the individual rows for Artists that belong in the [number] quota. For example, if you passed in “"a_5_template=quota_5.tpl”, then when Jamroom is building the output for display, it will use the “quota_5.tpl” template file as the ROW template for Artists whose Artist Quota is 5.
||This variable tells the newchart.php script the name of the template file (must be located in the templates/newchart directory) to use for the FOOTER section of the output (i.e. before the rows).
||This variable tells the newchart.php script how many of the artists will utilize the topspot_template in their output.
||This variable tells the newchart.php script how many of the artists will utilize the topten_template in their output.
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:
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.