Overview
The "spotlight" mode to the Jamroom Ranking System is a special mode that works a bit different then the other Jamroom Ranking System "modes", Some things to note:
- The "spotlight" mode is a Song mode - it spotlights Songs in your Jamroom - not Artists. if you have zero songs in your Jamroom, the spotlight mode will not work.
- There are some settings in the Jamroom Config -> Chart and Rank Settings section that impact how the "spotlight" selects songs for the spotlight:
- Spotlight Images - if this is set to "yes", then only songs that have an associated Song Image will be eligible for Spotlighting.
- Spotlight Method - The Spotlight Method tells Jamroom how you want the spotlighted songs to be "rotated".
If you have A LOT of songs in your Jamroom, using the "spotlight" mode can have some advantages over using the "song" mode:
- The spotlight mode is "pre cached" and will typically give better performance on large systems then the "song" mode
- The spotlight mode can "weight" the songs and display them in a "fairer" way then using the "song" mode in Random order.
Ranking Orders
 Ranking Orders are not used by the spotlight mode.
Additional Supported Parameters
In addition to the Common Function Parameters defined in the Jamroom Ranking System Guide, the "spotlight" mode also supports the following additional parameters:
| PARAMETER |
TYPE |
DEFAULT |
DESCRIPTION |
| song_id |
number |
n/a |
The "song_id" parameter tells Jamroom to only return the specified Song ID (s). Multiple Song ID's may be specified either by Template array, or comma separated list. |
| genre |
string |
n/a |
The "genre" parameter tells Jamroom to return only songs that match the given genre(s). Multiple Genres may be given as an array. |
| show |
number |
1 |
By default the Jamroom Song "spotlight" mode spotlights a single song - you can have Jamroom return more then 1 song by setting the "show" to a numeric value greater then 1. |
Available search_area values
search_areas are not used by the spotlight mode.
Template Variables for use in the row_template
In addition to the following Template Variables, you also have access to:
| VARIABLE |
DESCRIPTION |
| {$SONG_RANK} |
The numerical position on the output result set (starting at 1). |
| {$SONG_ID} |
Jamroom Song ID for the Song |
| {$SONG_NAME} |
The name of the Song |
| {$SONG_ALBUM} |
The name of the Album the Song belongs to. |
| {$SONG_LABEL} |
The text from the Song Label form entry. |
| {$SONG_CREATED} |
The 11 digit epoch time the Song was created. |
| {$SONG_UPDATE} |
The 11 digit epoch time the Song was last updated. |
| {$SONG_CREDITS} |
The text from the "Song Credits" field. |
| {$SONG_ADVISE} |
Will be set to "yes" if the Song has been set as having Explicit Content. |
| {$SONG_ISRC} |
The text from the "ISRC Code" field - note that this field will only show in the Create/Modify Song form if "Show License Fields" option is set in the Jamroom Quota. |
| {$SONG_ALICENSE} |
The text from the "Artist License" field - note that this field will only show in the Create/Modify Song form if "Show License Fields" option is set in the Jamroom Quota. |
| {$SONG_SLICENSE} |
The text from the "Songwriter License" field - note that this field will only show in the Create/Modify Song form if "Show License Fields" option is set in the Jamroom Quota. |
| {$SONG_LYRICS} |
The Lyrics for the Song |
| {$SONG_INFO} |
The Song Background/History/Information |
| {$SONG_GENRE} |
The Genre the Song belongs to. |
| {$SONG_IMAGE_URL} |
The HTML URL to use in an <img> tag to display the Song photo. |
|
