Jamroom Logo Jamroom 5 Core
is now Open Source!
Follow Jamroom on Twitter!

This document applies to Jamroom 2 only!
For current Jamroom 4 Documentation, visit the main Jamroom Documentation section.

Overview

The Jamroom Playlist Viewer is a script that will generate a viewable HTML page (based on a template) that contains the songs within a Radio Station playlist. This is commonly used on the Artist Pages so visitors to an artist’s site can “see” what is playing on that artist’s station before playing it.

Configuration

The Jamroom Playlist Viewer consists of a script (playlist.php) as well as templates that control what the output of calls to the script will look like. These templates are located in the jamroom/templates/playlist directory of your Jamroom installation, and use the Smarty templates for their presentation. This affords a great deal of flexibilty to customize the output to your suiting (to match your custom theme for example). To create a new template, it is as simple as creating the file in the template directory, and referencing it via a variable in the URL call to the script.

There is 1 setting in the Jamroom Config that affects the output of the playlist.php script:

Setting Description
Enable Playlist Caching When using the playlist.php script, Jamroom will create the playlist of a Radio Station so it can be included in an Artist’s Site (for example), or wherever it is needed. Some Radio Stations can have very large playlists, causing large SQL queries to be run against the Jamroom database. Enabling the Playlist Caching will cause the output from the playlist.php to be “cached” for a configurable number of seconds, thus reducing the load on busy systems. The length of time the playlist is cached is set in the “Cache Expiration” setting.

Usage

Using the playlist.php script is easy - just call it via a PHP include() function call where you want it (or link to it via an <a href> tag). Usage is as follows:

playlist.php?id=(number)&template=(name.tpl)[&limit=(limit number)]

The options have the following meanings:

Variable Description
id=(number) the id variable tells the playlist script the ID of the Radio Station you want to view the playlist for. This variable is required. The Radio Station ID can be found in the “Modify Station” section of the Artist Menu.
template=(name.tpl) the template variable tells the playlist script the name of the template file that it will be using to display its output through. Note that for security reasons the template file must be located in the jamroom/templates/playlist directory or it will not work. The template is a Smarty template and contains valid HTML, Smarty logic, etc. See the included playlist templates (located in jamroom/templates/playlist) for examples of how a template file looks.
[limit=(limit_number)] the limit variable is an optional argument, although it is recommended that it be used if the number of songs in the radio station exceeds 50. The number input here will LIMIT the number of songs displayed on the output to the number given. Note that on Radio Stations that are set up for Random Play, this list will change dynamically with every call to playlist.php unless the Jamroom Config → Station Settings → Enable Playlist Caching is set to "yes".

Using these options makes it easy to include its output in another PHP page using PHP‘s include() function - i.e.

<php @include(http://yoursite.com/jamroom/playlist.php?id=1&template=nice_template.tpl&limit=20); ?>

Template Variables

General template variables

These Template variables can be used anywhere in the template file.

Variable Description
{$JAMROOM_DIR} The full path to the Jamroom directory
{$JAMROOM_URL} The URL to the Jamroom installation
{$BAND_IMAGE} link to image.php script to generate Band Image - i.e.:
http://yourdomain.com/jamroom/image.php?band_id=(number)&amp;mode=band_image

- use this inside an IMG tag. NOTE: if you would like the band images that are created to be “cached” (this will improve loading time), then in your template you can add the width and height to the {$BAND_IMAGE} variable like this:

src="{BAND_IMAGE}&amp;width=96&amp;height=96"

- this will cause the image to be resized to 96×96 pixels using GD, then the resultant image would be cached - the next load of the same page would use the cached image instead of the full size image.

{$RADIO_ID} The ID Number of the Radio Station
{$RADIO_TIME} The Date/Time the Radio Station was created formatted to Date Format 1 (from Jamroom Config)
{$RADIO_NAME} The Name of the Radio Station
{$RADIO_NAME} The Description of the Radio Station
{$RADIO_NAME} The Radio Station Type (i.e. mp3, wma, etc.)
{$RADIO_LIMIT} The maximum number of songs this Radio Station will output
{$RADIO_BAND_ID} The numerical ID of the artist this Radio Station was created by
{$RADIO_RANDOM} Yes/No whether this Radio Station is randomized
{$RADIO_REPEAT} Yes/No whether this Radio Station is set to repeat
{$RADIO_PLAYS} The number of plays this Radio Station has had
{$RADIO_IMAGE} URL link to image.php script to generate Radio Image - i.e.:
http://yourdomain.com/jamroom/image.php?band_id=(number)&amp;radio_id=(number)&amp;mode=radio_image

- use this inside an IMG tag.

{$RADIO_PLAY_URL} URL to play.php to play the Radio Station. Used in an HTML anchor tag.
{$BAND_NAME} The name of the Artist that created the Radio Station.
{$BAND_MEMBERS} The Artist Members as entered in the Create/Modify Artist form.
{$BAND_LOCATION} The location of the Artist as entered in the Create/Modify Artist form.
{$BAND_QUOTA} The numberical Jamroom Quota ID of the quota the Artist Account belongs to.
{$BAND_INFLUENCE} The value of the Artist Influence field as entered in the Create/Modify Artist form.
{$BAND_SOUNDLIKE} The value of the Artist Sounds Like field as entered in the Create/Modify Artist form.

Song Loop template variables

These template variables can only be used in the inner “song loop” in the template file (see the included sample template files for details).

Variable Description
{$song.ARTIST_URL} The URL to the Artist’s Site
{$song.BAND_ID} The numerical ID of the Artist the song belongs to
{$song.BAND_NAME} The name of the Artist the song belongs to
{$song.BAND_QUOTA} The numerical quota of the Artist the song belongs to
{$song.BAND_INFLUENCE} The Text from the “Artist Influences” field in the Artist Modify section.
{$song.BAND_SOUNDLIKE} The Text from the “Artist Sounds Like” field in the Artist Modify section.
{$song.SONG_NAME} The name of the Song
{$song.SONG_ALBUM} The name of the Album the song belongs to
{$song.SONG_ADVISE} Set to “yes” if the song has explicit lyrics.
{$song.SONG_CREDITS} The information from the Song Credits field on the Song Create/Modify form.
{$song.SONG_ID} The numerical ID of the Song.
{$song.SONG_ISRC} The information from the Song ISRC field on the Song Create/Modify form.
{$song.SONG_ALICENSE} The information from the Song Artist License field on the Song Create/Modify form.
{$song.SONG_SLICENSE} The information from the Song Songwriter License field on the Song Create/Modify form.
{$song.GENRE_NAME} The name of the Genre the song belongs to
{$song.SONG_MODE} hifi/lofi - the mode of the song, wether a HIFI version or a LOFI version
{$song.SONG_IMAGE} link to show this Songs image via image.php:
http://server/jamroom/image.php?band_id=1&amp;song_id=1&amp;mode=song_image

- use this inside an IMG tag. NOTE: if you would like the song images that are created to be “cached” (this will improve loading time), then in your template you can add the width and height to the {$song.SONG_IMAGE} variable like this:

<src="{SONG_IMAGE}&amp;width=96&amp;height=96">

- this will cause the image to be resized to 96×96 pixels using GD, then the resultant image would be cached - the next load of the same page would use the cached image instead of the full size image.

{$song.SONG_IMAGE_NAME} The Name of the Song Image file.
{$song.SONG_MODE} hifi/lofi - the mode of the song, wether a HIFI version or a LOFI version
{$song.SONG_PLAY_URL} URL to the play.php script to play the song - use this as a link for an img tag or href.
{$song.LENGTH} song length in MM:SS (i.e. 01:49)

Solutions Products Support Community Company
Social Media Platform
Social Networking Software
Musician Website Manager
Community Builder
Jamroom 5
Jamroom 5 Modules
Jamroom Marketplace
Support Forum
Documentation
Support Center
Contact Support
Community Forum
Member Sites
Developers
About Us
Contact Us
Privacy Policy
©2003 - 2024 The Jamroom Network