Overview
The Jamroom Power Pack features a “commenting” script (comment.php) that you can use to allow visitors to your Jamroom site to add comments to various “items” in your Jamroom - artists, songs, events, store items, messages and more! This feature can really help build a “community” of users centered around your artists and your site.
Configuration
After the Jamroom Power Pack and comments have been installed, it’s fairly simple to integrate it in to your existing Artist Themes or template files. There are 2 settings in the Jamroom Quota configuration that impact the configuration of the comment.php script:
-
Allow Comments - If this is set to “yes”, then artists that are members of this Quota Plan can have Artist Comments on their Artist Page.
-
Allow Comment Editing - If this is set to “yes”, then artists that are members of this Quota Plan can delete the Artist Comments that have been placed on their Artist Page.
These 2 settings allow you on per-quota basis to enable those quotas that will have access to use the Jamroom Comments on their Artist Page.
If you set the “Allow Comment Editing” to yes, you will need to create a Jamroom Custom Button that gives the artist the link to the Edit Comments interface. To do this, create a new Custom Button with the following details:
-
Button Label - set this to “edit comments” or whatever text string you would like to use to define the action.
-
Button URL - set this to: comment.php?mode=edit_comments
-
Button Quota - choose the Jamroom Quota this button should be made available to.
-
Save your new Custom Button.
This will give your artists an interface to editing the comments that have been left about their songs or Artist. Note that the Admin has a similar button in the Admin Menu - “Edit Comments” that allows system-wide editing of all comments (including comment searching).
Usage
Using the Jamroom Comments script is fairly easy, and integrates similar to the Jamroom Rating System. You’ll find that for most uses, Jamroom provides a Template Variable for your use in the Artist Themes - i.e. “{SONG_COMMENT_FORM}”, etc. This makes it very easy to simply add your template file that you would like to use to the variable name, and have it create the correct URL link to the comment.php script. Here’s an example from an Artist Theme template file:
<?php if ('{QUOTA_COMMENTS}' == 'yes') { ?>
<img src="{THEME_URL}/images/song_info.png" align="middle" border="0">
<a href="{SONG_COMMENT_FORM}&template=umber_add_comment.tpl"
onclick="popwin(this.href,'name','450','400','no');return false">add a comment!</a>
<?php } if ({SONG_COMMENT_COUNT} > 0) { ?>
<i>(<a href="{SONG_COMMENTS_URL}&template=umber_view_comments.tpl"
onclick="popwin(this.href,'name','450','400','no');return false">{SONG_COMMENT_COUNT} comments</a>)</i>
<?php } ?>
Here you can see the use of the {SONG_COMMENT_FORM} theme variable. This variable will be automatically expanded by Jamroom when the Artists page is rebuilt, so it contains the correct URL needed to launch the form interface.
Variables
The comment.php script is very flexible, and depending on how it is called, you can tailor the output to the location you want to show comments.
| URL Variable |
Description |
| mode=(option) |
The “mode” variable tells the comment.php script what the action is that you would like the comment.php script to take. The most common mode is “view_comments”, and it is what is passed into the script when you want to view the comments that already exist for a given item. Available modes are: “view_comments” and “add_comment”. Using these two modes gives you the ability to add new comments, and view existing comments. |
| type=(type) |
The “type”URL variable tells the comment.php script which type of comment you would like to view, and is only used with the “view_comments” mode. Available “types” are: band, song, radio, event, item and message. You can also use video and photo modes if you have the Jamroom Power Pack installed. This “type” is REQUIRED if you want to ensure the correct comments are selected for viewing. |
| band_id[]=(number) |
This variable tells the comment.php the band_id you would like to view comments for. If the band_id is NOT given, then comments for ALL artists are returned. Note that this variable supported multiple band_id’s when passed in as URL array - i.e. &band_id[]=1&band_id=2 ... etc. |
| song_id=(number) |
This variable tells the comment.php script that you want to retrieve comments for a specific song_id. This variable is only valid when called with the song mode. |
| radio_id=(number) |
This variable tells the comment.php script that you want to retrieve comments for a specific radio_id. This variable is only valid when called with the radio mode. |
| event_id=(number) |
This variable tells the comment.php script that you want to retrieve comments for a specific calendar event_id. This variable is only valid when called with the event mode. |
| item_id=(number) |
This variable tells the comment.php script that you want to retrieve comments for a specific Store item_id. This variable is only valid when called with the store mode. |
| message_id=(number) |
This variable tells the comment.php script that you want to retrieve comments for a specific Blog entry message_id. This variable is only valid when called with the message mode. |
| video_id=(number) |
This variable tells the comment.php script that you want to retrieve comments for a specific Video video_id. This variable is only valid when called with the video mode, and if the Jamroom Power Pack is installed. |
| photo_id=(number) |
This variable tells the comment.php script that you want to retrieve comments for a specific Photo photo_id. This variable is only valid when called with the video mode, and if the Jamroom Power Pack is installed. |
| quota_id[]=(number) |
This URL variable tells the comment.php script to only return comments for Artists who’s Jamroom Quota ID is given. Note that this variable can be given as a URL array, so multiple quota_id’s may be passed in. |
| show=(number) |
The “show” variable limits the number of comments returned to the number given. |
Template Files
The Jamroom Comment script’s input and output is handled by Smarty templates, so it is completely customizable.
Comment Input Form Template
The comment.php script requires a template file to be given to it for showing all output and input - note the addition of the “&template=umber_add_comment.tpl” argument to the {SONG_COMMENT_FORM} variable. This variable is required and tells the comment.php script the name of the template to use for presenting the input interface in. Note that the template file must be located in the jamroom/templates/comment directory, or it will not be parsed or seen by the comment.php script. Here’s an example INPUT FORM (i.e. the input form is the form that you gather the information on from the user) template 1):
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Send the Artist a Message!</title>
<link rel="stylesheet" type="text/css" href="{$JAMROOM_URL}/themes/jm_umber_2.4/page.css">
</head>
<body class="thBody">
<table class="thStoreTable" style="width: 100%">
{* check for $SUCCESS - if set, we know the form has already been submitted - show the viewer the success message *}
{if isset($SUCCESS)}
<tr>
<td width="100%" class="thMsgB" style="text-align: center">
{$SUCCESS}
</td>
</tr>
<input type="button" value="close this window" onClick="javascript:window.close();" style="width: 150px; font-size: 11px">
{else}
<form method="post" target="_self" action="{$JAMROOM_URL}/comment.php?mode=save_comment">
{* NOTE: name of template required as a hidden field or else errors will not work! *}
<input type="hidden" name="template" value="umber_add_comment.tpl">
<input type="hidden" name="error_template" value="umber_add_comment.tpl">
<input type="hidden" name="band_id" value="{$BAND_ID}">
<input type="hidden" name="song_id" value="{$SONG_ID}">
{* check for an error returned (i.e. no subject, invalid email address, etc.
Note that the variable "$ERROR" will be set if we have an error *}
{if isset($ERROR)}
<tr>
<td width="100%" class="thMsgB">ERROR! {$ERROR}</td>
</tr>
{/if}
<tr>
<td width="100%" class="thStoreL">
Your Email Address<br>
<input type="text" name="c_email" value="" maxlength="60" style="width: 100%; font-size: 10px; background-color: #DDDDDD">
</td>
</tr>
<tr>
<td width="100%" class="thStoreL">
Your Nickname<br>
<input type="text" name="c_nick" value="" maxlength="60" style="width: 100%; font-size: 10px; background-color: #DDDDDD">
</td>
</tr>
<tr>
<td width="100%" class="thStoreL">
Your Comment<br>
<textarea name="c_body" rows="8" style="width: 100%; font-size: 11px; background-color: #DDDDDD"></textarea>
</td>
</tr>
<tr>
<td width="100%" class="thStoreL" valign="middle" style="vertical-align: middle">
Show E-Mail Address?<br>
<input type="checkbox" name="c_show" checked style="font-size: 11px; background-color: #DDDDDD">
</td>
</tr>
<tr>
<td width="100%" class="thStoreL" style="text-align: center">
<input type="submit" value="add your comment" style="width: 130px; font-size: 11px">
<input type="button" value="cancel" onClick="javascript:window.close();" style="width: 130px; font-size: 11px">
</td>
</tr>
<tr>
<td width="100%" class="thStoreL" style="text-align: center">
<br><small><i>Note: <u>ALL</u> IP Addresses are logged (yours is {$REMOTE_ADDR}) - please
refrain from using profanity in your comment or you comment will be removed. Thank You!</i></small>
</td>
</tr>
</form>
{/if}
</table>
</body>
</html>
As you can see it is just basically a form interface that asks the visitor for thier name, e-mail address and comment. Your best bet is to start with this form as a “template”, then modify it to suit your needs.
Some notes on specific lines from above:
{* check for $SUCCESS - if set, we know the form has already been submitted - show the viewer the success message *}
{if isset($SUCCESS)}
Since this is a Smarty template file, you will see some logic in the template that gets the template to show a different text and layout, depending on whether or not certain variables are set. The “{$SUCCESS}” variable will only be set if the visitor has submitted the form, and everything “checks out” OK. In this case the comment.php will reload the template, but this time the {$SUCCESS} variable will have a success message in it, which is then displayed to the user.
{* NOTE: name of template required as a hidden field or else errors will not work! *}
<input type="hidden" name="template" value="umber_add_comment.tpl">
<input type="hidden" name="error_template" value="umber_add_comment.tpl">
<input type="hidden" name="band_id" value="{$BAND_ID}">
<input type="hidden" name="song_id" value="{$SONG_ID}">
This set of 4 “hidden” HTML form fields defines some required information that the comments.php script will need when the visitor submits the form:
-
template - this is REQUIRED - it tells the comment.php script the name of the current template, so when it refreshes with a message it knows which template to use.
-
error_template - this is a seperate template that will be shown to the visitor if an error is detected in their entry.
-
band_id - this will be replaced with the correct band_id when it is parsed and presented by the comment.php script.
-
song_id - this will be replaced with the correct song_id when it is parsed and presented by the comment.php script. Note that this value will be set to 0 for Artist Comments.
The names of the form fields are important, and the comment.php script will be looking for them to be named a specific way:
-
c_email - this is used for the visitors email address.
-
c_nick - this is used for the visitors “nickname”.
-
c_body - this is the “body” or text section of the Comment or Guestbook entry.
-
c_show - this is the checkbox that is checked by the visitor if they don’t want their e-mail address shown.
View Comments Template
In order to be able to “view” the comments that have been left for a song/artist, you will want to create a View Comments template file. The best way to do this is to start with the View Comments template file that comes with the Umber Alert Jamroom theme:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>{$BAND_NAME} - comments</title>
<link rel="stylesheet" type="text/css" href="{$JAMROOM_URL}/themes/jm_umber_2.4/page.css">
</head>
<body class="thBody">
<table class="thStoreTable">
{* do our loop for the songs from this playlist *}
{foreach from=$COMMENTS key=key item=comment name=cval}
<tr>
<td width="100%" class="thMsgL">
{if $comment.COMMENT_SHOW == 'yes'}
{$comment.COMMENT_NICK} ({$comment.COMMENT_USER}) - posted: {$comment.COMMENT_TIME|date_format:"%D %T"}
{else}
{$comment.COMMENT_NICK} - posted: {$comment.COMMENT_TIME|date_format:"%D %T"}
{/if}
</td>
</tr>
<tr>
<td width="100%" class="thMsgB" style="font-size: 11px">{$comment.COMMENT_TEXT}</td>
</tr>
{/foreach}
</table>
</body>
</html>
Basically, this template will “loop” over the available comments for a song/artist, and output them. There are “template” variables that can be used within this template file - they are:
General Variables (available anywhere within the template file)
| Variable |
Description |
| {$JAMROOM_URL} |
This is the URL to your Jamroom directory. |
| {$BAND_NAME} |
The name of the Artist which the comments belong to. |
| {$BAND_ID} |
The numerical Band ID of the Jamroom Artist. |
| {$ARTIST_URL} |
The URL to the Jamroom Artist Page for this artist. |
Comment Loop Variables (only available within the Smarty {foreach} loop within the template)
| Variable |
Description |
| {$comment.COMMENT_SHOW} |
This will be set to “yes” if the user selected that they wanted their email address shown on the output, or set to “no” if they indicated they wanted their e-mail address hidden. NOTE: If this is set to yes, the e-mail address will be obfuscated so their e-mail address is not readable by spam bots. |
| {$comment.COMMENT_NICK} |
This is the “nickname” the user chose when posting the comment. |
| {$comment.COMMENT_TIME} |
This is the timestamp for when the comment was posted. NOTE: This value is in UNIX epoch time, so you will need to use the Smarty date_format variable modifier to present it in the format you choose. |
| {$comment.COMMENT_TEXT} |
This is the actual text of the comment. |
Once you have created your “View Comments” template, you’ll need to modify your Artist Theme template to include the proper template name. For example, if you named the template “my_view_comment.tpl”, you would first ensure that the template file was located in the jamroom/templates/comment directory, then you would modify your Artist Theme template (in this case song_footer.tpl) to call it correctly:
<?php } if ({SONG_COMMENT_COUNT} > 0) { ?>
<i>(<a href="{SONG_COMMENTS_URL}&my_view_comment.tpl" onclick="popwin(this.href,'name','450','400','no');return false">{SONG_COMMENT_COUNT} comments</a>)</i><br>
<?php } ?>
Note how the name of the template was added to the {SONG_COMMENTS_URL} Artist Theme variable. Since Jamroom will expand the {SONG_COMMENTS_URL} in to the correct URL to point to your comment.php script, all you need to do is add the template in and your set.
1) taken from the “Umber Alert” artist theme
|
