AnythingRating

From MODx Wiki

Downloads

• Download the [ url download Current Release] - 1.0

Description

Ajax Dynamic Star Rating

Features

• 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
  • Decide if multi-vote is allowed or not
  • Choose if only registered users could vote

• 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
  • Initialize the first rating from a named Template Variable of a document

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, description, image, link) from an other table
  • Style the top rated results you want with the template
  • Display as many you want your top rated lists

Planned Features

• Any suggestion is welcome

AnythingRating installation

• Copy the contents of the file snippet.anythingRating.php into a new snippet named AnythingRating
• Create a directory named anythingRating under the assets/snippets folder.
• Copy the files from the zip into the anythingRating folder.
• Add the following snippet calls:

First on the beginning of each page, a rating group definition :

 [!AnythingRating? &define=`1` &atrGrp=`grpName`!]

where 'grpName' is the rating group name of items you want to rate.

Then anywhere in your page near the item to rate:

 [!AnythingRating? &atrGrp=`grpName` &atrId=`idItem`!]
 

where 'idItem' is the id of each rated item. could be [*id*] or [+maxigallery.picture.id+] with a maxigallery template or any other relevant id you want

And optionaly, if you want display the top rated items on the same page:

 [!AnythingRating? &getTopRated=`1` &atrGrp=`grpName` &topTable=`site_content` &topTitle=`pagetitle`!]
 

where 'site_content' is an example of table where to search the titles of rated items

• May be edit the css/anythingRating.css file and adapt the styles to change how your rating widget looks

• 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
• Look below at the possible placeholders to customize your templates

AnythingRating installation

To change the location of the anythingRating snippet folder:

• change the definition of ATR_PATH in snippet.anythingRating.php

// Path where anythingRating is installed

 define('ATR_SPATH', 'assets/snippets/anythingRating/');

• change the definition of ATR_RELATIVE_BASE_PATH in includes/anythingRating_process.php

 define('ATR_RELATIVE_BASE_PATH','../../../');

• in the js/anythingRating.js file change the _base value:

 var _atrbase = 'assets/snippets/anythingRating/';

AnythingRating Usage

Creating your first contest

In a document:

• Put the snippet call in the beginning of the document content:

 [!AnythingRating? &define=`1` &atrGrp=`grpName`!]

• then for each item to rate:

 [!AnythingRating? &atrGrp=`grpName` &atrId=`anyId`!]

• To show the top rated items:

 [!AnythingRating? &getTopRated=`1` &atrGrp=`grpName` &topTableField=`tableName` &topIdField=`anId` &topTitleField=`aTitle`!]

AnythingRating Parameters

General Parameters

Parameter	Possible values	Default value
&define Define rating group (optional)	0 1	0 (false)
&getTopRated Get top rated items (optional)	0 1	0 (false)

Rating group definition parameters

Parameter	Possible values	Default value
&language Sets the AnythingRating language.(optional) Note: Language files are not fully implemented yet. Feel free to add your language(s). (See english.inc.php for examples.)	english-utf8 francais-utf8	the language set for your MODx manager
&nbStars number of "stars".(optional) The AnythingRating.css should fit with this number	Positive integer	5
&nbIP Number of IP adresses stored. (optional)	Positive integer all	all
&endDate End date to vote.(optional)	date as YYYY-MM-DD unlimited	unlimited
&canVote Comma delimited list of web user group allowed to vote. (optional) The user should be logged-in as user of this web group	Comma delimited list of web user group all	all for a public vote without registration
&multiVote Allow a user to vote many time. (optional)	0 1	0 only one vote is allowed
&atrCss Path & name of the css file to use. (optional)	Path of the css file	assets/snippets/anythingRating/css/anythingRating.css
&atrTpl Name of the template file to use. (optional) @FILE binding allowed	Path of the template file	@FILE:assets/snippets/anythingRating/templates/anythingRating.tpl.html

Rated item Parameters

Parameter	Possible values	Default value
&atrId Unique id for this anythingRating instance.	Any combination of characters a-z, underscores, and numbers 0-9	0
&noVotes Disallow (display votes only) / allow the vote for this item. (Optional)	0 1	0 (false)
&init Initialize the vote with a rating value or from content of a template Variable. (Optional) The content of the TV should contain a rating_value or "rating_value:nb_votes"	A numeric value >=1 and <= &nbStars A data formatted as follow TVname[:DocId]	0

Get Top Rated items

Parameter	Possible values	Default value
&topNb Top number of rated items to be displayed. (optional)	positive integer	5
&topDir Top direction Display the best or the worst rated items (optional)	best worst	best
&topTpl Name of the template file to use to display the top rated list (optional) @FILE binding allowed	Name of the template file to use. (optional)	@FILE:assets/snippets/anythingRating/templates/topRated.tpl.html
&topLabel Label of the top rated item used in the title of top/worst rated results Used by $_lang['atr_bestlabel'] and $_lang['atr_worstlabel'] in language files	Any label	items
&topTable Table name of the rated items. (mandatory)	Any existing table name without MODx prefix
&topIdField Id field of the rated items (mandatory)	id field name	id
&topTitleField Title field of the rated items (mandatory)	Title field name	title
&topDescrField Possible description field of the rated items (mandatory)	Description field name
&topImageField Possible description field of the rated items (optional)	Image field name
topLinkField Possible link field of the rated items (optional)	Link field name

CSS

Look at css/anythingRating.css to style the text and the rating widget Keep in mind that the images folder should be in the same level than the css folder You can change the css file with the atrCss parameter

Placeholders

Here's a list of the available placeholders that could be used or not in the templates.

• anythingRatingTpl
  • to display the rating widget
  • Look for the default content in: assets/snippets/anythingRating/templates/anythingRating.tpl.html

 [+atr.scoreSection+]    score section
 [+atr.intro+]           score introduction label
 [+atr.rating+]          rating value
 [+atr.nbstars+]         number of "stars"
 [+atr.lbstars+]         label for "stars"
 [+atr.nbvotes+]         number of votes
 [+atr.lbvotes+]         label for "votes"
 [+atr.msgSection+]      message section

• topRatedTpl
  • to display the top/worse rating results
  • Look for the default content in: assets/snippets/anythingRating/templates/topRated.tpl.html

 [+atr.groupid+]         rating group name

 [+atr.baseurl+]         web site base url  
 [+atr.ratingid+]        id of the rated item
 

• • Header table:

 [+atr.hdrank+]          label for "rank"
 [+atr.hdscore+]         label for "score"
 [+atr.hdnbvotes+]       label for "nb votes"
 [+atr.hdtitle+]         label for "title"
 [+atr.hddescr+]         label for "descr"     see topDescrField parameter
 [+atr.hdimage+]         label for "image"     see topImageField parameter
 [+atr.hdlink+]          label for "link"      see topLinkField parameter

• • Rated item in the table:

 [+atr.rank+]            rank
 [+atr.rating+]          score (rating value)
 [+atr.nbstars+]         number of "stars"
 [+atr.lbstars+]         label for "stars"
 [+atr.nbvotes+]         number of votes
 [+atr.lbvotes+]         label for "votes"
 [+atr.title+]           title
 [+atr.descr+]           description           see topDescrField parameter
 [+atr.image+]           image                 see topImageField parameter
 [+atr.link+]            link                  see topLinkField parameter

Examples

Feel free to add your own examples to the list.

The following examples have been tested with Firefox 2.0, IE 7.0, Opera and Safari on Windows XP

Rating group definition:

[!AnythingRating? &define=`1` &atrGrp=`photos`!]

• This simpliest snippet call defines the 'photos' 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` &canVote=`travel` &nbIP=`200` &nbStars=`10` &endDate=`2008-06-30` &atrTpl=`@FILE:assets/snippets/anythingRating/templates/travelBookTpl.tpl.html` &atrCss=`@FILE:assets/snippets/anythingRating/css/travelBookCss.css`!]

• This snippet call defines the 'travelbook' rating group with :
  • language set as francais-utf8
  • only web users of the "travel" web group could vote
  • a storage of a maximum of 200 IP addresses of voters per item
  • a widget with 10 images (defined by the css file)
  • 2006-06-30 as the end date for the contest
  • the file travelBookTpl.tpl.html as template file
  • the file travelBookCss.css as css file

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=`travelbooks` &atrId=`[+id+]` &init=`opinion:[+id+]`]]

• where:
  • 'travelbook' is the rating group which regroup the rated items
  • [+id+] is the id of your rated item (travelbook)
  • the initial value of rating come from the TV 'opinion' of the document [+id+]

 (snippet called for example from the Ditto item list template)

[!AnythingRating? &atrGrp=`photos` &atrId=`[+maxigallery.picture.id+]`!]

• where:
  • 'photos' is the rating group which regroup the rated items
  • [+maxigallery.picture.id+] is for example the id of the image you want to rate
  • (snippet called from the maxigallery picture template, to re-use the photo id)
• This 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 from the TV 'opinion'

Get top Rated items:

[[AnythingRating? &getTopRated=`1` &atrGrp=`travelbook` &topTableField=`site_content`&topTitleField=`pagetitle` &topLabel=`travelbooks` ]]

• This snippet call display the top rated items of the 'travelbooks' contest:
  • display the 5 best rated items
  • id, title and description of rated items come from the 'site_content' table
  • id field used is by default 'id'
  • the label used for the title of the top rated results is 'travelbooks'
  • title field use the pagetitle field of the 'site_content' table
  • description, image and link fields are by default not used
  • the default template used is: assets/snippets/anythingRating/templates/topRated.tpl.html

[[AnythingRating? &getTopRated=`1` &atrGrp=`travelbook` &topTableField=`site_content`&topTitleField=`pagetitle` &topLabel=`travelbooks` ]]

• This snippet call display the top rated items of the 'travelbooks' contest:
  • display the 5 best rated items
  • id, title and description of rated items come from the 'site_content' table
  • id field used is by default 'id'
  • the label used for the title of the top rated results is 'travelbooks'
  • title field use the pagetitle field of the 'site_content' table
  • description, image and link fields are by default not used
  • the default template used is: assets/snippets/anythingRating/templates/topRated.tpl.html

[!AnythingRating? &getTopRated=`1` &topDir=`worst` &atrGrp=`photos` &topNb=`3` &topTpl=`@FILE:assets/snippets/anythingRating/templates/anotherTopRated.tpl.html` &topTable=`maxigallery` &topDescrField=`descr` &topImageField=`filename` &topLinkField=`gal_id` &topLabel=`photos`!]

• This snippet call display the top rated items of the 'photos' contest:
  • display the 3 worst rated items !
  • the template used is: assets/snippets/anythingRating/templates/anotherTopRated.tpl.html
  • 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, of the 'maxigallery' table, used is 'descr'
  • image field used is 'filename'
  • link field used is 'gal_id'
  • the label used for the title of the worst rated results is 'photos'

Demo site

More examples on the demo site : http://www.modx.wangba.fr/AnythingRating.html/

Support

>>>>> Support url is incoming ..

For all new posts, thanks the first time to give the following informations:

• AnythingRating snippet version
• AnythingRating snippet calls
• browser type and version (IE, FireFox, Opera, Safari, ...)

and if needed:

• Operating system (Windows / Linux)
• php version
• mysql version

Thanks for your feedbacks.