Active_poll Plugin

Finally, I am glad to announce that I have released the active_poll plugin, which by the way, is my first Ruby On Rails plugin. This plugin is intended to provide poll functionality to applications that register the votes associated with users or, if not desired, just count the votes for anonymous participants.

Install plugin

To install it, you have to run the following command:

script/plugin install http://active-poll.googlecode.com/svn/trunk/active_poll

This command will download the plugin code and run a script. The next step is run the generator command:

./script/generate active_poll

This command will run a script that will prompt you which is the name of the model you want to associate with a user vote (typically the User model). If you don't want to track which users made the votes for a particular
poll, you just can configure the poll as anonymous, this way, the
plugin just increments a counter for each selected answer.

This will copy the plugin's files and the corresponding migration into your project. As usual, it means that you will need to run:

rake db:migrate

Create poll

At this point, we got our plugin properly installed. Now, in order to start using it, we got to create our first poll, with the following command:

script/runner vendor/plugins/active_poll/create_poll.rb

The script is intended to configure the poll. It will ask you which are the answers, which is the questions displayed, among other configurations (allows multiple selection, who is allowed to vote: registered users, anonymous, etc.) for the poll.

Show poll in views

For us to see the poll up & running in our application there are three things left to do:

1. Use View helper. Insert the active_poll helper within the views that we want to show the poll, as it is shown below:

#someview.rhtml (where you want to show the poll)..
< %= active_poll ( poll_name, { :in_place => true, :redirect_to => some_url, :view_dir => view_directory }
) %>
..

Where:



• poll_name. This is the name that identifies the poll to display. This is the only required parameter.
  


• :in_place. Enables AJAX functionality to the poll if it is set to true, otherwise the whole page would be reload while submitting a vote.
  


• :redirect_to. This is a url to redirect after the vote.
  


• :view_dir. If present, it loads the poll pages (show_poll, already_vote, user_not_logged, etc) from the directory set by this parameter. Otherwise, all the active_poll pages would be take from the views directory inside the active_poll plugin's folder.
  


2. Insert act_as_vote_handler statement. You have to append act_as_vote_handler statement (highlighted with red in the code below) to the controller that handles the view (where the poll is displayed). Here we can see an example:
   

   
   class SomeController
   ...
    acts_as_vote_handler
   ..
   end
   

   
   
3. Modify routes.rb accordingly. The acts_as_vote_handler hook defines the ap_vote_registered method which effectivity process the votes. For that matter, we have to enable the route for that method on this controller, which would look like this:
   
   

   #routes.rb
   map.connect 'somecontroller/ap_vote_registered', :controller => 'some', :action => 'ap_vote_registered'
   

Views of active_poll

This plugin contains multiple views, the one that would be rendered (using the helper mentioned in the section above) depends of the circumstances. We describe each one of them here:

• after_vote.rhtml. Shows a message after the user votes.
  
• already_voted.rhtml. Shown when the plugin finds out that you already (by means of database for logged users or cookies for anonymous) voted for the current poll.
  
• error.rhtml. This view is rendered by means of an internal error (poll delete while someone is voting, for example)
  
• max_votes_exceeded.rhtml. When the user chooses more options that is allowed in the poll's configuration it shows this view.
  
• no_vote.rhtml. This is rendered when the user press "Vote" but he/she doesn't select any option.
  
• poll_not_found.rhtml. Polls are identified by the name, defined with at the time we run the create_poll.rb script. When we use a the active_poll helper with a poll's name that is not defined in the database we show the poll_not_found.rhtml view.
  
• poll_outdated.rhtml. This view is rendered after the end_date (date of finalization) of the poll is reached.
• show_poll.rhtml. Displays the poll itself, with the appropriate form that submits the vote.
  
• show_results.rhtml. This view shows the current results of the poll.
• user_not_logged.rhtml. It is displayed when the poll is configured to logged users only and the user is not logged in.
  

For aesthetic purposes, you should redefine all the views mentioned above in a new directory (accessed by means of the :view_dir parameter) contained in your application. Also, you should base your customized views in the templates that comes in the views directory, where it is shown how to pass the parameters to the controller, for example.

Check for logged users

This plugin realizes that the current user is logged in by asking the session for the user_id, in this way:

user_model_id = session[:user_model_id]

If this value is set, then it is assumed that the user is logged, otherwise the user is treated as anonymous.

In particular, this methodology integrates transparently with the restful_authentication which uses the same strategy behind the scenes.

Improvment & Comments

If you have any comments, questions, and/or suggestions please don’t hesitate to send me an email here.