Drupal Tutorial: Make Custom Fivestar Graphics

Okay, experts, stop snickering. Yes, the procedure for making custom ratings "stars" for the Fivestar module is pretty darn obvious to anyone who peeks into the module's files. But it doesn't come with those instructions, and I could have saved a little time had there been a few how-to notes.

For the newbie wanting to tackle an easy customization project, this is a good one. You'll add those spiffy "rate this page" stars to your nodes – with said stars being smily faces, check boxes, butterflies, or anything else completely unique to your site alone.

Even stars like mine: the winking offspring of the Drupal icon and the ace of spades.

What's Fivestar?

Fivestar is a simple module that adds a nifty "rating star" widget to your nodes. The module displays a number of stars that you set; a single click from by a reader rates the page with that number (i.e., casts a single vote for that number). You can view the average ratings over all viewers, and find out how popular that node is.

To see an example, look no further than the bottom of this page. See the spade-shaped "stars"? Note the smooth rollover action, courtesy of jQuery. Click, and see your "vote" cast without a page refresh

In addition to adding a bit of "speak your mind" fun for visitors, the significance of the Fivestar rating for a webmaster is obvious: a high rating means "more of this, please!", and a low rating, "no more, thanks".

There are other ways to rate nodes, but Fivestar is one of the quickest and easiest ways to add the feature.

Ah, Fivestar. If you were Tenstar, you'd go to eleven.

Get ready

Installation

Find the module here: http://drupal.org/project/fivestar

Download and install per the README file.

Per that file, note that you'll need to visit three admin locations to fully enable Fivestar:

1) The main Fivestar configuration page. All you set there is choose the sitewide style for stars.

2) The content type page for every node type on which you want the stars to appear. Plenty of options there (though none to change star appearance by node type), all of which are obvious. I missed "Allow users to undo their votes" for a while; without that checked, users who click once on a rating have no chance to undo the choice. With the option checked, users see a "delete" graphic in addition to stars.

3) Access Control. It's always a good habit to visit Access Control after installing any module; there's often a permission to enable before things work as you expect.

Check that everything works. If so, you're ready to customize.

Make me a star!

Ready for the fun part?

1) Open the module and find the folder "widgets". You'll see "hearts" inside, one of the included star designs; let's create new stars from a copy of that.

2) Copy the "hearts" folder to your computer. Rename the folder to a descriptive name for the stars you'll make: "aces" in my example (for my spade-shaped stars).

3) Delete "heart.gif" and "heart_broken.gif" from the folder; we'll make our own replacements for these graphics.

4) Create your star graphics: three images, each 16x16 pixels. Stack them vertically into one new graphic, 16x48 pixels.

The top image is the "no rating" image; a pale or B&W image works well. The middle image marks the rated stars; a colorful image works well. The bottom image is the roll-over image; use something that stands out more than the top image, but less than the middle image.

See the images in the "default" or "hearts" folders for examples.

Name your new 'star' graphic file whatever you like, and save it in the folder we're working in.

4) Create two 16x16 pixel delete images, for users who cancel their ratings. Stack them vertically into one 16x32 pixel image.

The top image is the default image; pale works well. The bottom image is the rollover image.

Name your new 'delete' image file whatever you like, and save it in the folder we're working in.

(Another choice: if you don't see a need to make new graphics for this purpose, just do what I did: copy the delete.gif file from the "default" folder. I'm happy with that.)

5) Edit the .css file in the folder. Change every instance of "heart.gif" to the name of your 'star' image file ("aces.gif" in my case). Change every instance of "heart_broken.gif" to the name of your 'delete' image file ("delete.gif" in my case).

Save and close. Change the name of the .css file if you like.

The contents of my "aces" folder:

6) Upload your new folder to the fivestar/widgets folder in your Drupal installation. Go back to the Fivestar administration page, and you should see your new stars among the offerings.

The finished result:

And that's all there is to it. Any questions?