Pod Ratings
Version 1.0.0 added 1 year ago by sc0ttkclark
HOW TO INSTALL: To install this package, copy the following code and paste it into your Pods >> Package Manager under the Import tab and follow instructions there.
1.0.0 Notes
First version
About this Package
This package lets you easily add a rating field to any Pod type. It comes with a display helper for an AJAX-based five-star rating system, but you can customize it using your own display helper. The implementation for the star rating is similar to the one used at http://podscms.org/
Previously authored by @tokyograph, and taken over by @sc0ttkclark for maintenance / updates.
The package consists of:
- [Pod] rating (used for storing the rating statistics)
- [Pod] rating_vote (used for storing the individual votes)
- [Pod] rating_example (an example Pod using ratings)
- [Page] rating/vote (used for processing the votes)
- [Page] rating/example (example page to list items from the example Pod)
- [Page] rating/example/* (example page to show the detail page for an item from the example Pod)
- [Display Helper] rating/star5 (default helper for star ratings input letting users click a star to vote)
- [Display Helper] rating/show (default helper for showing the current star rating)
To add ratings to a Pod type, just add a new PICK column with 'rating' as the related pod. That's it! The package will handle the data.
To display the ratings, use the display helper 'rating/show'. To allow people to rate an item, use the display helper rating/star5. For example, if you name the column 'rating,' then your template can use the line:
Rating: {@rating,rating/show}
or
Rate this item: {@rating,rating/star5}
If you use PHP and are using the Pod :: pod_helper function, you must provide the field name. For example:
<?php
echo $Record->pod_helper('rating/show', $Record->get_field('rating'), 'rating');
?>
or
<?php
echo $Record->pod_helper('rating/star5', $Record->get_field('rating'), 'rating');
?>
You can include as many ratings on a single page as you want. You can even have multiple ratings fields on the same pod. The display helpers will only include the necessary Javascript and CSS styling a single time.
----------Setup----------
1) Import the package using the Package Manager.
2) In the "rating/vote" Page, there are two configurable variables:
$require_wp_user (restricts voting to logged-in users, default is false)
$allow_vote_change (lets people change their votes, default is true)
3) At the top of the "rating/star5" helper, set $require_wp_user to the same value as above and $star_file_location to point to the place you uploaded your stars20.png file (attached above) or use a custom image for your stars (css modifications may be necessary).
----------Customization----------
If you want to use a range of values besides 1-5, you can change the $vote_min and $vote_max variables in the "rating/vote" Page, you'll also need to adjust the helpers accordingly to support more/less than 5 stars.
If you want to create your own display helper, the "rating/vote" page requires four variables:
'pod' (the name of the pod type)
'id' (the id of the pod item being rated)
'field' (the name of the rating field on the pod type)
'vote' (the numerical value of the rating)
Previously authored by @tokyograph, and taken over by @sc0ttkclark for maintenance / updates.
The package consists of:
- [Pod] rating (used for storing the rating statistics)
- [Pod] rating_vote (used for storing the individual votes)
- [Pod] rating_example (an example Pod using ratings)
- [Page] rating/vote (used for processing the votes)
- [Page] rating/example (example page to list items from the example Pod)
- [Page] rating/example/* (example page to show the detail page for an item from the example Pod)
- [Display Helper] rating/star5 (default helper for star ratings input letting users click a star to vote)
- [Display Helper] rating/show (default helper for showing the current star rating)
To add ratings to a Pod type, just add a new PICK column with 'rating' as the related pod. That's it! The package will handle the data.
To display the ratings, use the display helper 'rating/show'. To allow people to rate an item, use the display helper rating/star5. For example, if you name the column 'rating,' then your template can use the line:
Rating: {@rating,rating/show}
or
Rate this item: {@rating,rating/star5}
If you use PHP and are using the Pod :: pod_helper function, you must provide the field name. For example:
<?php
echo $Record->pod_helper('rating/show', $Record->get_field('rating'), 'rating');
?>
or
<?php
echo $Record->pod_helper('rating/star5', $Record->get_field('rating'), 'rating');
?>
You can include as many ratings on a single page as you want. You can even have multiple ratings fields on the same pod. The display helpers will only include the necessary Javascript and CSS styling a single time.
----------Setup----------
1) Import the package using the Package Manager.
2) In the "rating/vote" Page, there are two configurable variables:
$require_wp_user (restricts voting to logged-in users, default is false)
$allow_vote_change (lets people change their votes, default is true)
3) At the top of the "rating/star5" helper, set $require_wp_user to the same value as above and $star_file_location to point to the place you uploaded your stars20.png file (attached above) or use a custom image for your stars (css modifications may be necessary).
----------Customization----------
If you want to use a range of values besides 1-5, you can change the $vote_min and $vote_max variables in the "rating/vote" Page, you'll also need to adjust the helpers accordingly to support more/less than 5 stars.
If you want to create your own display helper, the "rating/vote" page requires four variables:
'pod' (the name of the pod type)
'id' (the id of the pod item being rated)
'field' (the name of the rating field on the pod type)
'vote' (the numerical value of the rating)