Revision History
27/01/11 V1.0.0 Original Release
26/05/11 V1.0.1 Small bug fix
26/06/11 V1.0.2 paRate can now optionally add/subtract Jamroom credits
12/07/11 V1.0.3 Small bug fix. Modified ProJam2 skin and theme templates included.
20/07/11 V1.0.4 Order by rating time added to the ranking function
Overview
The paRate module provides up to five "5 Star" ratings (and associated rating legends) for every Jamroom item (songs, videos, bands etc.). It can also be configured to rate custom module items, eg. jrYouTube or any other item where the custom module creates a database table for its items.
Module Installation
Copy the paRate.php file and the 'modules' folder to your Jamroom directory
Log into Jamroom as admin, go to the Module Config page and enable this module
Installation should now be complete, however, if not running Jamroom V4.1.5 or later, you may need to run the Integrity Check to install this module correctly
Skin and Theme Templates
In order to show Ratings in your skin and user profile pages, templates need to be modified
Included with this module are the modified template for the 'stock' ProJam2, Nova, Cobalt3, and Sage skin and themes
If you are running any of the above 'stock' skins and themes, just copy the templates from this package as appropriate
If you are running any of the above 'stock' skins and themes that have only had their CSS files changed as a colour scheme, say, it should be OK to copy these modified files, BUT BE SURE TO BACKUP FIRST
If you are not running stock skins and themes, or have modified your video templates in any way, check out the included templates to see what is required - BE SURE TO BACKUP BEFORE MAKING ANY CHANGES
Upgrading This Module
Overwrite all your previously uploaded module files with those in the latest release.
Log into your Jamroom site as 'Admin' and if prompted to do so, run the Integrity Check
Module Configuration
Firstly, it is likely that you'll want to disable the existing Jamroom rating system (though it would still work in parallel with this module's rating system). Go to each of your quota configuration pages and in the Site Features section, disable the Jamroom ratings. Then, scroll to the bottom of the page to enable this modules rating system for the quota.
If you want to import all your existing Jamroom ratings into this module's rating system, go to your control panel Tools section and click on 'PaRate Ratings Import'. All existing Jamroom Item ratings will go into this modules rating number 5 fields.
The module will work 'out of the box' using a set of default 'Rating Legends' for each Jamroom item.
If you want to edit these, go to your control panel Tools section and click on 'PaRate Rating Legend Manager'. All 'Rating Legend Sets' have a quota associated with them so that different quotas can have different legends (for artists, DJs, producers etc.). Editing and creating new legend sets should be self explanitary from this page!! Note that you do not need to use all 5 legends for every item. If a legend is left blank, it can be tested for in the templates and not shown.
The module can also list rated items with a ranking call (see below). If you want to rank rated custom module items, you need to tell this module about its database table. Go to your control panel Tools section and click on 'PaRate Custom Table Manager'. There you need to add information on the table name, its ID field name, and the 'Key Word' that will be used within this module to specify the custom module item.
Module Ranking Call
{jr_ranking mode="paRate" item_type="song" . . . }
The item_type variable is optional and can be band, member, user, radio, event, item (for the store item), video, channel, image, vault or song. It can also be a specified Key Word for custom module items. If not used, all rated items will be returned from the ranking call.
Ranking orders are 1 => by overall_rating_average DESC, 2 => by overall_rating_average ASC, 3 => by overall_rating_number DESC, 4 => by overall_rating_number ASC, 5 => by rating_type ASC, 6 => by rating_type DESC, ASC, 7 => by rating_time ASC, 8 => by rating_time DESC
band_id and quota_id can also be specified in module ranking calls.
Rated items can be searched by item_type in the module ranking call.
All other regular ranking parameters can be used - show, pagebreak, pagenum, templates.
Module Smarty Functions
The module includes two smarty functions for use in your templates - paRate_get and paRate_rating_form
{paRate_get item_type="song" item_id=$SONG_ID quota=$BAND_QUOTA assign="_r"}
All parameters are required, including the assign as its to this value that the returned array containing all the item's rating data is named. See one of the included templates for more details on this smarty call and for how the returned variables are used.
{paRate_rating_form index="1" . . .}
This is similar to the Jamroom jr_rating_form function (and uses most of the same parameters) and is used to generate either 'star' or 'select' rating forms in your templates. Noted the inclusion of the 'index' variable. This is 1,2,3,4, or 5, is essential, and specifies which of the 5 module ratings this form this apply to. Again, see one of the included templated for details on how this function is used.
Questions?
Email any questions, comments or suggestions to paul@paulasher.com, or post on the Module's Jamroom Forum Thread
Joined: 20 Aug 2003
Posts: 5341
Location: Nottingham, UK
Posted: 01/27/11 02:26
iLoveHouseMusic:
Logged into the demo and have a question - Is there a way to have the stars refresh right after Rating?
Its almost not needed to have the confirmation message.
Maybe a good flow would be Rate, Confirm, auto refresh.
I like this module - this I could definitely use this on iLHM.
That's mostly down to the templates. In Cobalt3 and Sage you can set the popup confirmation to refresh the parent page when the popup is closed. With Nova and its ajax usage, refreshing the parent page will not necessarily show the ratings section again as they may not have been part of the original page.
But I do like your 'flow logic'. Maybe I can come up with something.
Thanks for the feedback.
Pa
Joined: 20 Aug 2003
Posts: 5341
Location: Nottingham, UK
Posted: 06/22/11 03:30
iLoveHouseMusic:
can paRATE somehow tie into Credit Actions for "rate item"??
Good point - I hadn't thought about the credit system. I'll look into it, but I don't think I can include a specific paRate credit option. More likely it'll check if the regular JR rating is set for credits and add/subtract credit based on those settings.
iLoveHouseMusic:
Also - paRate should be added to paAcclaim as far as being part of that ranking calculation.
To be honest, paAcclaim sales don't justify the major work on it that this would involve. I could look into doing something custom for you though?
Joined: 21 Apr 2009
Posts: 1482
Location: San Francisco CA
Posted: 06/25/11 13:02
pa,
I rec'd your PM, i've been busy with class but i should be able to take a look at the module again soon.
Also - Yes, maybe we can do a custom paAcclaim mod for my site.... I want to get it implemented first. I was thinking of using it to help determine the Featured artist for my site. I am trying to somewhat automate that....
Joined: 20 Aug 2003
Posts: 5341
Location: Nottingham, UK
Posted: 06/29/11 10:10
iLoveHouseMusic:
Just purchased. I'll be checking it out this weekend.
I can help you with a ProJam2 template if you want....
Thanks - Check out the included templates for Nova, Cobalt or Sage to see how to integrate this module into the PJ2 templates.
Let me know if you need any help.
Cheers
Pa
Joined: 21 Apr 2009
Posts: 1482
Location: San Francisco CA
Posted: 06/29/11 11:28
I did take a brief look last night.
In a nutshell:
1. Decide whether to disable existing jamroom ratings (and import)
2. Enable the module per quota
3. Modify the Song_Detail template
4. and also the JR_ranking template.
5. Customize my rating categories
just looking for a high level set of directions ... =)
Joined: 20 Aug 2003
Posts: 5341
Location: Nottingham, UK
Posted: 06/29/11 11:54
iLoveHouseMusic:
I did take a brief look last night.
In a nutshell:
1. Decide whether to disable existing jamroom ratings (and import)
2. Enable the module per quota
3. Modify the Song_Detail template
4. and also the JR_ranking template.
5. Customize my rating categories
just looking for a high level set of directions ... =)
That looks about right, except that I'd do them in the order 1,2,5,3,4
That way the rating legends are defined before you do the templates, so that there is less risk of text wrap around or any other oddities due to confined text
hth
Pa
Joined: 20 Aug 2003
Posts: 5341
Location: Nottingham, UK
Posted: 07/12/11 06:48
Version 1.0.3 released.
Small bug fix in the quota configuration.
Sample templates for the ProJam2 skin and theme now included.
Download the latest version from the Jamroom Marketplace.
Cheers
Pa
