Overview
When you first install Jamroom and start building your first artists within Jamroom, you will probably soon wonder if there is a way to create a “master index” of some sorts - possibly a list of all of the bands that are within Jamroom so your visitors can just click on a link and be taken directly to that band’s site. The Jamroom Ranking System was designed to do that, and much more. Using the Jamroom Ranking System you can create customized “Top 40” lists, “phone book” pages for your users of Jamroom, as well as almost any other way to organize Artists, Songs, Users, Stations, Items, etc. that you might need. Following are instructions on tailoring the “ranking.php” script templates, which are the center of the JRS, to suit your specific needs, as well as details on how to customize it even further (should you need to do so). Using the Jamroom Ranking System, you can accomplish the following:
-
“Spotlight” a single, or group of Artists within your Jamroom
-
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.
-
Generate dynamic, on demand playlists using any of the ranking criteria
-
Plus more - the number of options and features you can “pass” in to the ranking.php script make it extremely versatile and flexible.
Configuration
The JRS consists of a central script “ranking.php” which makes use of Smarty “template” files located within the templates/ranking subdirectory off of the main Jamroom 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.
Usage
The ranking.php script is called directly from the browser, or can be called using the PHP include() function. This will allow you to add the output of the ranking.php script to your own pages. Example entries might look like this (in your html):
PHP‘s include() function:
include("http://yoursite.com/jamroom/ranking.php?mode=band&order=3&show=10&row_template=artist_row.tpl");
Tip: If you would like to “mask” the URL that you need to call when generating an output list from the Jamroom Ranking System, you can simply “embed” the whole URL within a small PHP script, then simply call the PHP script instead of the ranking.php URL. For example - create a file called “test_rank.php” in your jamroom directory and place this inside the file:
<?php
include("http://yoursite.com/ranking.php?mode=band&order=3&show=10&row_template=artist_row.tpl");
?>
Now when you call “test_rank.php” from your browser you will see the output of the ranking.php script
Modes
The Jamroom Ranking System will operate in any of 9 “modes”, which are passed into the ranking.php script from the calling URL, and determine the type of data and amount of data the ranking.php script will “rank”:
ranking.php?mode=band
ranking.php?mode=song
ranking.php?mode=user
ranking.php?mode=radio
ranking.php?mode=spotlight
ranking.php?mode=store
ranking.php?mode=page
ranking.php?mode=photo (with Jamroom Power Pack installed)
ranking.php?mode=video (with Jamroom Power Pack installed)
ranking.php?mode=video_spotlight (with Jamroom Power Pack installed)
Note the ? between the ranking.php script name and the first variable, mode. This is REQUIRED and must be used in order to get it to work like you expect it to.
There are also additional variables that you can pass into the ranking.php script via the URL, but they vary depending on the MODE given. Here is how the usage is shown - a value with parentheses around it i.e. “(number)” indicates a REQUIRED field. A value with square brackets around it i.e. “[number]” indicates an OPTIONAL field that is not required.
Band Mode
ranking.php?mode=(band)&order=[number]&show=[number]&pagebreak=[number]&pagenum=[number]&letter[]=[letter]"a[]=[quota]&header_template=[template.tpl]&row_template=[template.tpl]&footer_template=[template.tpl]
Song Mode
ranking.php?mode=song&order=(number)&show=[number]&pagebreak=[number]&pagenum=[number]&genre[]=[genre]&type=[mp3|ogg|wma]&letter[]=[letter]"a[]=[quota]&header_template=[template.tpl]&row_template=[template.tpl]&footer_template=[template.tpl]
User Mode
ranking.php?mode=user&order=(number)&show=[number]&pagebreak=[number]&pagenum=[number]&letter[]=[letter]"a[]=[quota]&header_template=[template.tpl]&row_template=[template.tpl]&footer_template=[template.tpl]
Radio Mode
ranking.php?mode=radio&order=(number)&show=[number]&pagebreak=[number]&pagenum=[number]&letter=[letter]"a[]=[quota]&header_template=[template.tpl]&row_template=[template.tpl]&footer_template=[template.tpl]
Spotlight Mode
ranking.php?mode=spotlight&band_id=[band_id]&show=[number]"a[]=[quota]&genre[]=[genre]&header_template=[template.tpl]&row_template=[template.tpl]&footer_template=[template.tpl]
Store Mode
ranking.php?mode=store&order=(number)&show=[number]&pagebreak=[number]&pagenum=[number]&letter[]=[letter]"a[]=[quota]&header_template=[template.tpl]&row_template=[template.tpl]&footer_template=[template.tpl]
Page Mode
ranking.php?mode=page&order=(number)&show=[number]&pagebreak=[number]&pagenum=[number]"a[]=[quota]&header_template=[template.tpl]&row_template=[template.tpl]&footer_template=[template.tpl]
Photo Mode (Available if Jamroom Power Pack is installed)
ranking.php?mode=photo&order=(number)&show=[number]&pagebreak=[number]&pagenum=[number]"a[]=[quota]&header_template=[template.tpl]&row_template=[template.tpl]&footer_template=[template.tpl]
Video Mode (Available if Jamroom Power Pack is installed)
ranking.php?mode=video&order=(number)&show=[number]&pagebreak=[number]&pagenum=[number]"a[]=[quota]&header_template=[template.tpl]&row_template=[template.tpl]&footer_template=[template.tpl]
Video Spotlight Mode (Available if Jamroom Power Pack is installed)
ranking.php?mode=video_spotlight&band_id=[band_id]&show=[number]"a[]=[quota]&genre[]=[genre]&header_template=[template.tpl]&row_template=[template.tpl]&footer_template=[template.tpl]
Note: Anywhere that a variable is used that contains a [] at the end of the variable name, i.e. &genre[]=[genre], this means that the “genre” variable is an array. This means more than 1 value can be passed in - i.e. &genre[]=Hard+Rock&genre[]=Pop&genre[]=Synth, etc.
Variables
Jamroom Ranking System URL Variables
| URL Variable |
Description |
| mode=(name) |
the mode argument that is passed to the ranking.php script tells the script what data to retrieve, and can be one of 8 values: band, song, video, photo, user, radio, spotlight and store - note that ONLY these 8 values are allowed for the mode variable - any other value for mode that is passed in (or if left empty) will be changed internally to band. |
| order=(number) |
the order argument (default is 1) relates to one of the list-orders that the ranking.php script can do. It varies by mode (but DOES NOT apply to the spotlight mode). |
| show=[number] |
the OPTIONAL show argument can be used to LIMIT the number of entries shown - it is optional (and is not supported in the spotlight mode), and if not included will default to showing ALL - if you have A LOT of bands, songs or users in your Jamroom install, this is helpful. It can also be used along with the song mode to create “Top” lists (i.e. Top 40) |
| pagebreak=[number] |
this OPTIONAL parameter will “paginate” the results for you into pages. So for example, if you did “ranking.php?mode=band&pagebreak=20&pagenum=1”, if your Jamroom had over 20 artists in it it would break them up into pages of 20 artists each. |
| pagenum=[number] |
this variable tells the Ranking System to START on that page. This must be used in conjunction with the pagebreak=[number] variable. Usually you will use pagenum=1 here. |
| letter[]=[letter] |
this variable tells the Ranking System to only get entries whose names START with the given letter. This corresponds with artist name, song name, radio name and user nickname. NOTE: This URL variable can be entered as an array to pass multiple letter values in to the script - i.e. &letter[]=a&letter=b&letter=c, etc. |
| genre[]=[genre] |
this optional argument is only valid when used in conjunction with the “song”, “spotlight”, “video”1) or “video_spotlight”2) modes - it will limit the entries that it returns to an individual Song or Video Genre. 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). NOTE: This variable supports more than 1 genre being passed in - i.e. &genre[]=Hard+Rock&genre[]=Pop&genre[]=Synth, etc. |
| type=[mp3/ogg/wma] |
this optional argument is only valid when used in conjunction with the song mode - it will limit the entries that it returns to an individual Song Type - that is, MP3, OGG, or WMA. |
| quota[]=[quota] |
this optional argument tells the ranking.php script to limit the data it returns to a select quota (or set of quotas). NOTE: This URL variable can be entered as an array to pass multiple quota values in to the script - i.e. "a[]=1"a[]=2"a[]=5, etc. |
| band_id[]=[number] |
This optional URL variable can be used in the “band”, “spotlight”, “song”, “video” and “video_spotlight” modes. It defines a list of band_id’s to use to create the listing from. This can come in handy when you want to “spotlight” an artist for an extended period of time. |
| song_id[]=[number] |
This optional URL variable can only be used in “song” or “spotlight”. It defines a list of song_id’s to use to create the listing from. This can come in handy when you want to “spotlight” a specific song for an extended period of time. |
| video_id[]=[number] |
This optional URL variable can only be used in “video” or “video_spotlight” modes (if the Jamroom Power Pack is installed). It defines a list of video_id’s to use to create the listing from. This can come in handy when you want to “spotlight” a specific video for an extended period of time. |
| replace[]=[replace text] |
This option allows you to pass in “replacement text” that will be parsed out when viewed. This input variable is an array, and will be expanded in to {$REPLACE_0}, {$REPLACE_1}, etc. For example - if you used this on your url: &replace[]=This+is+text+0&replace[]=This+is+text+1 then inside your header and footer templates, wherever you placed {$REPLACE_0}, the text “This is text 0” would be placed. Note that the values must by urlencoded or they will not work!. |
| header_template=[template.tpl] |
This variable tells the ranking.php script the name of the template file (must be located in the templates/ranking directory) to use for the HEADER section of the output (i.e. before the rows). |
| row_template=[template.tpl] |
This variable tells the ranking.php script the name of the template file (must be located in the templates/ranking directory) to use for the ROW sections of the output. |
| footer_template=[template.tpl] |
This variable tells the ranking.php script the name of the template file (must be located in the templates/ranking directory) to use for the FOOTER section of the output (i.e. before the rows). |
Valid Order Values
Note that the “spotlight” and “video_spotlight” modes do not have any order values.
supported order values when using band mode
-
list artists alphabetically (default)
-
list artists by creation date (oldest first)
-
list artists by creation date (newest first)
-
list artists by number of song plays (streaming only)
-
list artists by number of song plays (streaming + downloads)
-
list artists by location alphabetically
-
list artists by number of Artist Ratings received (highest to lowest)
-
list artists by number of Artist Ratings received (lowest to highest)
-
list artists by Artist Rating Average (highest to lowest)
-
list artists by Artist Rating Average (lowest to highest)
-
list artists randomly
-
list artists by number of song downloads
supported order values when using song mode
-
list song names alphabetically (default)
-
list song names by creation date (oldest first)
-
list song names by creation date (newest first)
-
list song names by number of plays (streaming only)
-
list song names by number of plays (streaming + downloads)
-
list song genres loaded in our Jamroom
-
list songs by number of Song Ratings received (highest to lowest)
-
list songs by number of Song Ratings received (lowest to highest)
-
list songs by Song Rating Average (highest to lowest)
-
list songs by Song Rating Average (lowest to highest)
-
list songs randomly
-
list songs by number of song downloads
supported order values when using video mode
-
list video names alphabetically (default)
-
list video names by creation date (oldest first)
-
list video names by creation date (newest first)
-
list video names by number of views (streaming only)
-
list video names by number of views (streaming + downloads)
-
list video genres loaded in our Jamroom
-
list videos by number of Video Ratings received (highest to lowest)
-
list videos by number of Video Ratings received (lowest to highest)
-
list videos by Video Rating Average (highest to lowest)
-
list videos by Video Rating Average (lowest to highest)
-
list videos randomly
-
list videos by number of video downloads
supported order values when using photo mode
-
list photos by name (alphabetically) (default)
-
list photos by name (reverse alphabetical)
-
list photos by time created (oldest to newest)
-
list photos by time created (newest to oldest)
-
list photos by image size (smallest to largest)
-
list photos by image size (largest to smallest)
-
list photos by category (alphabetized)
-
list photos randomly
supported order values when using user mode
-
list user nicknames alphabetically (default)
-
list user nicknames alphabetically (reversed)
-
list user nicknames by creation date (oldest first)
-
list user nicknames by creation date (newest first)
-
list user nicknames by randomly
supported order values when using radio mode
-
list radio stations alphabetically (default)
-
list radio stations alphabetically (reversed)
-
list radio stations by creation date (newest first)
-
list radio stations by creation date (oldest first)
-
list radio stations by number of plays
-
list radio stations randomly
supported order values when using store mode
-
list store items alphabetically (default)
-
list store items alphabetically (reversed)
-
list store items by price (lowest to highest)
-
list store items by price (highest to lowest)
-
list store items randomly
supported order values when using page mode
-
list HTML pages by number of views (highest to lowest)
-
list HTML pages by number of views (lowest to highest)
-
Templates
The templates that are used by ranking.php are where the real power of the ranking system comes 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.
You will find ALL of the templates that the ranking.php script uses inside the jamroom/templates/ranking directory. These template files are Smarty template files, and are very configurable and customizable. Note that since you must pass in the name of the template file(s) you want to use in your ranking.php output, its possible to create a common set of “header” and “footer” template files that can be used over and over again with many different lists and outputs.
For example, lets say for the “header_template” option to the script you gave “my_new_header.tpl” like this:
ranking.php?header_template=my_new_header.tpl
Then the ranking.php script would look for the “my_new_header.tpl” file in the jamroom/templates/ranking folder and use it for the HEADER part of the output. You’ll want to make sure and include a “row_template” as well, since that is likely where you will be showing the “rows” of data you returned. Note though that ALL of the templates are optional, and are not required for the script to function (although if you do not include at least 1 template, you won’t see anything.)
Template Variables
Example URLs
The following examples give you a convenient “cut and paste” set of URL‘s that you can place in your code. Just ensure that you modify the “yourdomain.com” to be the name of your actual domain (or IP address). Note that all of these examples make use of the “default” ranking templates that are shipped with Jamroom. If you have renamed and/or created new custom ranking templates, make sure you use those instead. To test these examples, simply cut and paste them in to your browser, modifying the domain name and path to Jamroom as necessary.
"Spotlight" a Single Jamroom Artist
This URL will generate a single “spotlight” artist block:
ranking.php?mode=spotlight&header_template=spotlight_header.tpl&row_template=spotlight_row.tpl&footer_template=common_footer.tpl
Artists in your Jamroom Alphabetically
This URL will generate a list of all artists in your Jamroom, and list them alphabetically:
ranking.php?mode=band&order=1&header_template=artist_header.tpl&row_template=artist_row.tpl&footer_template=common_footer.tpl
Artists in your Jamroom beginning with the letter "B"
This URL will retrieve all Artists whose artist name begins with the letter “b” (note that it is NOT case sensitive, so both “b” and “B” will be found):
ranking.php?mode=band&order=1&letter=b&header_template=artist_header.tpl&row_template=artist_row.tpl&footer_template=common_footer.tpl
Artist Songs by Total Plays
This URL will generate a list of all songs in your Jamroom, and order them by the total number of plays that each song has received (downloads + streams).
ranking.php?mode=song&order=5&header_template=song_header.tpl&row_template=song_row.tpl&footer_template=song_footer.tpl
Jamroom User Accounts by Date Created
This URL will generate a list of all Jamroom User Accounts (not Artist Accounts), and order them by the date the User Account was created, from oldest to newest:
ranking.php?mode=user&order=3&header_template=user_header.tpl&row_template=user_row.tpl&footer_template=common_footer.tpl
Jamroom Radio Stations by Number of Plays
This next URL will generate a list of Jamroom Radio stations, and order them by the number of times they have been played:
ranking.php?mode=radio&order=5&header_template=station_header.tpl&row_template=station_row.tpl&footer_template=common_footer.tpl
Jamroom Store Items Alphabetically
This URL will list all of the Jamroom Store Items in alphabetical order:
ranking.php?mode=store&order=1&header_template=store_header.tpl&row_template=store_row.tpl&footer_template=common_footer.tpl
Artist Pages by Number of Views
This URL will “rank” the Artist Pages based on the number of page views each has had:
ranking.php?mode=page&order=1&header_template=page_header.tpl&row_template=page_row.tpl&footer_template=common_footer.tpl
"Top 40" list for Hard Rock Genre
This URL will generate a “Top 40” list for the Hard Rock genre only (as an example - you can use any genre in the URL below). Note that if you have fewer than 40 songs in the selected genre, then only the number of songs that are actually in your Jamroom will show:
ranking.php?mode=song&order=5&genre=Hard+Rock&show=40&header_template=song_header.tpl&row_template=song_row.tpl&footer_template=song_footer.tpl
List all Genres in your Jamroom
This URL will generate a listing of the Genres that currently have songs in your Jamroom:
ranking.php?mode=song&order=6&header_template=song_header.tpl&row_template=song_row.tpl&footer_template=song_footer.tpl
Extra: Converting from the Jamroom 1.x "rank.php" script
Up until Jamroom 2.60, it was still possible to run the Jamroom 1.x (and 2.1x) “rank.php” script within the Jamroom framework. With the release of version 2.60 though, some of the functions that the old “rank.php” script relied on had to be modified for new features, and in the process the backwards compatibility was broken.
The good news is that upgrading your templates to work with the new “ranking.php” script is very easy to do. Simply follow these steps to upgrade:
-
First, copy the templates that are currently located in the jamroom/rank/(type) directories over to the jamroom/templates/ranking directory. In the jamroom/rank directory you will see sub directories by type - do not use sub-directories within the jamroom/templates/ranking directory - everything goes into the 1 directory.
-
Next, modify the “header”, “row” and “footer” template you want to use, and place a dollar sign ($) within the variables - i.e. {BAND_NAME} would become {$BAND_NAME}. This is because the new templates use Smarty for template parsing, which is much more flexible then the straight HTML of the old templates.
-
Next you will want to construct the new URL to use to generate the ranking page. The “ranking.php” script requires that the header, footer and row template be passed in via the URL, so whereas in the “old” rank.php you could have called it like this:
rank.php?mode-band&order=1
In the new ranking.php you will need to call it like this:
ranking.php?mode=band&order=1&header_template=band_1_header.tpl&row_template=band_1_row.tpl&footer_template=band_1_footer.tpl
While this may seem like more work, it will actually save you A LOT of work in the long run - this way, you can re-use the same set of templates (or just the row template, etc) and not have to create a seperate header, row and footer template for each “order” the ranking.php can be given.
That’s it - now you will just want to update any links that point to the “old” rank.php script with links to the new ranking.php script, and you’re done.
|
