AnythingRating is coming soon ...
Find below the user documentation of AnythingRating, a snippet to rate what you want ... and organize any kind of contest
I have built this snippet for a photo contest for my wife ’s photo club site. As I haven’t succeed in doing the same thing with cssStarRating & maxiGallery, I have built my own solution. This solution based on an ajax solution, don’t use TVs but store the IP adresses of voters.
This new rating snippet is oriented "contest" with many items to rate. As TVs are not necessary, the contest parameters and contest results could be easily remove by dropping a single table as the contest is finished.
I think to deliver a demo of this snippet
on my site before the end of the week
So feel free for your comments and/or suggestions for any new parameters and/or features.
AnythingRating Readme version 1.0
---------------------------------------------------------------
:: Snippet: anythingRating
----------------------------------------------------------------
Short Description:
Ajax Dynamic Star Rating
Version:
1.0
Created by:
Coroico (www.modx.wangba.fr)
----------------------------------------------------------------
:: Credits
----------------------------------------------------------------
Based on Ajax Dynamic Star Rating 1.6 by Jordan Boesch (www.boedesign.com)
Copyright & Licencing:
----------------------
Licensed under Creative Commons
http://creativecommons.org/licenses/by-nc-nd/2.5/ca/
---------------------------------------------------------------
:: Changelog:
----------------------------------------------------------------
12-Apr-08 (1.0)
-- Initial work based on Star Rating 1.6
----------------------------------------------------------------
:: Description
----------------------------------------------------------------
Uses AJAX Post (simple js script, no JS library like mootools needed)
Unobtrusive (works with javascript disabled)
Use as many rating group you want
Rate as many items you want without any TV definition
Checks not only against IP upon vote but includes also a cookie check
Precise rating to a 2 decimal place
Pre-loads common images
Multi-languages (French, English, ...)
Tested in IE 6, IE 7, Firefox 2.x, Opera and Safari
Rating group - Define your rating group once only per page:
Choose the number of "stars" (or any other image)
Define an end date for the contest
Style the rating information you want with the template
eg: 3.25/5 stars 65% (205 votes)
Change the "star" image by changing the css style sheet
Precise the number of IP addresses stored. Store the more recent addresses
Rate anything you want with a unique id :
Link your rated item to a rating group for contest
Ability to set ’novote’ option to not allow users to vote for this item
Display top rated items of a rating group:
Choose the number of top rated items
Choose to display the "best" or the "worst"
Define the linked information (title and description) from an other table
Style the top rated results you want with the template
Display as many you want your top rated lists
Weary of this contest ? Simply drop the rating group table!
----------------------------------------------------------------
:: General Parameters
----------------------------------------------------------------
&define [1 | 0]
set the definition of a group of rated items
&getTopRated [1 | 0]
display top rated items
&atrGrp [Any combination of characters a-z, underscores, and numbers 0-9 | ’ratings’]
unique rating group name
----------------------------------------------------------------
:: Rating group definition
----------------------------------------------------------------
&language [language_name | manager_language ] (optional)
with manager_language = $modx->config[’manager_language’] by default
&nbStars [ positive integer | 5 ]
number of stars
&nbIP [positive integer | ’all’]
number of IP adresses stored
&endDate [date | ’unlimited’]
end date to vote. By default unlimited in time
&multiVote [1 | 0]
end date to vote. By default unlimited in time
&atrCss [css file | ’assets/snippets/anythingRating/css/anythingRating.css’]
path & name of the css file to use
&atrTpl [template file | ’assets/snippets/anythingRating/templates/anythingRating.tpl.html’]
path & name of the template file to use
----------------------------------------------------------------
:: Rated item
----------------------------------------------------------------
&atrId [ Any combination of characters a-z, underscores, and numbers 0-9 | ’0’]
unique id for this anythingRating instance
&noVotes [1 | 0]
disallow (display votes only) / allow the vote for this item
&init [TV name or rating value | 0 ]
initialize the vote with a rating value or from a Template Variable
the rating value should be beetween 0 and &nbStars
the content of the TV should contain a rating value
by default 0
----------------------------------------------------------------
:: Get Top Rated items
----------------------------------------------------------------
&topNb [positive integer | 5]
top number of rated items to be displayed
&topDir [’worst’ | ’best’]
top direction Display the best or the worst rated items
’best’ by default
&topTable [any existing table name without MODx prefix]
table name of the rated items
&topIdField [id field name | ’id’]
id field of the rated items
’id’ by default
&topTitleField [title field name | ’title’]
title field of the rated items
’title’ by default
&topDescrField [description field name] (optional)
description field of the rated items
&topTpl [template file | ’assets/snippets/anythingRating/templates/topRated.tpl.html’]
path & name of the template file to use to displat the top rated list
----------------------------------------------------------------
:: CSS
----------------------------------------------------------------
Look at css/anythingRating.css to style the text and the rating widget
You can change the css file with the atrCss parameter
----------------------------------------------------------------
:: AnythingRating Mode Example Calls - Rating group definition
----------------------------------------------------------------
[!AnythingRating? &define=`1` &atrGrp=`photos`!]
This simpliest snippet call defines the ’photo’ rating group with :
- a storage of ’all’ IP addresses of voters per item
- a widget with 5 images (define by default css file)
- an ’unlimited’ date for this contest
- language set as the language of the MODx manager
[!AnythingRating? &define=`1` &atrGrp=`travelbook` &language=`francais-utf8`
&nbIP=`200` &nbStars=`10` &endDate=`2008-06-30`
&atrTpl=`assets/snippets/anythingRating/templates/travelBookTpl.tpl.html`
&atrCss=`assets/snippets/anythingRating/css/travelBookCss.css`!]
This snippet call defines the ’travelbook’ rating group with :
- language set as francais-utf8
- a storage of a maximum of 200 IP addresses of voters per item
- a widget with 10 images (define by the css file)
- 2006-06-30 as the end date for the contest
----------------------------------------------------------------
:: AnythingRating Mode Example Calls - Rated item
----------------------------------------------------------------
[!AnythingRating? &atrGrp=`travelbook` &atrId=`[*id*]`!]
where:
- ’travelbook’ is the rating group which regroup the rated items
- [*id*] is for example the id of the current document you want to rate
[!AnythingRating? &atrGrp=`photos` &atrId=`[+maxigallery.picture.id+]`!]
where:
- ’photo’ is the rating group which regroup the rated items
- [+maxigallery.picture.id+] is for example the id of the image you want to rate
These basic calls renders an anythingRating widget
Language, images and display parameters are provided by the rating group `photos`
[!AnythingRating? &atrGrp=`products` &atrId=`[*id*]` &noVotes=`1` &init=`opinion` !]
where:
- ’products’ is the rating group which regroup the rated items
- [*id*] is for example the id of the current document you want to rate
- display the vote only (Votes not allowed)
- initialize the vote with the TV ’opinion’
----------------------------------------------------------------
:: AnythingRating Mode Example Calls - Get top Rated items
----------------------------------------------------------------
[[AnythingRating? &getTopRated=`1` &atrGrp=`landscapes` &topTable=`maxigallery`]]
This simpliest snippet call display the top rated items of the ’landscapes’ contest:
- display the 5 best rated items
- id, title and description of rated items come from ’the maxigallery’ table
- id field and title field used are by default ’id’ and ’title’
- description field is not used
- the default template used is: assets/snippets/anythingRating/templates/atrTpl.tpl.html
[[AnythingRating? &getTopRated=`1` &atrGrp=`travelbook` &topNb=`20` &topDir=`worst`
&topTable=`site_content` &topTitle=`pagetitle` &topDescr=`introtext`
&topTpl=`assets/snippets/anythingRating/templates/topBookTpl.tpl.html`]]
This snippet call display the top rated items of the ’travelbook’ contest:
- display the 20 worst rated items !
- id, title and description of rated items come from the ’site_content’ table
- id field used are by default ’id’
- title field used is ’pagetitle’
- description field used is ’introtext’
- the template used is: assets/snippets/anythingRating/templates/topBookTpl.tpl.html
-----------------------------------------------------------------
:: How-to use this snippet
-----------------------------------------------------------------
1. Copy the contents of the file snippet.anythingRating.php into a new snippet named AnythingRating
2. Create a directory named anythingRating under the assets/snippets folder.
3. Copy the files from the zip into the anythingRating folder.
4. Add the following snippet calls:
First on each page, a rating group definition :
[!AnythingRating? &define=`1` &atrGrp=`movies`!]
where ’tutorials’ is the rating group name of items (here tutorials) you want to rate
then anywhere in your page (usually near the item 
):
[!AnythingRating? &atrGrp=`movies` &atrId=`[*id*]`!]
And if you want display the top rated items on another page:
[[AnythingRating? &getTopRated=`1` &atrGrp=`movies` &topTable=`site_content` &topTitle=`pagetitle`]]
5. May be edit the css/anythingRating.css file and adapt the styles to change
how your rating widget looks
6. May be edit the templates/anythingRating.tpl.html file and adapt the template to change
how your rating widget looks. Do the same with templates/topRated.tpl.html
7. Enjoy anythingRating!
. But this avoid cheating during a short period and for all fixe IP adress users.
