AJAX Star Rating (ASR)

An unobtrusive rating module for Lepton CMS and WebsiteBaker (not tested).

The module's JavaScript is based on the work by Masuga Design,
http://www.masugadesign.com/software/unobtrusive-ajax-star-rating-bar/

Therefore, while this module itself is GPL software, parts of it are under different
licenses.

Features and Benefits
---------------------

As far as I'm concerned ASR is the first real AJAX Rating Module as others
available for the CMS named above invoke a page reload at some time or are very
inflexible when it comes to using them.

With JavaScript turned on in the user's web browser, ASR does the real AJAX thing
so if for instance you use this module to rate a video or audio file, playback won't
stop when rating is triggered.
On the other hand ASR still functions flawlessly with JavaScript turned off, although
in this case a page reload can't be avoided.

A very handy feature is to mark a rating as private so only members of your site
are able to vote, even if the page that contains the rating is public. Private is
off by default

You can add (or even turn existing) rating bars in 'static' state which disables
voting for everyone. Static is off by default.

ASR comes with 3 different CSS presets: a small one with 14px stars, a medium sized
with 20px stars and a larger one with 24px stars. The correct CSS class is automatically
set by chosing the unit width. Default is 20px which looks nicely in most layouts.

ASR supports rating sizes up to 10 stars - if you need more, just add more
classes to the CSS, as ASR can handle any number you feed it with ;-)
Default is five-star-rating, as this is commonly used around the web.

The voters' IP addresses are stored to prevent the same person from voting again
instantly. However, after a default timeout of 6 hrs the IP number will be deleted.
This is done because most people, at least in Europe, don't have permanent IP
addresses and storing these numbers forever would some day prevent random users from
voting, which might lead to a frustrating experience.
Also there are strict privacy laws in most European countries that don't permit
storing IP numbers for more than a few days.

The last important thing: for each rating you have to set a unique ID. This ID
may be up to 25 characters long, supporting just letters from a-z or A-Z (no
umlauts, accents and whatsoever), numbers from 0-9, dash (-) and underscore (_).

Note
----

ASR does not store every single vote, it only stores the totals. This means you
cannot present any statistics displaying the actual ratings over time.
I did so because I wanted to keep DB utilization low and make this module fast.

Usage
-----

Unlike most modules ASR is no page module - it is a snippet. Despite the different
name AJAX Star Rating can be installed like any other module.

To work properly ASR comes packed with a Droplet which will be installed automatically
in Lepton; if in WebsiteBaker this doesn't work, please follow these steps:
1. Unpack ASR to you harddrive
2. Open \install\asr.php with an editor and copy the entire code
3. In WebsiteBaker backend open the 'Admin Tools' tab and click on 'Droplets'
4. Create a new droplet named 'asr', paste the copied code to it and save

NOTE THAT WITH EVERY UPDATE THE DROPLET WILL BE OVERWRITTEN IN LEPTON!
IF YOU HAVE APPLIED MANUAL CHANGES PLEASE BACK UP YOUR DROPLET!


Once you have both parts installed properly, just go and add the droplet to
one of your pages. Possible parameters are:
id = Unique Identifier (up to 25 characters)
u = number of rating units (up to 10)
s = static (no rating possible); true/false or 1/0
p = private (logged-in users only); true/false or 1/0
w = unitwidth (width of star); CSS-presets for 14, 20 and 24

Minimum call: [[asr?id=thisid]]
This adds a five star rating bar of 20px sized stars, which isn't private, nor static

Full call:    [[asr?id=myid&u=7&s=1&p=1&w=14]]
This adds a seven star rating bar of 14ps sized stars which is private and static