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.
Configuration
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 (using the "spotlight" or "video_spotlight" modes), the “Allow Spotlight” quota option must also be set to yes.
|
Usage
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
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. |
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.
| 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 |
no |
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 (unless the tpl_dir and skin parameters are used). By default, Jamroom will look for a file called "jr_ranking_row.tpl" in the active skin directory. |
| 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. |
search_min
|
number |
n/a |
no |
If the search_area/search_string combination you are using is numeric, you can set a search_min value if you would like to only return values that are greater than or equal to the search_min value. * |
search_max
|
number |
n/a |
no |
If the search_area/search_string combination you are using is numeric, you can set a search_max value if you would like to only return values that are less than or equal to the search_max 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".
|
exclude_area
|
string |
n/a |
no |
The "exclude_area" parameter allows you to exclude specific searchable database columns from a ranking query. * |
exclude_string
|
string |
n/a |
no |
If an "exclude_string" is given, then Jamroom will ensure that any "exclude_area" parameter does NOT contain the exclude_string. Multiple exclude_string values may be entered by using the {jr_array} template function to build the necessary exclude_string value. * |
| jr_active_mode |
bool |
n/a |
no |
The "jr_active_mode" parameter is a special ranking function parameter for use in theme templates. The ranking system will check to see if jr_active_mode has been set, and, if so, will output the generated ranking code directly to the file (i.e. so that it is "static"), permitting you to also use the assign parameter, which is not usually available in theme templates. |
| private_profile |
number |
n/a |
no |
The "private_profile" parameter tells Jamroom to either include or exclude profiles that have been set to "private" by the profile owner. Set this parameter to "0" to show only profiles that are NOT private. Set this parameter to "1" to only show profiles that ARE private. |
| power_user_id |
number |
n/a |
no |
If a "power_user_id" parameter is given, and contains a valid user_id, then only profiles that are associated with the power_user_id will be included in the results. |
|
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. |
Templates
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 4.1.0 and newer only
|
