Tuesday, December 9, 2008

Sexy Vote jQuery plugin documentation

Sexy Vote is a jQuery plugin that allows you to embed easily the voting system on your web site. It is very easy to use (as jQuery itself), but you certainly need to have some knowledge about how to configure it (at least how to write callback function that process voting), and of course some basic skills of JavaScript programming.

Usage

To use Sexy Vote, you must follow these steps:

  1. Download the package and unpack it.
  2. Include jQuery to your web page (e.g <script type="text/javascript" src="jquery.js"></script>).
  3. Include plugin file (jquery.sexy-vote-min.js) to your web page (e.g <script type="text/javascript" src="jquery.sexy-vote-min.js"></script>).
  4. Now sexyVote became a native method of jQuery object, and so you can use it as the other jQuery methods. The elements jQuery object contains will be containers for the voting widget. For example, if you write $("#vote").sexyVote(), the voting widget will be rendered inside the element with an ID "vote". You can similarly write $(".vote").sexyVote(), or something else that fit your needs. Sexy Vote also support chaining (as native jQuery methods do), so you can write, for example $("#vote").sexyVote().parent().show() or anything else you need.
  5. You can configure Sexy Vote if you would like to change its appearance or behaviour. To reach this, sexyVote method accepts single parameter in the form of JavaScript object literal. For example, if you write $("#vote").sexyVote({maxScore: 3}), the maximum score user can give will be 3 (so only three stars will be displayed). The full list of configuration options is located in the next section.

Configuring the plugin

Sexy Vote has a number of configuration options that are passed to the sexyVote method in the form of JavaScript object. Here is the complete list of these options.

  • activeImageSrc, passiveImageSrc - the URLs of the images that are displayed in the widget. You will probably need to change the default values of these options. Defaults are "active_star.gif" and "passive_star.gif".
  • maxScore - the maximum score user can give. For example, if you write $("#vote").sexyVote({maxScore: 3}), 3 images (stars) will be displayed and so the user will be able to vote for 3 scores maximum. You will probably not have to change this. Default is 5.
  • fn - the callback function that is called after user have voted (clicked on the image). The function is called in the scope of event target (in this case, the image that was clicked), and two arguments are passed to the function: the event object and score that the user gave. The main purpose of this function is to give to developers the possibility to send the result of the vote to the server, but, of course, you can do anything in this function. Example:
    
    $("#vote").sexyVote({fn: function(e, score) {
        var $this = $(this);
        //now $this is jQuery object that contains the image that was clicked.
        //It is similar to $(e.target)
        alert("You have put " + score + " score. Thank you for voting!");
    }});
    
    
    Default is empty function.
  • messages - this property is an array of strings that are messages displayed in response to user's action right to the images. The message in the zero index is diplsayed when the user have voted (i.e. clicked on the image). The rest of them are displayed when the user hovers on the appropriate image. For example, the message in the first index is displayed when the user places mouse pointer over the first image. Default is ["Your vote have been saved.", "Very bad", "Bad", "Good, but could be better", "Good enough", "Very good" ].

Customizing CSS

Sexy Vote generates the following markup:

<img src="active_star.gif" /><img src="passive_star.gif" />...<span>Messages are displayed here</span>
So if you have placed the widget inside the paragraph with the ID "vote", the markup will look like this:
<p>
<img src="active_star.gif" /><img src="passive_star.gif" />...<span>Messages are displayed here</span>
</p>
According to this, you can customize the appearance of the widget. For example, I included the following stylesheet to the demo page:
#vote span {
    margin-left: 3px;
    font-size: 0.8em;
}

Resources

2 comments:

fazi said...

Hi, is there a possibility to set vote if user have already vote in past ?

raditiya13 said...

around county talked her esteem. Those fully these way nay thing seems. Scarcely on striking packages by so property in delicate. Up.
harga mesin cuci 2 tabung serta artikel harga mesin cuci front loading dan harga mesin cuci top loading juga harga kompor gas merk Quantum dan info harga kompor gas merk Rinnai dan bacaan harga Samsung galaxy V and article spesifikasi samsung galaxy Star Plus dan ulasan Xiaomi Redmi 2 terbaru dan harga samsung galaxy young dan harga laptop asus a456uf terbaru