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

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

Jamroom Play Script Index Jamroom Ranking System - Common Template Variables

Using the Jamroom Ranking System

The Jamroom Ranking System can be thought of as the "swiss army knife" of Jamroom scripts - it is extremely flexible, and is used as a general purpose "lister" for items and elements in your Jamroom.  If you are looking to do any of the following:

  • “Spotlight” a single Artist, group of Artists, or song, video, etc.
  • Create dynamic “Top” lists of Songs, Artist and Radio Stations
  • Generate User Lists for use by the Master Admin
  • Create “ranked” lists of the number of times an Artist Page has been viewed, a song has been played, etc.
  • Generate dynamic, on demand play lists using any of the ranking criteria
Then the Jamroom Ranking System is what you will be using - the Jamroom Ranking System can do that, and a whole lot more.


The JRS consists of a central script “ranking.php” which makes use of Smarty “template” files for it's presentation.  For the most part, the Jamroom Ranking System will expect to find the templates it uses in the Jamroom Active Skin directory (i.e. jamroom/skins/Cobalt), although the templates, if specific to a certain Artist / Member Theme, can also be found in a Theme directory.

Note: the ability for an artist or song to be included on the output of a ranking call is determined by the “Allow Ranking” option in the Jamroom Artist Quota. Make sure the “Allow Ranking” is set to yes or you will not be able to see that Artist (or their songs) on any of the ranking.php output pages. Furthermore, for an artist to be spotlighted by the Jamroom Ranking System, the “Allow Spotlight” quota option must also be set to yes.


There are several ways the Jamroom Ranking System can be run.  Listed in order of recommended usage, they are:

  • Embedded within another Jamroom template use the {jr_ranking} template function (recommended):
{jr_ranking mode="spotlight" row_template="jr_spotlight_row.tpl"}
  • Called via a URL and embedded in a template using the PHP include() function, or if inside a Jamroom template, the {jr_fetch} template function:

<?php include("http://yoursite.com/ranking.php?mode=spotlight&row_template=jr_ranking_spotlight.tpl"); ?>

{jr_fetch file="`$JAMROOM_URL`/ranking.php?mode=spotlight&row_template=jr_spotlight_row.tpl"}

  • Directly via the Location bar of your browser

It's recommended that you use the first method listed above - the embeddable {jr_ranking} template function, as it will avoid a second web server call and is generally much faster.

Tip: If you would like to “mask” the URL that you need to call when generating an output list from the Jamroom Ranking System, use the Jamroom Link Masker tool available from the Jamroom Tools menu.

Operational Modes

The Jamroom Ranking System operates in one of 19 different “modes” that determines the type of output you will see.  The different modes correspond to the different types of "items" that are available within Jamroom.  Since the majority of configuration options are different based on the "mode" the Jamroom Ranking System is run in, each Mode has it's own documentation page that lists the available mode "orders", as well as variables available for each mode.

The following Modes are available
* Requires Jamroom Bonus Pack installed
** Requires Jamroom Power Pack installed
*** Requires Jamroom Payment Pack installed

Common Function Parameters

The following parameters work with all "modes" of the Jamroom Ranking System.  The "type" of parameter defines what is allowed as a value for the given parameter:
  • string - a "string" can be anything - a number, text string, name, etc.
  • number - a valid number must be given - i.e. "25".
  • mixed - a "mixed" type means the parameter accepts one of 3 different data types:
    • a single number - i.e. "25"
    • a range of numbers separated by commas - i.e. "2,6,7,21"
    • an array of numbers that has been built using the {jr_array} template function.
  • true - a "true" type means the parameter is in effect if it is set to ANY value.
mode string n/a yes The "mode" parameter tells Jamroom which "mode" the Jamroom Ranking System is working in.  Valid Ranking System modes are listed above in the "Operational Modes" section.
order number 1 no The "order" parameter tells Jamroom the "order" that you want to run the Ranking System in.  The number of "orders" supported by a given mode varies depending on the mode selected.  See the individual Mode pages for lists of supported Ranking orders.
show number n/a no If a number is given for the "show" parameter, then only the number of entries given will be "shown".  "show" overrides any pagebreak parameter.
pagebreak number n/a no If a number is given for the "pagebreak", then the number given will control how many results are returned on each page of the result set.
pagenum number 1 no If a "pagenum" parameter is given, then the result set will start on the given page number.
band_id mixed n/a  no If the band_id parameter is given, then only entries from the given band_id(s) will be shown.
quota_id mixed n/a no If the "quota_id" parameter is given, then only entries from the given quota_id(s) will be shown.
replace array n/a no If the "replace" parameter is given as an array (this must be prepared beforehand with the {jr_array} template function), then Jamroom will make the replace values available as template variables - i.e. {$REPLACE_0}, {$REPLACE_1}, etc.
header_template string n/a no If the "header_template" parameter is given, then the template that is specified will be used as the header template in the output.  This template must be located in the Active Skin Directory.
row_template string n/a yes The "row_template" defines the template that will be used to process each "row" in the result set.  This template must be located in the Active Skin Directory.  This parameter has been marked as "required", although no error will be emitted if you do not give a row_template.  However, without a row_template, you will not see any output, so in essence it is "required".
footer_template string n/a no If the "footer_template" parameter is given, the the given template will be used the footer template in the output (i.e. it will be processed after the header and rows have been processed).  This template must be located in the Active Skin Directory.
search_area string n/a no If a "search_area" parameter is given, then the Ranking System will "search" the given search_area for the given search_string parameter.  Multiple search_areas may be given, as long as all given search_area values are supported in the given mode.  Use the {jr_array} Template function to build the search_area array.
search_string string n/a no If a "search_string" is given, then Jamroom will search any "search_area" parameter for the given search string.  Multiple search_string values may be entered by using the {jr_array} template function to build the necessary search_string value.
order_by string n/a no If you would like to "order" the output of the Ranking System by a specific table column, you can specify that table column using the order_by parameter.
order_dir string n/a no If you would like to select the "direction" the results are ordered by, you can specify a value of "ASC" (for ascending order) or "DESC" for descending order.  FOr numeric sorting, you will want to use an order_dir of "DESC" to order from high to low, and for alphanumeric ordering you want to use a order_dir of "ASC" so the results are in alphabetical order.
strict_search string n/a no The "strict_search" parameter gives you fine-tuning ability over "how" Jamroom matches a string in the given search_area.
  • By default, Jamroom will search for a string that is any part of another string.  For example - if you search for the search_string "top", it would return results for "stop" and "topper".
  • Alternately, you can set "strict_search" to "left" - this means the search_string must match the left-side of the string - so "top" would match "topper", but not "stop". 
  • Specifying a value of "right" for strict_search means the search_string must match the right-most part of the string, so searching for "top" would match "stop" but not "topper".
  • Specifying a value of "both" requires an exact match in the column - therefore "top" would only match "top" and not "top star".


Tip: You can use a search_string of "_" (underscore) to grab ALL results.  This allows you to use the order_by and order_dir options to sort by your Custom Fields, and gives you virtually an unlimited number of ways to sort your results.


The Jamroom Ranking System uses "Templates" to allow the output to be shaped any way you want.  Make sure and check out the "Working with Jamroom Templates" documentation for details about using the Jamroom Template system.

Example Template Function calls

The following examples show the use of the {jr_ranking} template function - this is the recommended method for embedding Jamroom Ranking System calls directly into other templates:

  • "Spotlight" a single song in from your Jamroom

{jr_ranking mode="spotlight" row_template="jr_ranking_spotlight.tpl"}

  • List Artist Profiles alphabetically

{jr_ranking mode="artist" row_template="jr_ranking_row.tpl"}

  • List all Audio Genres in your Jamroom

{jr_ranking mode="song" order="6" row_template="song_row.tpl"}

As you can see, by passing in the desired parameters, you can create listings of almost any type and order for the items in your Jamroom.

* Jamroom 3.1 and newer only

Jamroom Play Script page 55 of 185 Jamroom Ranking System - Common Template Variables
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