The Jamroom 4 Advanced Charts
The Jamroom Advanced Charts are part of the Jamroom Bonus Pack - a special collection of programs and features that are available to licensed 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 and video (if you have the Jamroom Power Pack installed) in Jamroom, and that data is then used to determine the movement of songs and videos up and down the charts.
The Jamroom charts are extremely modifiable, and can be easily integrated into your site - allowing you to do the following and more:
-
Chart based on Total Plays (streams + downloads), Streams only, or Downloads Only
-
Chart based on individual Song and Video movement within a genre or groups of genres
- Create charts that encompass any start date, end date, or "range" of dates
- Create charts based on Jamroom Quotas, or individual groups of artists
Configuration
The Jamroom Charts consists of a central script “chart.php” which makes use of Jamroom template files, which will be placed in the "skin" 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 chart.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 chart.php script is allowed to use here.
NOTE: This setting does not mean that Jamroom 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 chart.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.
Usage
The Jamroom Advanced Charts work best when "embedded" into an existing template, or when a new template is created to "hold" the charts. For example, we could create a page called "top_40_charts.tpl" in the jamroom/skins/Cobalt3 directory (assuming that the "Cobalt3" Jamroom Skin is the Active Skin), with this inside:
{jr_chart type="audio" pagebreak="40" header_template="jr_chart_header.tpl" row_template="jr_chart_row.tpl" footer_template="jr_chart_footer.tpl"}
Save the file, then "call" it using Jamroom's Template Processor:
http://yoursite.com/jamroom/index.php?t=top_40_charts
You will see the output of a chart in your browser - it's that easy. Now that you have seen how to "call it", it's just a matter of modifying the {jr_chart} function call with different parameters to suit your needs, and possibly modifying or creating custom templates to get the output looking exactly as you want it.
Jamroom Chart Parameters
| Parameter |
Type |
Default |
Required |
Description |
| order |
number |
1 |
no |
the order argument (default is 1) relates to one of the list-orders that the Jamroom Advanced Charts can do. The available order numbers are:
- 1 - (default) Setting the "order' parameter to 1 tells Jamroom to create a Chart that ranks Songs by total plays (streams + downloads).
- 2 - an "order" parameter of 2 tells Jamroom to chart the songs by number of streams.
- 3 - an "order" parameter of 3 tells Jamroom to chart the songs by the number of downloads.
|
| pagebreak |
number |
25 |
no |
The "pagebreak" parameter will “paginate” the Result set into pages, with the "pagebreak" number of entries on each page. If this value is not given, the default will be the number set in the Jamroom Config -> Chart and Ranking Settings -> Default Results Per Page. |
| pagenum |
number |
1 |
no |
this variable tells Jamroom the page number in the output set to start on. This must be used in conjunction with the "pagebreak" parameter. |
| show |
number |
n/a |
no |
the "show" parameter can be used to limit the number of entries shown - it is optional, and it’s value will be overridden if a "pagebreak" parameter is used at the same time. |
| genre |
mixed |
n/a |
no |
The "genre" parameter allows you to define the Song Genre you want to create the chart for.
 Note: When creating a Jamroom Chart based on a specific genre (or group of genres), the "order" parameter is automatically set to "1" since Jamroom does not chart streams and downloads separately by genre. |
| chart_days |
number |
1 |
no |
The "chart_days" parameter tells Jamroom how many "days" you want to chart, counting backwards from the current day. For example, a chart_days of "7" will create a Jamroom Chart that shows the movement and plays of songs over the previous week. |
| max_songs |
number |
n/a |
no |
The "max_songs" parameter allows you to define the Maximum number of songs by any ONE artist that will appear in the Jamroom chart. |
| band_id |
mixed |
n/a |
no |
The "band_id" parameter allows you to create a Jamroom Chart that includes songs only from the specified band_id (or group of band_id's). |
| quota_id |
mixed |
n/a |
no |
The quota_id parameter allows you to build a Jamroom Chart that only contains songs from Artists in the specified Jamroom Quotas. |
| header_template |
string |
n/a |
yes |
This variable tells Jamroom the name of the template file (must be located in the Active Skin directory) to use for the HEADER section of the output (i.e. before the rows are displayed).
Note: If you do not wish to have a header template, leave the value empty - i.e. "header_template=". |
| row_template |
string |
n/a |
yes |
This variable tells Jamroom the name of the template file (must be located in the Active Skin directory) to use for the ROW sections of the output. |
| footer_template |
string |
n/a |
yes |
This variable tells Jamroom the name of the template file (must be located in the Active Skin directory) to use for the FOOTER section of the output (i.e. after the rows have been displayed).
Note: If you do not wish to have a footer template, leave the value empty - i.e. "footer_template=". |
| month |
number |
n/a |
no |
The "month" parameter tells Jamroom to create a Jamroom Chart for a specified MONTH. The month must be given as a zero-padded number if it is less then 10 - i.e. "07". |
| year |
number |
n/a |
no |
The "year" parameter tells Jamroom to create a Jamroom Chart for the specified YEAR. This can be used in conjunction with the "month" parameter to create a Jamroom Chart for a specific month in the past. |
| start_date |
number |
n/a |
no |
The "start_date" parameter lets you define the exact start date for the Jamroom chart. The format must be YYYYMMDD. |
| end_date |
number |
n/a |
no |
The "end_date" parameter lets you define the exact end date for the Jamroom chart. The format must be YYYYMMDD. |
Templates
Any templates created for use with the Jamroom Advanced Charts need to be placed into the "Active Skin" directory - i.e. jamroom/skins/Cobalt3. This is where Jamroom will look to find the templates specified - if they are not found there, you will see an error appear telling you that Jamroom was not able to find the requested template file.
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 in as parameters. 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 skin directory can get quite full of template files.
|
