D6: Rating and voting

D6: This chapter shows how to use modules from the Voting API and the Rate projects to add a simple rating function to a website.

Table of contents

• Adding simple ratings

Drupal modules discussed in this chapter: Rate, Voting API.

Setting up

Next, download and install the Voting API package and the Rating package from the Drupal site. Both will be grouped together in the Voting section. Enable the Rate and Voting API modules. We will not need Rate expiration, so leave that disabled.

Adding simple ratings

The Fivestar module provides functionality for acquiring a score that can be used to rate things. Together with the Voting API module, this can be used to let users rate the DSLR cameras listed.

Global settings for the Voting API module is under Administer » Site configuration » Voting API. The global settings let you set the time limit for anonymous vote rollover, and how often votes should be counted. On a busy site, designers can use this setting to postpone the calculation of vote results to save resources.

Global settings for the Fivestar module is under Administer » Site configuration » Fivestar. The global settings let you select widget display (stars, hearts, flames, etc.) and colour scheme (for custom colour widgets).

In this tutorial, we'll go on using the default setting for both modules, so you don't need to change anything here. But check them out! This will give you an overview of the options that are available.

Before you start to use Fivestar, you should know that the module has two completely separate modes of operation:

1. Entity mode. In this mode, the rating widget lets an end-user rate a particular entity. To enable this mode, you turn it on a special Fivestar ratings panel that is part of each content type. Enabling this mode will make the rating widget appear when a user is viewing a entity (or commenting on a entity). Clicking on the widget registers a vote for that particular entity.
2. Review mode. In this mode, the user is presented with a widget to rate something (i.e. not necessarily the entity itself) while editing a entity. To enable this mode, add a field with field type set to Fivestar Rating to the entity using the CCK.

If you enable Fivestar Comments, in entity mode users have the option of putting the rating in comment instead of the the root entity. This provides a lightweight review facility, because users can write a review of the root entity in the comment and then accompany their review/comment with a rating.

In the review mode, the value of the rating is saved in the entity when a entity is created. What is rated is set explicitly, and is referred to as the voting target.

In this tutorial we are going to use Fivestar Comments in entity mode to let users review the DSLR cameras listed by means of comments. This is much simpler than setting up a full-featured review using review mode, but will have to do for now.

Navigate to Administer » Content Management » Content Types, and click edit in the row for DSLR camera. Scroll down and expand the panel named Fivestar ratings. Tick Enable Fivestar rating and set the other options to determine how the widget is displayed.

Here is a brief run-down of the settings:

• Number of stars - the number of stars to display (2-10).
• Star labels (collapsed group) - edit the textual labels for the ratings.
• Star display style - whether to display average, user vote, or both, in star display.
• Text display style - whether to display average, user vote, or both, in text display.
• Show widget title - show title above widget.
• Allow users to undo their votes - allow users to come back and change or delete their rating.
• Enable feedback during vote saving and deletion - will display an ephemeral status message during saving and deletion.
• Teaser display - how and where to display rating as part of a teaser.
• Full entity display - how and where to display rating as part of a full entity.

The Comment widget panel can be used to display a rating widget when a user posts a comment. The ratings placed in the comments will bee used to calculate an average rate that is displayed in the root entity. We shall use this feature to let users review and rate DSLR cameras. The screen shot below shows how to set this up so that the comment widget appears when the user creates a comment:

Finally, click Save content type to save the settings for the Fivestar ratings widget.

Now, our DSLR camera site is set up. We can go ahead an create content by creating entities about specific cameras, and users can rate these cameras by clicking on the Add new comment tab at the bottom of each camera entity. They can then write in their own review of the camera, and rate it by clicking on the rating widget.

Displaying fields

So far, we haven't paid any attention to how our fields are going to be displayed to users that browse the site.

Almost all the work has been from the Manage fields page. This page let you control how the fields are presented in the form on the content creation page, but this still leaves you with the task of presenting the created content. To to this, click on the Display fields. This takes you to a page with at least two tabs: Basic and RSS.

If you've enabled Search in the Drupal core, there will also be a Search tab that let you set up how the fields should be displayed in search results. The additional tabs use a similar format as the Basic format, and provides functions to customise the display of content in miscellaneous specialised contexts.

The Basic tab lets you define some display parameters that defines how the content shall appear in a Teaser (a shortened version of the content often used as teaser on the front page) and default Full entity display.

Each field and group has a Label column to determine where the label is to appear relative to the data contained in the field. The three options are:

• Above – show the label above the field data.
• Inline – show the label in front of the field data, on the same line.
• <Hidden> – do not show the label.

The Inline option is not available for groups.

The Teaser and Full entity columns have drop-down menus that depends on what underlying field types they are. Rather than listing all the available options in this tutorial, you should familiarise yourself with the different presentation formats by trying out the different options available and observe the effect by looking at the displayed full entity.

The Exclude columns let you exclude the display of a field from the Teaser and the Full entity by ticking the field.

The screen shot below shows how you may set up the display of DSLR camera content:

As always, click Save to save your settings when you are done.

You may notice that the Fivestar rating widget doesn't appear in this list. This is because you use the widget in entity mode, so you're not using the the CCK to add it as a field to the entity (in review mode, it is). In entity mode, the display of the widget is set up within the Direct rating widget and Comment widget discussed in the previous section.

This is how the actual display of a specific DSLR camera may look like:

---

Last update: 2011-01-07 [gh].