dga_rating

DGA Rating

A fully compliant, accessible, and user-centric rating widget for Drupal 10 & 11, designed in alignment with the Digital Government Authority (DGA) Design System standards.

This module delivers an elegant, intuitive 1–5 star rating experience with optional written feedback, allowing visitors to easily evaluate services, content pages, or any entity type.
Built with performance, security, and usability in mind, it ensures seamless integration into government-grade digital services.

Design System Compliance: This module implements the Rating Section template from the DGA Design System, following official design guidelines and best practices, ensuring full alignment with national design guidelines, accessibility requirements, and UI best practices.

Features

• Interactive Rating Widget: Star-based rating system (1-5 stars)
• Optional Feedback: Text area for detailed user feedback
• Dynamic Statistics: Automatically calculates and displays:
• Average rating (e.g., "3.9")
• Total number of reviews (e.g., "1544 reviews")
• AJAX Submission: Asynchronous rating submission without page reload
• Entity Support: Can track ratings by entity (node, user, etc.) or by URL
• Anonymous Support: Works for both authenticated and anonymous users
• Accessibility: Keyboard navigation and ARIA labels for screen readers
• Responsive Design: Mobile-friendly layout

Requirements

• Drupal 10.x or 11.x
• PHP 8.1 or higher
• No external dependencies

Installation

1. Download/Clone the module

• Place the dga_rating folder in web/modules/custom/ directory
• Or use Composer: (if published to drupal.org)

2. Enable the module

drush en dga_rating

Or navigate to /admin/modules and enable "DGA Rating"

3. Clear cache
drush cr

Usage

Block Placement

1. Navigate to Structure > Block layout (or your theme's block management)
2. Find the "DGA Rating Widget" block
3. Place it in your desired region (e.g., Content, Sidebar, Footer)
4. Configure block settings as needed
5. Save the block layout

How It Works
The rating widget automatically:

• Detects the current page context (node, URL, etc.)
• Fetches existing statistics (average rating and review count)
• Updates statistics dynamically after each submission

Default View (Closed State):

• Shows average rating (e.g., "3.9")
• Displays total review count (e.g., "1544 reviews")
• Provides a "Rate this service" button

Form View (Open State):

• Primary Question: "How do you rate this service?" - The most important element in the rating section
• Interactive star rating (1-5 stars) - Allows users to provide specific numeric feedback that reflects whether the service is useful or not useful
• Optional feedback textarea
• Links to e-participation statement and rules of engagement
• Submit button

Confirmation View (Submitted):

• Success message: After the user submits the rating, a confirmation page appears showing that the response has been sent successfully
• Shows user's submitted rating
• Updated statistics are reflected in the closed view

Key Design Requirements

1. Rating Question: The most important element is the question "How do you rate this service?" accompanied by the star rating element
2. Numeric Feedback: Specific numbers (1-5 stars) reflect whether the service is useful or not useful, facilitating precise identification of problems or strengths
3. Success Confirmation: After submission, a confirmation message appears showing that the response has been sent successfully
4. Mobile Responsive: In the mobile version, buttons are positioned below the text to ensure a better user experience and smoother formatting on small screens

For full design guidelines, refer to: [DGA Design System - Rating Section](https://design.dga.gov.sa/guidelines/templates/rating-section)

Theming

Override the Template

Copy templates/dga-rating-widget.html.twig to your theme:

your_theme/
  templates/
    dga-rating-widget.html.twig

When overriding, ensure you maintain compliance with the DGA Design System guidelines.

Override CSS

The module includes basic CSS styling following DGA Design System standards. To customize:

1. Add CSS to your theme that targets .rating-widget classes
2. Use CSS specificity or !important to override module styles
3. See css/rating.css for available classes
4. Maintain design system compliance when customizing

Template Variables

Available variables in dga-rating-widget.html.twig:

• average: Average rating (string, e.g., "3.9")
• count: Total number of reviews (integer)
• url: Current URL path (string)
• entity_type: Entity type if available (string or NULL)
• entity_id: Entity ID if available (integer or NULL)

Design System Resources

Official Guidelines: DGA Design System - Rating Section
Template Preview: Available on the design system website
Code Examples: Refer to the design system documentation
Figma Design: Link available on the design system page

Security Considerations

• The module uses Drupal's CSRF protection for AJAX requests
• IP addresses are stored for abuse prevention (can be anonymized if needed)
• Ratings can be submitted by anonymous users (configurable via permissions)
• All user input is sanitized before database storage

Troubleshooting

Ratings not submitting

• Check the browser console for JavaScript errors
• Verify CSRF token is included in requests
• Check database table exists: drush sql-query "DESCRIBE dga_rating;"

Statistics not updating

• Clear Drupal cache: drush cr
• Verify JavaScript file is loading: Check browser Network tab
• Check module is enabled: drush pm:list --filter=dga_rating

Styles not appearing

• Clear cache: drush cr
• Check the CSS file is loading in the browser DevTools
• Verify library is attached (check block build output)

Uninstallation

1. Disable and uninstall the module:
drush pmu dga_rating

Or navigate to /admin/modules, disable and uninstall "DGA Rating"

2. The dga_rating database table is automatically dropped when the module is uninstalled.

Warning:
All rating data will be permanently deleted. If you need to preserve the data, export it before uninstalling the module.