By default, you will find links to the Jamroom Rating script embedded within the included Artist Themes in your Jamroom. While this is the typical place to create links to the Rating script, it can be used anywhere there is Jamroom output - this includes the output of the Jamroom Ranking System, Jamroom Search, Jamroom Playlist Viewer, Jamroom Advanced Charts, etc.
There is no direct configuration file for the Jamroom Rating script, however its behavior is influenced by the “Jamroom Ratings” section in the Jamroom Config (Admin Menu → Jamroom Config → Rating Settings). The following options can be set:
- The first method is to use the value from the Artist rating_average column, which is computed only from the numbers reported via the “Rate Artist” form.
- The second method bypasses the Artist Average rating, and instead uses the average value of ALL of the Artist’s Song Ratings.
Also, in the Jamroom Config → Counter and Timer Settings section, you will find the following config option:
Within the Artist Quota settings (Admin Menu → Modify Quota) you can also, on a per Quota basis, set the avilability for that Quota to have Rating Allowed, as well as that Quotas ability to do “Remote Rating”. “Remote Rating” is the ability for an Artist in your Jamroom to create a banner graphic (for example), or a link from an external web page, that when clicked on would allow visitors to THEIR site (not your Jamroom) to also submit a rating to your Jamroom. This can be popular among Artists since it allows them some power over self promotion and gives them a way to round up votes for their Artist Rating.
Displaying the Rating Form
Using the rating.php script is fairly straight forward, and works like many of the other Jamroom scripts. Calling a Rating form for a visitor to fill out from a Jamroom Artist Theme is easy, since Jamroom provides the variables for you to use directly in your Artist Theme templates. To use these variables, simlpy place them within an HTML anchor tag like this
- {BAND_RATING_FORM}
- {SONG_RATING_FORM}
- {MESSAGE_RATING_FORM}
- {RADIO_RATING_FORM}
- {EVENT_RATING_FORM}
- {ITEM_RATING_FORM}
- {PHOTO_RATING_FORM} (Jamroom Power Pack required)
- {VIDEO_RATING_FORM} (Jamroom Power Pack required)
To use these variables, simlpy place them within an HTML anchor tag like so:
<a href="{SONG_RATING_FORM}" {POPUP_JAVALINK}>Rate This Song!</a>
This would create a popup that would contain a Song Rating form. The visitor could choose the Rating they would give to the Song, then when they submit the form, their vote would be recorded.
Note: Once a visitor rates an item in Jamroom, they will not be able to rate that same item again from the same IP address.
The page that is used for the Rating Form is a Smarty based template. By default, since no “template” argument is provided, Jamroom will use the
default rating templates, which are located in the jamroom/templates/rating directory, and are named according to the "type" of item being rated - i.e. "rate_song_form.tpl". You always have the option of passing in your own template name like this:
<a href="{SONG_RATING_FORM}&template=custom_rating.tpl" {POPUP_JAVALINK}>Rate This Song!</a>
By merely adding the &template=(template_name) argument to the variable, it causes the rating.php script to look for a template by that name in the jamroom/templates/rating folder.
Note: For security reasons the template MUST be located within that directory or it will not work. If for any reason Jamroom is unable to locate the template, an error will be shown.
Its recommended that to create your own templates, just copy the default template to a new name and then modify it to your design.
Displaying a Rating Average or Number of Ratings
On your Artist Themes, your Ranking output, etc., you are likely going to want to show the current rating that a Jamroom item has. For the most part, it is recommended that you use the appropriate variables for the method you are using (i.e. use the "ranking" variables provided in the Jamroom Ranking System if you want to include ratings on the output of the Jamroom Ranking System), but if you need to display a rating on a page that is external to Jamroom, you can "pull" this information from Jamroom via a PHP include() statement, or an Apache SSI (Server Side Include).
The format of the URL looks like:
rating.php?mode=(show_rating|show_average)&band_id=(band_id)[&other_id=(other_id)]
The first part of the URL:
mode=(show_rating|show_average)
Means you must define what number you want returned:
- show_rating - this mode will return the number of times the item has been rated.
- show_average - this mode will show the average of the ratings the item has received.
The second part of the URL is for defining the band_id for the Artist you want to view the ratings or average for:
band_id=(band_id)
There is a third, optional part of the URL that allows you to define the "id" of the item that you want to return the rating or average for, and this part will vary depending on the "type" of item you want the numbers for.
The options have the following meanings:
| Option |
Description |
| mode |
The mode option is REQUIRED and tells Jamroom what "mode" you would like the script to operate in. The following "modes" are supported:
show_rating - this mode is used to return the number of ratings an item as received.
show_average - this mode is used to show the average rating an item as received
rating_form - this mode is used for displaying a rating form to a visitor
|
| type |
The "type" option tells Jamroom the type of Jamroom item you are rating. Valid "type" values are:
bands
song
radio
event
item
message
video (required Jamroom Power Pack)
photo (requires Jamroom Power Pack) |
| [template=template.tpl] |
the template variable is an optional argument that allows you specify an alternate Rating template to be used in place of the default templates. Note that the template file MUST be located in the jamroom/templates/rating directory for security reasons. |
To RETRIEVE the current Artist or Song rating value, rating.php should be used like this:
rating.php?mode=(show_rating|show_average)&type=(type)&band_id=(band_id)
The options have the following meanings:
The mode option is REQUIRED and tells Jamroom what rating value to retrieve from the database:
-
song_rating = returns the NUMBER of times the song has been rated
-
song_average = returns the AVERAGE of the song ratings in the database
-
band_rating = returns the NUMBER of times the artist has been rated
-
band_average = returns the AVERAGE of the artist ratings in the database
band_id=(band_id)
The band_id option is REQUIRED and tells Jamroom the Artist ID Number of the Artist rating you want to retrieve. Note that if you are using the “rate_band” mode, then you would use “song_id=0” to indicate you are doing a band rating.
When calling the rating.php like this to RETRIEVE a value from Jamroom’s database, only the VALUE is returned - that means that if you would like to format the output (i.e. the font size, color) you will need to precede or embed the PHP include() or SSI call within your page:
<php @include("http://yoursite.com/jamroom/rating.php?mode=song_average&band_id=25"); ?>
