Creating and Contributing a Fivestar Widget Set

The Fivestar project is always interested in included new sets of stars with the default distribution. If you've created a set of stars you'd like to see included in the Fivestar project, follow the instructions below then create an issue in the Fivestar issue queue. Note that color-enhanced sets will be much more likely to be included than basic sets.

Creating a Fivestar Set

To avoid adding directly to the Fivestar module, you can create a custom module to hold your widget using hook_fivestar_widget found inside fivestar.api.php. A useful guide on this is in the comments of this tutorial.

1. Open your favorite image editor and create an image that is 3 times as high as it is wide. The default size for Fivestar (and the easiest to work with) is 16x48 pixels.

2. Setup guides at 16 pixels and 32 pixels. This splits your canvas into thirds.

3. Create a star icon in the top third. When satisfied, copy it into the middle and bottom thirds of the image. Change the middle and bottom copies to your liking. Fivestar will use the top, middle, and bottom images for each state of the star.

   Top -> Off
   Middle -> On
   Bottom -> Hover

4. Save your image as "star.png" in a new directory. The name of your directory will be the label for your set of stars, spaces are not allowed.

5. Do the same thing for a cancel image, only there are only 2 states for a cancel image, so your image will be 16 pixels by 32pixels. Setup a guide at 16 pixels so your canvas is split in half.

6. Create a cancel icon in the top half. Then duplicate it into the bottom half. The cancel states are simply Off and Hover.

   Top -> Off
   Bottom -> Hover

7. Save your cancel image as "cancel.png" in the directory create in step 4.

8. Create the CSS stylesheet. The easiest way to make this stylesheet is to copy an existing CSS file from another set of stars. The "Basic" set provides an excellent example for a 16x16 star, because it only changes the background image as necessary. If you're making a larger or smaller size for your stars than 16x16 pixels, the "Minimal" and "Outline" sets make for a good example.

Creating a Color Enhanced Fivestar Set

If contributing your set of stars back to the community, creating a color enhanced version of your widget is an excellent way to make the stars usable by a large audience. By slightly extending a basic widget, you can make allow users to customize the colors in your Fivestar set.

1. Similar to a basic star set, create a new image that will be split in thirds vertically. However, color enhanced sets of stars are also split in half horizontally, so you'll actually create 6 stars inside of a single image. The default canvas size for a 16x16 star then is 32x48 pixels.

2. Setup guides at 16 and 32 pixels on the y-axis and another grid at 16 pixels on the x-axis.

3. Using the same method as a basic widget, create stars for Off, On and Hover states on the right side of your image. The stars on the right side of the image will be used as an *overlay*

   While it's okay to use color for the overlay, you'll generally only use white and black to add highlights or shadows to the colors the end-user will choose from the Fivestar settings page.

4. Create matching stars on the left side of the image (also for Off, On, and Hover states). The stars on the left side will be used as the *color mask*. The stars should be entirely black (transparency is okay).

5. Save your image as star-template.png, *make sure to format it as a 24-bit PNG*. Even though the template is a 24-bit PNG (which isn't compatible with IE6), the generated images can be either an 8-bit PNG (with a matte) or 24-bit PNG (if no matte is chosen).

6. Besides the star-template.png image, it's also necessary to make a basic star.png that will serve as a preview on the Fivestar settings page before any colors are chosen. This preview image should be entirely grayscale. For consistency, try to use these suggested default colors:

   • Off: White or 80% Brightness
   • On: 70% or 50% Brightness
   • Hover: 40% Brightness

7. Repeat steps 1 through 6 for the cancel image, only with a 32x32 pixel image for the Off and Hover states. Save the final images as cancel-template.png and cancel.png.

8. Create a CSS file for your star set. The format is identical to a basic star set. After new colors are chosen, the star-template.png and cancel-template.png are converted to star.png and cancel.png, replacing the default grayscale ones.