1
|
CONTENTS OF THIS FILE
|
2
|
---------------------
|
3
|
|
4
|
* Introduction
|
5
|
* Requirements
|
6
|
* Installation
|
7
|
* Configuration
|
8
|
* Maintainers
|
9
|
|
10
|
|
11
|
INTRODUCTION
|
12
|
------------
|
13
|
|
14
|
The Fivestar voting module adds a clean, attractive voting widget to nodes and
|
15
|
comments in Drupal. It features:
|
16
|
|
17
|
* jQuery (1.0 - 1.8) rollover effects and AJAX no-reload voting
|
18
|
* Customizable star sets
|
19
|
* Graceful degradation to a HTML rating form when JavaScript is disabled
|
20
|
* Configurability per node type
|
21
|
* Anonymous voting support
|
22
|
* Voting spam protection
|
23
|
* Easy-to-use integration with Views for lists sorted by rating, or filtered
|
24
|
by min/max ratings
|
25
|
* A Fivestar field for use in custom node types
|
26
|
* An easy-to-use Form API element type for use in other modules
|
27
|
|
28
|
* For a full description of the module, visit the project page:
|
29
|
https://www.drupal.org/project/fivestar
|
30
|
|
31
|
* To submit bug reports and feature suggestions, or track changes:
|
32
|
https://www.drupal.org/project/issues/fivestar
|
33
|
|
34
|
* For more information on module usage, visit the documentation guide:
|
35
|
https://www.drupal.org/docs/7/modules/fivestar
|
36
|
|
37
|
|
38
|
REQUIREMENTS
|
39
|
------------
|
40
|
|
41
|
This module requires the following modules:
|
42
|
|
43
|
* Voting API (https://www.drupal.org/project/votingapi)
|
44
|
|
45
|
|
46
|
INSTALLATION
|
47
|
------------
|
48
|
|
49
|
* Install as you would normally install a contributed Drupal module. Visit
|
50
|
https://www.drupal.org/node/1897420 for further information.
|
51
|
|
52
|
|
53
|
CONFIGURATION
|
54
|
-------------
|
55
|
|
56
|
Fivestar has two configuration modes:
|
57
|
|
58
|
* End-user rating a piece of content: These settings are located on the content
|
59
|
type settings page. These settings let you expose a rating widget when
|
60
|
viewing the node, not editing it. Clicking on the widget registers a vote for
|
61
|
that node, and never anything else.
|
62
|
|
63
|
The configuration for Fivestar is spread between the content type settings page,
|
64
|
Fivestar site settings page, and access permissions. To configure:
|
65
|
|
66
|
1) Configure the site-wide setting for Fivestar, Administer -> Configuration ->
|
67
|
Fivestar (or go directly to /admin/config/content/fivestar)
|
68
|
|
69
|
2) Activate voting on each content type. For example, if you want Fivestar to
|
70
|
appear on "Article" nodes, use Administer -> Structure -> Content Types ->
|
71
|
Article, and check the "Enable Fivestar rating" box under
|
72
|
the "Fivestar ratings" heading. Repeat for each content type desired.
|
73
|
|
74
|
3) Enable anonymous voting.
|
75
|
If you want to allow anonymous voting, you'll need to set permissions for
|
76
|
that. Use Administer -> People -> Permissions, and check the
|
77
|
"Use Fivestar to rate content" checkboxe for the role(s) you'd like.
|
78
|
You'll find this permission under the "Fivestar" module heading.
|
79
|
|
80
|
|
81
|
Configuration for Reviews of Content
|
82
|
------------------------------------
|
83
|
|
84
|
Fivestar can be used to quickly setup a rating system for your site visitors to
|
85
|
review a piece of content. When enabling the Comment widget, visitors will
|
86
|
submit a rating on the *original piece of content* along with their comment.
|
87
|
Visitors will not be rating the comments themselves. Fivestar does not allow for
|
88
|
the rating of comments.
|
89
|
|
90
|
1) If it's not already enabled, turn on the comment module at
|
91
|
Administer -> Modules.
|
92
|
|
93
|
2) Visit the content type you want to enable reviews, such as Administer ->
|
94
|
Structure -> Content Types -> Article, and select an option under
|
95
|
the "Comment widget" section.
|
96
|
|
97
|
|
98
|
Configuration as a CCK field / Advanced Rating
|
99
|
----------------------------------------------
|
100
|
|
101
|
Fivestar has extensive CCK support, which makes it so that the user is presented
|
102
|
with a widget to rate some node with the widget while editing a node. It does
|
103
|
not necessary rate the current node, nor does it rate anything if no value is
|
104
|
entered in the Node ID field when configuring the CCK field. The value is
|
105
|
saved in the node (so when you edit it it is still there), but no vote is
|
106
|
registered in VotingAPI without the Node ID field filled out.
|
107
|
|
108
|
An example of a situation where you might want to use the CCK fivestar field is
|
109
|
creating a node type called 'review'. This review type would let users rate
|
110
|
some particular node, and accompany their rating with a review. This could be
|
111
|
combined with a standard rating on the target node, so that some users could
|
112
|
rate the target node using the simple method, or write a complete review to
|
113
|
accompany their rating.
|
114
|
|
115
|
To configure a CCK field for rating a node while creating a new 'review' node:
|
116
|
|
117
|
1) Create a new node type called 'review' at Administer -> Structure ->
|
118
|
Content Types. Configure the type. Do NOT set any fivestar settings on the
|
119
|
content type form! We don't want users to actually be able to rate the reviews
|
120
|
themselves!
|
121
|
|
122
|
2) Edit your new content type, then click on the "Add Field" tab while on the
|
123
|
content type form. Add a field called 'rating' to your new type, make it of type
|
124
|
Fivestar Rating with the Stars radio button.
|
125
|
|
126
|
3) Configure the rating widget to your liking. Most field have help text which
|
127
|
explain their purpose. The Node ID field is the most important field on the page
|
128
|
which determines exactly what node will receive the value of the rating. In a
|
129
|
really simple case, you could just enter the value 10 to always rate on the same
|
130
|
node with nid = 10.
|
131
|
|
132
|
A common scenario is using fivestar with nodecomments to make reviews. If using
|
133
|
nodecomments a separate checkbox appears the Node ID field to allow you easily
|
134
|
select the nodecomment parent as the target of the vote.
|
135
|
|
136
|
Save your field. Now when making new nodes of type 'review', the user will
|
137
|
select a star that will register a vote on the value of the Node ID field.
|
138
|
|
139
|
|
140
|
Views Integration
|
141
|
-----------------
|
142
|
Fivestar depends on the views integration provided by VotinAPI, but adds some
|
143
|
special features to make it work specifically with Fivestar. To display Fivestar
|
144
|
ratings in a view, select the "VotingAPI percent vote result" from the list of
|
145
|
available Fields. This will display the average vote for nodes. Then choose
|
146
|
"Fivestar rating" from the Handler options for the field and the averages will
|
147
|
be displayed as Fivestar ratings.
|
148
|
|
149
|
Fivestar also provides handling for the display of Fivestar CCK fields, they are
|
150
|
in the Field list under "Fivestar Rating: [Field name]".
|
151
|
|
152
|
|
153
|
Creating a Fivestar Set
|
154
|
-----------------------
|
155
|
|
156
|
1. Open your favorite image editor and create an image that is 3 times as high
|
157
|
as it is wide. The default size for Fivestar (and the easiest to work with)
|
158
|
is 16x48 pixels.
|
159
|
|
160
|
2. Setup guides at 16 pixels and 32 pixels. This splits your canvas into thirds.
|
161
|
|
162
|
3. Create a star icon in the top third. When satisfied, copy it into the middle
|
163
|
and bottom thirds of the image. Change the middle and bottom copies to your
|
164
|
liking. Fivestar will use the top, middle, and bottom images for each state
|
165
|
of the star.
|
166
|
|
167
|
Top -> Off
|
168
|
Middle -> On
|
169
|
Bottom -> Hover
|
170
|
|
171
|
4. Save your image as "star.png" in a new directory. The name of your directory
|
172
|
will be the label for your set of stars, spaces are not allowed.
|
173
|
|
174
|
5. Do the same thing for a cancel image, only there are only 2 states for a
|
175
|
cancel image, so your image will be 16 pixels by 32pixels. Setup a guide at
|
176
|
16 pixels so your canvas is split in half.
|
177
|
|
178
|
6. Create a cancel icon in the top half. Then duplicate it into the bottom half.
|
179
|
The cancel states are simply Off and Hover.
|
180
|
|
181
|
Top -> Off
|
182
|
Bottom -> Hover
|
183
|
|
184
|
7. Save your cancel image as "cancel.png" in the directory create in step 4.
|
185
|
|
186
|
8. Create the CSS stylesheet. The easiest way to make this stylesheet is to copy
|
187
|
an existing CSS file from another set of stars. The "Basic" set provides an
|
188
|
excellent example for a 16x16 star, because it only changes the background
|
189
|
image as necessary. If you're making a larger or smaller size for your stars
|
190
|
than 16x16 pixels, the "Minimal" and "Outline" sets make for a good example.
|
191
|
|
192
|
|
193
|
Contributing
|
194
|
------------
|
195
|
Have a sweet set of stars you'd like to contribute to the Fivestar module?
|
196
|
Post them to the issue queue: https://drupal.org/project/issues/fivestar
|
197
|
|
198
|
|
199
|
Support
|
200
|
-------
|
201
|
If you experience a problem with fivestar or have a problem, file a
|
202
|
request or issue on the fivestar queue at
|
203
|
https://drupal.org/project/issues/fivestar. DO NOT POST IN THE FORUMS. Posting
|
204
|
in the issue queues is a direct line of communication with the module authors.
|
205
|
|
206
|
|
207
|
MAINTAINERS
|
208
|
-----------
|
209
|
|
210
|
Fivestar was designed by Nate Haug and Jeff Eaton.
|
211
|
|
212
|
This Module Made by Robots: http://www.lullabot.com
|