modules/fivestar/README.txt

// $Id: README.txt,v 1.6 2009/05/11 15:56:23 quicksketch Exp $

The Fivestar voting module adds a clean, attractive voting widget to nodes and
comments in Drupal. It features:

 * jQuery rollover effects and AJAX no-reload voting
 * Customizable star sets
 * Graceful degradation to an HTML rating form when JavaScript is turned off
 * Per-nodetype configurability
 * Support for anonymous voters
 * Spam protection to keep users from filling your DB with bogus votes
 * Easy-to-use integration with Views module for lists sorted by rating, or filtered by min/max ratings
 * A Fivestar CCK field for use in custom node types
 * An easy-to-use Form API element type for use in other modules

Fivestar was designed by Nate Haug and Jeff Eaton.

This Module Made by Robots: http://www.lullabot.com


Dependencies
------------
 * votingapi

Fivestar also provides additional features for both the CCK and Views modules.

Install
-------
Installing the Fivestar voting module is simple:

1) Copy the fivestar folder to the modules folder in your installation.

2) Enable the module using Administer -> Modules (/admin/build/modules)

Note: Aggressive caching will complain that fivestar doesn't work, but it
actually causes no problems. To improve performance, the module implements
hook_init() -- and the caching advisor screen uses that as the only metric to
determine whether a module will work with the caching system. Activate it
without fear, friends -- Fivestar will continue to hum happily along.

Upgrading from Drupal 5
-----------------------
The Drupal 6 version of VotingAPI has been significantly improved for both
efficiency and flexibility. Because Fivestar depends on VotingAPI for much of
its functionality, these changes have affected Fivestar.

The Fivestar Anonymous vote interval set in admin/settings/fivestar is no
longer available. We use the same setting as defined in VotingAPI now, set at
admin/settings/votingapi. It has the same effect as the previous Fivestar
setting.

Configuration for Simple Rating
-------------------------------

Fivestar has two completely separate modes of operation. The first is letting an
end-user rate a piece of content. The settings for this are on the content type
settings page. These settings let you expose a rating widget when viewing the
node, not editing it. Clicking on the widget registers a vote for that node, and
never anything else.

The configuration for Fivestar is spread between the content type settings page,
Fivestar site settings page, and access permissions. To configure:

1) Configure the site-wide setting for Fivestar, Administer -> Settings ->
   Fivestar.

2) Activate voting on each content type. For example, if you want Fivestar to
   appear on story nodes, use Administer -> Content Management ->
   Content Types -> Story, and check the "Enable Fivestar rating" box under
   the "Fivestar ratings" heading. Repeat for each content type desired.

3) Enable anonymous voting.
   If you want to allow anonymous voting, you'll need to set permissions for
   that. Use Administer -> User Management -> Access Control, and check the
   "rate content" and "view ratings" checkboxes for the roles you'd like.
   You'll find these permission items under the "fivestar module" heading.

Configuration for Reviews of Content
------------------------------------

Fivestar can be used to quickly setup a rating system for your site visitors to
review a piece of content. When enabling the Comment widget, visitors will
submit a rating on the *original piece of content* along with their comment.
Visitors will not be rating the comments themselves. Fivestar does not allow for
the rating of comments.

1) If it's not already enabled, turn on comment module at Administer ->
   Site Building -> Modules.

2) Visit the content type you want to enable reviews, such as Administer ->
   Content Management -> Content Types -> Story, and select an option under
   the "Comment widget" section.

Configuration as a CCK field / Advanced Rating
----------------------------------------------

Fivestar has extensive CCK support, which makes it so that the user is presented
with a widget to rate some node with the widget while editing a node. It does
not necessary rate the current node, nor does it rate anything if no value is
entered in the Node ID field when configuring the CCK field. The value is
saved in the node (so when you edit it it is still there), but no vote is
registered in VotingAPI without the Node ID field filled out.

An example of a situation where you might want to use the CCK fivestar field is
creating a node type called 'review'. This review type would let users rate
some particular node, and accompany their rating with a review. This could be
combined with a standard rating on the target node, so that some users could
rate the target node using the simple method, or write a complete review to
accompany their rating.

To configure a CCK field for rating a node while creating a new 'review' node:

1) Create a new node type called 'review' at Administer -> Content Management ->
Content Types. Configure the type. Do NOT set any fivestar settings on the
content type form! We don't want users to actually be able to rate the reviews
themselves!

2) Edit your new content type, then click on the "Add Field" tab while on the
content type form. Add a field called 'rating' to your new type, make it of type
Fivestar Rating with the Stars radio button.

3) Configure the rating widget to your liking. Most field have help text which
explain their purpose. The Node ID field is the most important field on the page
which determines exactly what node will receive the value of the rating. In a
realy simple case, you could just enter the value 10 to always rate on the same
node with nid = 10. Usually you'll need to enter PHP code to dynamically select
what node you want to rate.

A common scenario is using fivestar with nodecomments to make reviews. If using
nodecomments a separate checkbox appears the Node ID field to allow you easily
select the nodecomment parent as the target of the vote.

Save your field. Now when making new nodes of type 'review', the user will
select a star that will register a vote on the value of the Node ID field.

Views Integration
-----------------
Fivestar depends on the views integration provided by VotinAPI, but adds some
special features to make it work specifically with Fivestar. To display Fivestar
ratings in a view, select the "VotingAPI percent vote result" from the list of
available Fields. This will display the average vote for nodes. Then choose
"Fivestar rating" from the Handler options for the field and the averages will
be displayed as Fivestar ratings.

Fivestar also provides handling for the display of Fivestar CCK fields, they are
in the Field list under "Fivestar Rating: [Field name]".

Creating a Fivestar Set
-----------------------

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. 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.

7. The two template.png files will tell Fivestar that the set is "color enhanced" and allow users to
   choose new colors for their stars.

Contributing
------------
Have a sweet set of stars you'd like to contribute to the Fivestar module?
Post them to the Fivestar issue queue: http://drupal.org/project/issues/fivestar

Support
-------
If you experience a problem with fivestar or have a problem, file a
request or issue on the fivestar queue at
http://drupal.org/project/issues/fivestar. DO NOT POST IN THE FORUMS. Posting in
the issue queues is a direct line of communication with the module authors.
1	// $Id: README.txt,v 1.6 2009/05/11 15:56:23 quicksketch Exp $
2
3	The Fivestar voting module adds a clean, attractive voting widget to nodes and
4	comments in Drupal. It features:
5
6	* jQuery rollover effects and AJAX no-reload voting
7	* Customizable star sets
8	* Graceful degradation to an HTML rating form when JavaScript is turned off
9	* Per-nodetype configurability
10	* Support for anonymous voters
11	* Spam protection to keep users from filling your DB with bogus votes
12	* Easy-to-use integration with Views module for lists sorted by rating, or filtered by min/max ratings
13	* A Fivestar CCK field for use in custom node types
14	* An easy-to-use Form API element type for use in other modules
15
16	Fivestar was designed by Nate Haug and Jeff Eaton.
17
18	This Module Made by Robots: http://www.lullabot.com
19
20
21	Dependencies
22	------------
23	* votingapi
24
25	Fivestar also provides additional features for both the CCK and Views modules.
26
27	Install
28	-------
29	Installing the Fivestar voting module is simple:
30
31	1) Copy the fivestar folder to the modules folder in your installation.
32
33	2) Enable the module using Administer -> Modules (/admin/build/modules)
34
35	Note: Aggressive caching will complain that fivestar doesn't work, but it
36	actually causes no problems. To improve performance, the module implements
37	hook_init() -- and the caching advisor screen uses that as the only metric to
38	determine whether a module will work with the caching system. Activate it
39	without fear, friends -- Fivestar will continue to hum happily along.
40
41	Upgrading from Drupal 5
42	-----------------------
43	The Drupal 6 version of VotingAPI has been significantly improved for both
44	efficiency and flexibility. Because Fivestar depends on VotingAPI for much of
45	its functionality, these changes have affected Fivestar.
46
47	The Fivestar Anonymous vote interval set in admin/settings/fivestar is no
48	longer available. We use the same setting as defined in VotingAPI now, set at
49	admin/settings/votingapi. It has the same effect as the previous Fivestar
50	setting.
51
52	Configuration for Simple Rating
53	-------------------------------
54
55	Fivestar has two completely separate modes of operation. The first is letting an
56	end-user rate a piece of content. The settings for this are on the content type
57	settings page. These settings let you expose a rating widget when viewing the
58	node, not editing it. Clicking on the widget registers a vote for that node, and
59	never anything else.
60
61	The configuration for Fivestar is spread between the content type settings page,
62	Fivestar site settings page, and access permissions. To configure:
63
64	1) Configure the site-wide setting for Fivestar, Administer -> Settings ->
65	Fivestar.
66
67	2) Activate voting on each content type. For example, if you want Fivestar to
68	appear on story nodes, use Administer -> Content Management ->
69	Content Types -> Story, and check the "Enable Fivestar rating" box under
70	the "Fivestar ratings" heading. Repeat for each content type desired.
71
72	3) Enable anonymous voting.
73	If you want to allow anonymous voting, you'll need to set permissions for
74	that. Use Administer -> User Management -> Access Control, and check the
75	"rate content" and "view ratings" checkboxes for the roles you'd like.
76	You'll find these permission items under the "fivestar module" heading.
77
78	Configuration for Reviews of Content
79	------------------------------------
80
81	Fivestar can be used to quickly setup a rating system for your site visitors to
82	review a piece of content. When enabling the Comment widget, visitors will
83	submit a rating on the original piece of content along with their comment.
84	Visitors will not be rating the comments themselves. Fivestar does not allow for
85	the rating of comments.
86
87	1) If it's not already enabled, turn on comment module at Administer ->
88	Site Building -> Modules.
89
90	2) Visit the content type you want to enable reviews, such as Administer ->
91	Content Management -> Content Types -> Story, and select an option under
92	the "Comment widget" section.
93
94	Configuration as a CCK field / Advanced Rating
95	----------------------------------------------
96
97	Fivestar has extensive CCK support, which makes it so that the user is presented
98	with a widget to rate some node with the widget while editing a node. It does
99	not necessary rate the current node, nor does it rate anything if no value is
100	entered in the Node ID field when configuring the CCK field. The value is
101	saved in the node (so when you edit it it is still there), but no vote is
102	registered in VotingAPI without the Node ID field filled out.
103
104	An example of a situation where you might want to use the CCK fivestar field is
105	creating a node type called 'review'. This review type would let users rate
106	some particular node, and accompany their rating with a review. This could be
107	combined with a standard rating on the target node, so that some users could
108	rate the target node using the simple method, or write a complete review to
109	accompany their rating.
110
111	To configure a CCK field for rating a node while creating a new 'review' node:
112
113	1) Create a new node type called 'review' at Administer -> Content Management ->
114	Content Types. Configure the type. Do NOT set any fivestar settings on the
115	content type form! We don't want users to actually be able to rate the reviews
116	themselves!
117
118	2) Edit your new content type, then click on the "Add Field" tab while on the
119	content type form. Add a field called 'rating' to your new type, make it of type
120	Fivestar Rating with the Stars radio button.
121
122	3) Configure the rating widget to your liking. Most field have help text which
123	explain their purpose. The Node ID field is the most important field on the page
124	which determines exactly what node will receive the value of the rating. In a
125	realy simple case, you could just enter the value 10 to always rate on the same
126	node with nid = 10. Usually you'll need to enter PHP code to dynamically select
127	what node you want to rate.
128
129	A common scenario is using fivestar with nodecomments to make reviews. If using
130	nodecomments a separate checkbox appears the Node ID field to allow you easily
131	select the nodecomment parent as the target of the vote.
132
133	Save your field. Now when making new nodes of type 'review', the user will
134	select a star that will register a vote on the value of the Node ID field.
135
136	Views Integration
137	-----------------
138	Fivestar depends on the views integration provided by VotinAPI, but adds some
139	special features to make it work specifically with Fivestar. To display Fivestar
140	ratings in a view, select the "VotingAPI percent vote result" from the list of
141	available Fields. This will display the average vote for nodes. Then choose
142	"Fivestar rating" from the Handler options for the field and the averages will
143	be displayed as Fivestar ratings.
144
145	Fivestar also provides handling for the display of Fivestar CCK fields, they are
146	in the Field list under "Fivestar Rating: [Field name]".
147
148	Creating a Fivestar Set
149	-----------------------
150
151	1. Open your favorite image editor and create an image that is 3 times as high as it is wide.
152	The default size for Fivestar (and the easiest to work with) is 16x48 pixels.
153
154	2. Setup guides at 16 pixels and 32 pixels. This splits your canvas into thirds.
155
156	3. Create a star icon in the top third. When satisfied, copy it into the middle and bottom
157	thirds of the image. Change the middle and bottom copies to your liking. Fivestar will
158	use the top, middle, and bottom images for each state of the star.
159
160	Top -> Off
161	Middle -> On
162	Bottom -> Hover
163
164	4. Save your image as "star.png" in a new directory. The name of your directory will be the label
165	for your set of stars, spaces are not allowed.
166
167	5. Do the same thing for a cancel image, only there are only 2 states for a cancel image, so your
168	image will be 16 pixels by 32pixels. Setup a guide at 16 pixels so your canvas is split in half.
169
170	6. Create a cancel icon in the top half. Then duplicate it into the bottom half. The cancel states
171	are simply Off and Hover.
172
173	Top -> Off
174	Bottom -> Hover
175
176	7. Save your cancel image as "cancel.png" in the directory create in step 4.
177
178	8. Create the CSS stylesheet. The easiest way to make this stylesheet is to copy an existing CSS
179	file from another set of stars. The "Basic" set provides an excellent example for a 16x16 star,
180	because it only changes the background image as necessary. If you're making a larger or smaller
181	size for your stars than 16x16 pixels, the "Minimal" and "Outline" sets make for a good example.
182
183	Creating a Color Enhanced Fivestar Set
184	--------------------------------------
185
186	If contributing your set of stars back to the community, creating a color enhanced version of your
187	widget is an excellent way to make the stars usable by a large audience. By slightly extending a
188	basic widget, you can make allow users to customize the colors in your Fivestar set.
189
190	1. Similar to a basic star set, create a new image that will be split in thirds vertically. However,
191	color enhanced sets of stars are also split in half horizontally, so you'll actually create 6
192	stars inside of a single image. The default canvas size for a 16x16 star then is 32x48 pixels.
193
194	2. Setup guides at 16 and 32 pixels on the y-axis and another grid at 16 pixels on the x-axis.
195
196	3. Using the same method as a basic widget, create stars for Off, On, and Hover states on the right
197	side of your image. The stars on the right side of the image will be used as an overlay.
198	While it's okay to use color for the overlay, you'll generally only use white and black to add
199	highlights or shadows to the colors the end-user will choose from the Fivestar settings page.
200
201	4. Create matching stars on the left side of the image (also for Off, On, and Hover states). The
202	stars on the left side will be used as the color mask. The stars should be entirely black
203	(transparency is okay).
204
205	5. Save your image as star-template.png, make sure to format it as a 24-bit PNG. Even though the
206	template is a 24-bit PNG (which isn't compatible with IE6), the generated images can be either
207	an 8-bit PNG (with a matte) or 24-bit PNG (if no matte is chosen).
208
209	6. Repeat steps 1 through 6 for the cancel image, only with a 32x32 pixel image for the Off and
210	Hover states. Save the final images as cancel-template.png and cancel.png.
211
212	7. The two template.png files will tell Fivestar that the set is "color enhanced" and allow users to
213	choose new colors for their stars.
214
215	Contributing
216	------------
217	Have a sweet set of stars you'd like to contribute to the Fivestar module?
218	Post them to the Fivestar issue queue: http://drupal.org/project/issues/fivestar
219
220	Support
221	-------
222	If you experience a problem with fivestar or have a problem, file a
223	request or issue on the fivestar queue at
224	http://drupal.org/project/issues/fivestar. DO NOT POST IN THE FORUMS. Posting in
225	the issue queues is a direct line of communication with the module authors.