You are here

README.txt in Fivestar 8

Same filename and directory in other branches
  1. 5 README.txt
  2. 6.2 README.txt
  3. 6 README.txt
  4. 7.2 README.txt
CONTENTS OF THIS FILE
---------------------

 * Introduction
 * Requirements
 * Installation
 * Configuration
 * Maintainers


INTRODUCTION
------------

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

 * jQuery (1.0 - 1.8) rollover effects and AJAX no-reload voting
 * Customizable star sets
 * Graceful degradation to a HTML rating form when JavaScript is disabled
 * Configurability per node type
 * Anonymous voting support
 * Voting spam protection
 * Easy-to-use integration with Views for lists sorted by rating, or filtered
   by min/max ratings
 * A Fivestar field for use in custom node types
 * An easy-to-use Form API element type for use in other modules

 * For a full description of the module, visit the project page:
   https://www.drupal.org/project/fivestar

 * To submit bug reports and feature suggestions, or track changes:
   https://www.drupal.org/project/issues/fivestar

 * For more information on module usage, visit the documentation guide:
   https://www.drupal.org/docs/8/modules/fivestar


REQUIREMENTS
------------

This module requires the following modules:

 * Voting API (https://www.drupal.org/project/votingapi)


INSTALLATION
------------

 * Install as you would normally install a contributed Drupal module. Visit
   https://www.drupal.org/node/1897420 for further information.


CONFIGURATION
-------------

Fivestar has two configuration modes:

 * End-user rating a piece of content: These settings are located 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 -> Configuration ->
   Fivestar (or go directly to /admin/config/content/fivestar)

2) Activate voting on each content type. For example, if you want Fivestar to
   appear on "Article" nodes, use Administer -> Structure -> Content Types ->
   Article, 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 -> People -> Permissions, and check the
   "Use Fivestar to rate content" checkboxe for the role(s) you'd like.
   You'll find this permission 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 the comment module at
   Administer -> Modules.

2) Visit the content type you want to enable reviews, such as Administer ->
   Structure -> Content Types -> Article, 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 -> Structure ->
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
really simple case, you could just enter the value 10 to always rate on the same
node with nid = 10.

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.


Contributing
------------
Have a sweet set of stars you'd like to contribute to the Fivestar module?
Post them to the issue queue: https://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
https://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.


MAINTAINERS
-----------

Fivestar was designed by Nate Haug and Jeff Eaton.

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

File

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