Voting API Widgets
A flexible field-based voting system built on Voting API, providing ready-to-use voting widgets including five-star ratings, like buttons, and useful/not useful voting.
votingapi_widgets
Overview
Voting API Widgets extends the Voting API module by providing a field-based voting system that can be easily added to any content entity. The module offers three built-in voting widget types: a five-star rating system with multiple visual themes, a simple like button, and a useful/not useful thumbs up/down widget.
The module leverages Drupal's field system, allowing site builders to add voting functionality to any entity type through the standard field configuration interface. Each voting field can be configured independently with different vote types, rollover windows for both anonymous and authenticated users, and various display options.
All voting interactions are handled via AJAX for a seamless user experience without page reloads. The module provides granular permission control with dynamically generated permissions for each voting field instance, allowing fine-grained access control over who can vote, edit their votes, clear their votes, or manage voting status.
Developers can extend the module by creating custom voting widget plugins using either PHP 8 Attributes or Doctrine Annotations. The plugin system provides a clean architecture for implementing new voting styles with custom forms, values, and display logic.
Features
- Field-based voting system that can be attached to any content entity through Drupal's field UI
- Three built-in voting widgets: Five-star rating, Like button, and Useful/Not Useful voting
- Five-star widget supports 9 different visual themes including CSS stars, FontAwesome stars, Bootstrap stars, and various bar styles
- AJAX-based voting for seamless user interaction without page reloads
- Configurable vote rollover windows to control how frequently users can change their votes (from immediate to never)
- Separate rollover settings for anonymous and authenticated users
- Dynamic permission generation per field instance for voting, editing votes, clearing votes, and managing voting status
- Lazy loading of voting forms using Drupal's #lazy_builder for optimal performance
- Custom vote result functions for calculating field-specific averages, counts, and useful ratings
- Extensible plugin system for creating custom voting widgets using PHP 8 Attributes
- Theme suggestions for vote summary templates allowing widget-specific and entity-specific overrides
- Support for showing results summary alongside the voting widget
- Option to display user's own vote or aggregated results
Use Cases
Article Rating System
Add a five-star rating field to articles allowing readers to rate content quality. Configure the formatter to show results summary and use the 'fontawesome-stars' theme for a polished appearance. Grant anonymous users permission to vote to maximize engagement.
Social Like Feature
Implement Facebook-style like buttons on blog posts or comments. Add a voting_api_field with the 'like' plugin to your content type. The like count displays next to the button, providing social proof and engagement metrics.
Help Article Feedback
Add a 'Was this helpful?' feature to documentation or FAQ pages using the 'useful' widget. Users can vote thumbs up or down, and the aggregated results help identify content that needs improvement.
Product Reviews
Create a product review system with five-star ratings. Use the formatter's 'show_results' option to display average ratings and vote counts. Configure user_window to 'Never' to ensure each user can only rate a product once.
Comment Voting
Add voting to comments to allow community moderation. Users can upvote helpful comments or downvote unhelpful ones using the useful widget, similar to Stack Overflow or Reddit.
Poll-style Content
Create lightweight polls by adding a voting field to a content type. The voting status can be toggled open/closed to control when voting is active, useful for time-limited voting events.
Tips
- Use theme suggestions to customize vote summary templates per widget type or content type. Templates follow the pattern: votingapi-widgets-summary--[plugin]--[entity_type]--[bundle]--[field_name].html.twig
- For high-traffic sites, the lazy loading feature (#lazy_builder) helps improve page load performance by deferring voting form rendering
- The 'show_own_vote' formatter setting is useful on edit forms where you want users to see and modify their existing vote
- When creating custom voting widgets, extend VotingApiWidgetBase and implement the VotingApiWidgetInterface. Use PHP 8 Attributes for plugin definitions.
- Vote rollover settings inherit from Voting API's global settings when set to 'Votingapi default'. Configure site-wide defaults at /admin/config/search/votingapi.
- The module adds a 'field_name' base field to the Vote entity, allowing votes to be associated with specific fields rather than just entity types.
Technical Details
Permissions 4
Hooks 1
hook_votingapi_widgets_voting_api_widget_info_alter
Allows modules to alter the voting widget plugin definitions.
Troubleshooting 6
Download the jQuery Bar Rating library from GitHub (https://github.com/antennaio/jquery-bar-rating) and place it in /libraries/jquery-bar-rating/ directory. The file jquery.barrating.min.js should be at /libraries/jquery-bar-rating/dist/jquery.barrating.min.js.
Ensure the jQuery Bar Rating library is properly installed and the CSS theme files are accessible. Check browser console for JavaScript errors. Clear Drupal caches after installing the library.
Verify that permissions have been granted. Go to People > Permissions and look for 'Vote on type [entity_type] from bundle [bundle] in field [field_name]' permission. Grant this to the anonymous role.
Check the vote rollover window settings in the field configuration. Set 'Anonymous vote rollover' and 'Registered user vote rollover' to 'Never' or an appropriate time interval to prevent duplicate voting.
All voting_api_field instances must be deleted before the module can be uninstalled. Go to each content type's Manage fields page and delete any voting fields first.
Voting results are cached for performance. Try clearing the Drupal cache. If using Views to display results, ensure the View is not cached or has appropriate cache settings.
Security Notes 4
- Permissions are dynamically generated per field instance, providing granular access control. Always review permissions after adding new voting fields.
- Anonymous voting uses IP-based identification which can be circumvented. For critical voting, consider requiring authentication.
- The vote rollover window helps prevent vote manipulation but determined users may still find ways to submit multiple votes.
- AJAX callbacks validate voting permissions server-side, preventing unauthorized votes even if client-side restrictions are bypassed.