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):

• 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:

• Directly via the Location bar of your browser

http://yoursite.com/ranking.php?mode=spotlight&row_template=jr_spotlight_row.tpl

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.

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

• artist
• blog
  
• channel **
• comment **
• content
  
• event
• fan *
• favorite *
• member *
• page
• photo **
• radio
• song
• spotlight
• store
• user
• vault ***
• video **
• video_spotlight **

* 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:

PARAMETER	TYPE	DEFAULT	REQUIRED	DESCRIPTION
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".